Endpoints

Scans

Start a scan of a token or refresh a stale report.

POST/api/v1/scans

Queues a full analysis of a token and returns its current state. The call is safe to repeat: it never starts a second scan while one is running.

Parameters#

chainbody

Chain id. Only solana for now."solana"default: "solana"

addressbodyrequired

Token mint address to scan.string

Request#

curl -s -X POST "https://app.xca.fun/api/v1/scans" \
  -H "Authorization: Bearer $XCA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"chain":"solana","address":"DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263"}'

Try it

API keyGet API keyKept only in this browser tab and sent only to the XCA API.

chainbodyaddressbody

Paste your API key to send a real request.

Response#

status

Scan state."NONE" | "QUEUED" | "RUNNING" | "DONE" | "ERROR"

depth

Depth of the report the scan produces or refreshes."LIGHT" | "FULL" | null

step

Current scan step.string | null

progress

Progress from 0 to 100.number

stale

The existing report is older than its cache lifetime.boolean

upgrading

A LIGHT report is being upgraded to FULL.boolean

limitReached

Your daily scan limit is used up; the state of the older report is returned.boolean

Example response#

{
  "status": "QUEUED",
  "depth": null,
  "step": "queued",
  "progress": 0,
  "stale": false,
  "upgrading": false,
  "limitReached": false
}

Status codes#

200Success

400validation — A parameter or the body is invalid; see error.issues.

401unauthorized — The API key is missing, malformed or revoked.

402planRequired — Your plan doesn't include API access or this feature.

429rateLimited — Too many requests per minute, or the monthly quota is used up.

503unavailable — Maintenance or the data provider is out of capacity.

How it behaves#

Fresh report: returns DONE right away and doesn't use your scan limit.
Scan in progress: returns QUEUED or RUNNING with step and progress.
Otherwise: queues a new scan and uses one scan of your daily limit.
Daily limit reached but an older report exists: returns that report's state with limitReached set to true.

Waiting for the result#

Poll GET /tokens/{chain}/{address} every 3–5 seconds until the status is DONE or ERROR. Most scans finish within a minute.

Scan a token and waitStart a scan, poll politely and get the finished report.

Scan steps#

`queued`	Waiting in the queue.
`market`	Fetching price, liquidity and mint data.
`holders`	Reading the holder list.
`trades`	Reading the earliest trades to find snipers.
`profiles`	Profiling the largest holders: funding, age, PnL.
`classify`	Assigning classes and building clusters.
`dev`	Checking the creator's previous launches.
`save`	Computing the Holder Score and saving.
`done`	Finished.
`error`	Failed.

While XCA is under maintenance or its data provider is out of capacity, scans return 503 unavailable. Retry later.