xca문서
엔드포인트

스캔

토큰 스캔을 시작하거나 오래된 리포트를 갱신해요.

POST/api/v1/scans

토큰의 전체 분석을 대기열에 넣고 현재 상태를 반환해요. 여러 번 호출해도 안전해요. 스캔이 진행 중이면 두 번째 스캔을 시작하지 않아요.

파라미터#

chainbody
체인 ID. 현재는 solana만 지원해요."solana"기본값: "solana"
addressbody필수
스캔할 토큰의 민트 주소.string

요청#

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"}'
직접 실행
실제 요청을 보내려면 API 키를 붙여넣으세요.

응답#

status
스캔 상태."NONE" | "QUEUED" | "RUNNING" | "DONE" | "ERROR"
depth
스캔이 생성하거나 갱신하는 리포트의 분석 깊이."LIGHT" | "FULL" | null
step
현재 스캔 단계.string | null
progress
0~100 사이의 진행률.number
stale
기존 리포트가 캐시 유효 기간보다 오래됐어요.boolean
upgrading
LIGHT 리포트를 FULL로 업그레이드하는 중이에요.boolean
limitReached
일일 스캔 한도를 모두 사용해서 이전 리포트의 상태를 반환했어요.boolean

응답 예시#

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

상태 코드#

200성공
400validation — 파라미터나 요청 본문이 유효하지 않아요. error.issues 값을 확인하세요.
401unauthorized — API 키가 없거나, 형식이 잘못됐거나, 폐기됐어요.
402planRequired — 플랜에 API 접근 권한이나 이 기능이 포함되어 있지 않아요.
429rateLimited — 분당 요청이 너무 많거나 월간 할당량을 모두 사용했어요.
503unavailable — 점검 중이거나 데이터 제공업체의 처리 용량이 부족해요.

동작 방식#

  • 최신 리포트가 있을 때: 바로 DONE 상태를 반환하고 스캔 한도를 차감하지 않아요.
  • 스캔이 진행 중일 때: step, progress 값과 함께 QUEUED 또는 RUNNING 상태를 반환해요.
  • 그 밖의 경우: 새 스캔을 대기열에 넣고 일일 한도에서 스캔 1회를 차감해요.
  • 일일 한도에 도달했지만 이전 리포트가 있을 때: limitReached 값을 true로 설정해 그 리포트의 상태를 반환해요.

결과 기다리기#

상태가 DONE 또는 ERROR가 될 때까지 GET /tokens/{chain}/{address} 엔드포인트를 3~5초마다 폴링하세요. 대부분의 스캔은 1분 안에 끝나요.

토큰 스캔 후 기다리기스캔을 시작하고, 무리 없는 간격으로 폴링해 완성된 리포트를 받아요.

스캔 단계#

queued대기열에서 기다리는 중이에요.
market가격, 유동성, 민트 데이터를 가져오는 중이에요.
holders홀더 목록을 읽는 중이에요.
trades스나이퍼를 찾기 위해 초기 거래를 읽는 중이에요.
profiles상위 홀더의 자금 출처, 지갑 나이, 손익을 분석하는 중이에요.
classify유형을 분류하고 클러스터를 구성하는 중이에요.
dev생성자의 이전 발행 이력을 확인하는 중이에요.
saveHolder Score를 계산하고 저장하는 중이에요.
done완료됐어요.
error실패했어요.
XCA가 점검 중이거나 데이터 제공업체의 처리 용량이 부족하면 스캔 요청에 503 unavailable 오류가 반환돼요. 잠시 후 다시 시도하세요.