Guides

Scan a token and wait

Start a scan, poll politely and get the finished report.

The most common flow: you get a contract address from somewhere and need its Holder Score before acting on it. Start a scan, then poll the report with a growing delay until it is done.

POST /scans returns immediately; the scan runs in the background.
Back off between polls and respect retryAfter on 429.
Stop at DONE or ERROR, or after your own timeout.

Code#

const BASE = "https://app.xca.fun/api/v1";
const headers = {
  Authorization: `Bearer ${process.env.XCA_API_KEY}`,
  "Content-Type": "application/json",
};
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function scanAndWait(address, { timeoutMs = 180_000 } = {}) {
  const start = await fetch(`${BASE}/scans`, {
    method: "POST",
    headers,
    body: JSON.stringify({ chain: "solana", address }),
  });
  if (!start.ok) throw new Error((await start.json()).error.message);

  const deadline = Date.now() + timeoutMs;
  let delay = 2000;
  while (Date.now() < deadline) {
    const res = await fetch(`${BASE}/tokens/solana/${address}`, { headers });
    if (res.status === 429) {
      const { error } = await res.json();
      await sleep((error.retryAfter ?? 5) * 1000);
      continue;
    }
    const report = await res.json();
    if (report.status === "DONE") return report;
    if (report.status === "ERROR") throw new Error(report.errorMessage ?? "Scan failed");
    console.log(`${report.step ?? "queued"} ${report.progress}%`);
    await sleep(delay);
    delay = Math.min(delay * 1.5, 8000);
  }
  throw new Error("Timed out waiting for the scan");
}

const report = await scanAndWait("DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263");
console.log(report.symbol, report.holderScore, report.riskLevel);