Guias

Escaneie um token e aguarde

Inicie um scan, consulte com moderação e receba o relatório pronto.

O fluxo mais comum: você recebe um endereço de contrato de algum lugar e precisa do Holder Score dele antes de agir. Inicie um scan e depois consulte o relatório com um intervalo crescente até ele ficar pronto.

POST /scans responde imediatamente; o scan roda em segundo plano.
Aumente o intervalo entre as consultas e respeite o retryAfter ao receber 429.
Pare em DONE ou ERROR, ou depois do seu próprio timeout.

Código#

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);