Documentation

Getting Started

1. Generate a key from API Keys in the dashboard
2. POST /api/sybil/check with your claimant list — you get back a jobId
3. Poll GET /api/sybil/jobs/:id until status is complete
4. Pull the forwardable summary or CSV from /api/sybil/jobs/:id/report

Prefer not to write code? Snapshot Screening in the dashboard runs the same pipeline through a UI.

Authentication

Two accepted credentials, checked in this order: an af_ API key, then the dashboard session cookie. Session users are treated as DEVELOPER tier and aren't counted against any key's quota.

Authorization: Bearer af_your_key_here

OpenAPI Spec

The full route inventory — every endpoint, method, and tier requirement — is available as a machine-readable OpenAPI 3.0 document, generated from the same route source this page used to be hand-transcribed from. Import it directly into Postman, Insomnia, or Swagger UI.

GET /api/openapi.json

Response Shape

Every successful response is wrapped as { "data": ... }, with pagination or other response context under a sibling meta key when present — data is always exactly the resource you asked for, never mixed with metadata about the response itself. Errors are unchanged: { "error": "..." } with a non-2xx status. The CSV report format is the one exception — it returns a raw CSV body, not JSON.

Async Jobs

The three forensics endpoints are enqueue-only. A 500-wallet snapshot fans out to thousands of on-chain lookups, so the work runs on a background worker rather than inside the request. POST → 202 {jobId, poll} → poll until complete or failed.

Status moves pending → processing → complete or failed. Poll every few seconds; there's no webhook yet.

Batch caps per request

Separate from the daily rate limit below — this caps addresses in one call, because addresses are the real unit of upstream cost. Applies to /sybil/check and /consolidation/scan.

Snapshot Screening

1 — Enqueue the snapshot:

curl -X POST https://getalphaflow.xyz/api/sybil/check \
  -H "Authorization: Bearer af_..." \
  -H "Content-Type: application/json" \
  -d '{"addresses": ["Wallet1...", "Wallet2...", "Wallet3..."]}'

# 202 Accepted
# {
#   "data": {
#     "jobId": "clx7f2k9a0001abcd",
#     "status": "pending",
#     "submitted": 3,
#     "poll": "/api/sybil/jobs/clx7f2k9a0001abcd"
#   }
# }

2 — Poll until it completes:

curl https://getalphaflow.xyz/api/sybil/jobs/clx7f2k9a0001abcd \
  -H "Authorization: Bearer af_..."

# while status is "pending" or "processing", wait and poll again.
# on "complete", data holds the result (every success response is
# wrapped in { data }, with optional pagination/context under meta):
# {
#   "data": {
#     "status": "complete",
#     "submitted": 3,
#     "flaggedCount": 2,
#     "clusters": [
#       {
#         "confidence": 0.82,
#         "signals": ["shared_funder", "behavior_match"],
#         "memberCount": 2,
#         "sharedFunder": "Funder...",
#         "members": ["Wallet1...", "Wallet2..."],
#         "smartMoneyMembers": [],
#         "evidence": [
#           {
#             "address": "Wallet1...",
#             "funderAddress": "Funder...",
#             "fundingTxSignature": "5xY...",
#             "commonFeePayer": "Payer...",
#             "behaviorFingerprint": "a91c..."
#           }
#         ]
#       }
#     ],
#     "knownFarmers": [
#       { "address": "Wallet2...", "timesFlagged": 3, "confidence": 0.88 }
#     ],
#     "unclustered": ["Wallet3..."]
#   }
# }

Response fields

Reports

GET /api/sybil/jobs/:id/report turns a completed job into something you can forward or feed to tooling. JSON gives counts, clusters sorted by confidence, a bands breakdown, and a plain-English summary paragraph; ?format=csv gives one row per flagged address. Non-complete jobs return the same status shape as the poll route, so a client can point at this endpoint the whole way through.

# JSON summary — the shape you forward to a protocol team
curl https://getalphaflow.xyz/api/sybil/jobs/clx7f2k9a0001abcd/report \
  -H "Authorization: Bearer af_..."

# CSV — one row per flagged address, for your exclusion tooling
curl "https://getalphaflow.xyz/api/sybil/jobs/clx7f2k9a0001abcd/report?format=csv" \
  -H "Authorization: Bearer af_..." \
  -o sybil-report.csv

# address,clusterIndex,confidence,signals,funderAddress,fundingTxSignature,band

Full enqueue → poll → report loop:

JOB=$(curl -s -X POST https://getalphaflow.xyz/api/sybil/check \
  -H "Authorization: Bearer $AF_KEY" \
  -H "Content-Type: application/json" \
  -d @snapshot.json | jq -r .data.jobId)

until [ "$(curl -s https://getalphaflow.xyz/api/sybil/jobs/$JOB \
  -H "Authorization: Bearer $AF_KEY" | jq -r .data.status)" = "complete" ]; do
  sleep 5
done

curl -s "https://getalphaflow.xyz/api/sybil/jobs/$JOB/report?format=csv" \
  -H "Authorization: Bearer $AF_KEY" -o sybil-report.csv

Bulk Export

The report endpoints above cover one job, case, or wallet at a time. For everything at once, two list-level export endpoints return a summary row per record rather than each record's full detail — pull the per-record report separately for anything that needs deeper inspection.

GET /api/cases/export?format=csv
GET /api/sybil/jobs/export?format=csv

Other Forensics

Consolidation scan — trace known claimants forward to the addresses they swept into. Sinks receiving from 3+ claimants surface as farm treasuries; a sink that is itself a labeled CEX deposit address is its own tell.

curl -X POST https://getalphaflow.xyz/api/consolidation/scan \
  -H "Authorization: Bearer af_..." \
  -H "Content-Type: application/json" \
  -d '{"addresses": ["Claimant1...", "Claimant2..."]}'

# then: GET /api/consolidation/jobs/<jobId>
# result: { claimantsScanned, sinks: [{ address, inflowCount, totalSol,
#           fromClaimants, knownDestination }], unresolved }

Fund-flow trace — follow outbound SOL from any root address, flagging hops that land on known CEX/bridge destinations.

curl -X POST https://getalphaflow.xyz/api/fundflow/trace \
  -H "Authorization: Bearer af_..." \
  -H "Content-Type: application/json" \
  -d '{"address": "SourceWallet..."}'

# then: GET /api/fundflow/jobs/<jobId>

Wallet API

Synchronous reads — these return results inline, no job needed.

Rate Limits

Requests per UTC day. Same numbers api-auth.ts enforces server-side — not a second copy that could drift. Enqueueing a job and each poll both count as one request.

Status & Error Codes

A job that fails during processing is not an HTTP error: the poll route returns 200 with status: "failed" and an error message. Check the body, not just the code.

SDK

Best Practices

• Split snapshots larger than your tier cap into sequential batches — clustering runs per job, so keep wallets you expect to be related in the same batch
• Poll every 3–5 seconds, not tighter; polls count against your daily limit
• Persist the jobId. Results stay retrievable, so a dropped connection never means re-running the batch
• Never auto-exclude on confidence alone — read evidence[] and check smartMoneyMembers first
• /wallet/:address/token-risk and /token-risk/:mint answer different questions — a wallet's own exposure vs. a specific token's risk vectors — check you're calling the right one
• Fund-flow and consolidation only label CEX/bridge destinations that are in the verified registry. An empty knownDestination means unlabeled, not unrelated