Stablecoin scanner ACHIVX API 연동하기

HTTPS를 쓸 수 있는 어떤 환경에서든 GET https://stablescan.achivx.com/v1/networks 요청을 보내십시오. 키도, 가입도, /api 접두사도 없습니다. REST는 루트의 /v1에 있습니다. 응답은 ETag, Cache-Control, X-Request-Id가 붙은 JSON입니다. 2026-10-24에는 0.31초 만에 스캐너가 아는 아홉 개 네트워크와 함께 돌아왔으며, 그중 일곱 개가 settled: true였습니다. 아래의 세 가지 헬퍼 — Python, Go, TypeScript — 는 이 섹션의 다른 모든 페이지가 호출하는 것입니다.

라우트 목록이 아니라 질문에서 출발하십시오. 이 주소와 거래해도 되는가?는 /v1/addresses/{a}/risk이며, 그 뒤의 사실은 /v1/addresses/{a}입니다. 내 전송이 도착했는가?는 /v1/verify?tx=, 오늘 누가 동결되었는가?는 /v1/freezes/acts, 시장에서 무슨 일이 일어나고 있는가?는 /v1/stats/home입니다. 아래 표는 이 섹션이 답하는 모든 질문을 엔드포인트에, 모든 엔드포인트를 그 응답을 필드별로 설명하는 페이지에 연결합니다.

규칙은 여섯 가지이며 모든 라우트에 적용됩니다. chain을 명시적으로 전달하십시오. 지정하지 않을 때의 기본값은 베이스(Base)(8453)이며, chain_source: "default"가 유일한 흔적입니다. 주소는 질의한 네트워크의 표기로 답하며, 다른 종류의 체인 표기는 거부되지 않고 address_respelled: true로 표시됩니다. 모든 _usd6는 미국 달러에 백만을 곱한 값입니다. 단위 없는 amount나 balance는 토큰의 최소 단위이며 옆에 decimals가 있습니다. 오류는 하나의 형식을 공유하므로 error.code로 분기하십시오. 네 개 라우트는 알 수 없는 매개변수를 거부하고, 나머지는 무시합니다. 모든 응답은 요청 ID를 밝힙니다.

이 API의 모든 판정에는 세 가지 결과가 있으며, 여러분의 코드는 셋을 모두 유지해야 합니다. 이름이 붙은 결과(sanctioned, frozen, severe), none(충분한 집계 범위에서 확인했고 아무것도 찾지 못함), unknown(확인할 수 없었음)입니다. unknown은 절대 none이 아니며, 항상 incomplete_reasons에서 이유를 밝힙니다. 응답이 보이는 것보다 부족하다는 신호가 네 가지 더 있습니다. 숫자가 있어야 할 자리의 null, 판정이 아니라 목록일 뿐인 빈 목록, 일부를 잃은 조회의 Cache-Control: no-store, 그리고 요청보다 늦게 시작하는 그래프의 window_from입니다. 이 페이지는 정직성 약속을 분기 규칙으로 다시 쓴 것입니다.

GET /v1/addresses/{address}?chain=은 사실 요약표입니다. sanctioned(OFAC SDN 목록), 해당 네트워크에서 동결 가능한 스테이블코인마다 status(clear, frozen, seized, unknown)가 있는 freeze[] 행 하나, 어떤 발행사도 건드릴 수 없는 코인을 담은 not_freezable[], 다른 인덱싱된 네트워크의 유효한 기록을 담은 frozen_elsewhere[], freeze_proposals[], 그리고 라벨(is_service, name, name_category)이 들어 있습니다. 이것은 사실일 뿐 신원, AML, 법적 판정이 아니며, 이 사실들로 만든 판정은 /risk입니다.

GET /v1/addresses/{address}/risk?chain=은 tier 하나 — severe, high, medium, low, none, unknown — 를 flags(sanctioned, frozen, exposed, labeled, service), 신호마다 하나씩인 evidence[] 행, incomplete_reasons[]와 함께 답합니다. 등급은 사실이 정합니다(OFAC 목록 등재는 severe, 발행사 동결은 high, 오염된 출발점까지의 도달은 high 또는 medium). 라벨만으로는 medium이 상한입니다. unknown은 평가를 완료할 수 없었다는 뜻이며 그 이유를 밝힙니다. 활발한 주소에서는 노출 탐색이 자주 시간을 다 쓰며, 그 경우 none이 아니라 time_budget과 함께 unknown으로 읽힙니다. 두 주소가 전에 거래한 적이 있는지 알고 싶으면 from=을 추가하십시오.

GET /v1/addresses/{address}/exposure?chain=&hops=는 주소에서 거래 상대를 거쳐 가장 가까운 오염 출발점(taint root) — OFAC 목록에 오른 주소, 또는 해킹·드레이너·믹서 라벨이 붙은 주소 — 을 향해 hops(기본값 3)까지 역방향으로 탐색하고 exposure를 답합니다. 값은 sanctioned, direct, indirect, negligible, none, unknown 중 하나이며, reached_roots[], exposure_fraction, min_hops, 그리고 탐색 자체에 대한 기록(hops_completed, nodes_explored, frontier_truncated, truncation_reason)이 함께 옵니다. 판정 /risk는 이 탐색을 바탕으로 만들어집니다. 출발점과 경로 길이가 필요할 때 이 라우트를 호출하십시오.

/v1/addresses/{address}/balances?chain=은 요청 시점에 인덱싱된 모든 스테이블코인의 balanceOf를 체인에서 실시간으로 읽어, 실제 0을 포함한 전부를 최소 단위 문자열과 decimals로 나열합니다. /v1/addresses/{address}/volume?chain=&days=는 일별 집계에서 정산된 입출금 달러 금액을 답합니다. days에 걸친 period(기본값 30, 최대 3,650)와 all_time이며, 각 합계에는 _complete 플래그가 있어 수치나 0을 믿기 전에 반드시 확인해야 합니다. 발행, 소각, 자기 자신에게 보낸 전송, 1달러 그래프 하한 미만의 일별 쌍은 제외됩니다. 거래량은 정산이지, 모든 Transfer 로그의 합이 아닙니다.

/v1/addresses/{address}/approvals?chain=은 주소가 열어 둔 스테이블코인 허용량(디코딩된 Approval 사실, 클래스 F)을 섀도 방식으로 계산한 행별 위험 band, 그리고 목록 전체에 대한 worst_band와 함께 나열합니다. /v1/addresses/{address}/heuristics?chain=은 주소가 금액 0 전송(zero-value transfer)을 보냈는지를 flagged, status, zero_value_sends로 알려 줍니다. 이는 주소 포이즈닝(address poisoning) 캠페인이 가짜 이력을 심을 때 쓰는 형태입니다. 둘 다 참고용입니다. 구간과 플래그는 휴리스틱(클래스 H)이며, 탐지기가 정밀도 기준을 통과하기 전까지는 위험 점수에 절대 반영되지 않고, 두 응답 모두 note에서 이를 밝힙니다.

/v1/addresses/{address}/graph?chain=&token=&hops=는 주소 주변의 정산 그래프를 nodes[]와 edges[] (엣지별 거래량, 노드별 라벨, motifs[])로 반환합니다. 최신 스냅샷이 저장되어 있으면 그것으로 만들고, 무거운 그래프가 아직 없으면 202 building으로 답합니다. /v1/addresses/{address}/walk?chain=&token=&hops=는 같은 이웃을 홉 단위로 반환하며, 요청마다 새로 만들고 stop_at_attributed와 stop_on_sanctioned 스위치를 가집니다. 두 라우트 모두 token을 전달하십시오. 그래프는 스테이블코인별로 만들어집니다. 무언가가 없다는 것에서 결론을 내리기 전에 window_from을 읽으십시오.

GET /v1/transfers?chain=은 피드입니다. 네트워크 하나의 스테이블코인 전송을 최신순으로, 한 페이지에 50개(1–200)씩 보여 주며, 각 행에는 tx_hash, block_number, block_time, payer, recipient, decimals가 있는 amount 객체, 토큰 컨트랙트, finality, 양 끝의 라벨이 있습니다. payer=, recipient=, token=, block=, finality=로 필터링하고 cursor=로 페이지를 넘깁니다. 이 주소가 관여한 필터는 없습니다. payer와 recipient를 따로 조회해 합치십시오. 첫 페이지에는 total(상한 25,000)과 hot_window_start가 있습니다. 더 오래된 행은 없는 것이 아니라 보관 처리된 것입니다.

GET /v1/verify?tx=<hash>는 해시만 받아, 거래 ID 형식이 맞는 모든 인덱싱된 네트워크(EVM 네트워크와 트론(Tron)은 16진수, 솔라나(Solana)는 base58)에서 스테이블코인 전송 및 발행사 기록을 검색합니다. 찾으면 chain_id, transfers[], freeze와 함께 found: true를, 모든 네트워크가 찾지 못했다고 답하면 false를, 적어도 하나가 답하지 않으면 null을 답합니다. GET /v1/transfers?tx=&chain=은 네트워크 하나에서 찾아 행을 반환합니다. 둘 다 최근 보관 구간(hot window)보다 오래되었거나 네트워크의 인덱싱된 헤드보다 새로운 거래는 볼 수 없습니다.

세 가지 습관이며, 각각 몇 줄이면 됩니다. 같은 쿼리를 cursor=<next_cursor>로 반복해 next_cursor가 없는 페이지가 올 때까지 페이지를 넘기십시오. 도중에 필터를 바꾸지 마십시오. If-None-Match: <etag>로 재검증하십시오. 일치하는 응답은 본문 없는 304입니다(/v1/networks가 2026-10-24에 Age: 140으로 하나를 답했습니다). max-age에 맞춰 폴링하십시오. 피드는 15초, 동기화 상태는 5초, 판정은 60초(탐색이 잘렸으면 10초), 레지스트리는 300초, 순위는 3,600초입니다. 더 자주 폴링하면 같은 바이트가 돌아옵니다. 여기의 모든 규칙은 스캐너가 보내는 헤더에서 나온 것이며, 코드가 그것을 보여 줍니다.

GET /v1/sync/status?chain=은 last_indexed_block, head_block, safe_block, finalized_block, lag_blocks, freshness_seconds를 답합니다. freshness_seconds는 해당 네트워크에서 가장 최근에 인덱싱된 전송의 경과 시간으로, 어디서나 같은 의미를 갖는 유일한 최신성 척도입니다. 2026-10-24에 이더리움(Ethereum)은 16블록, 209초 뒤처져 있었고, 베이스는 30블록, 63초였습니다. 전송이 일어나지 않았다고 판단하기 전에 이것을 읽고, 모든 주소 응답 옆에 있는 같은 freshness_seconds를 읽으십시오. /health와 /ready는 인덱싱에 대해 아무것도 말하지 않습니다.

GET /v1/freezes/acts는 원장입니다. 인덱싱된 네트워크에서 발행사 컨트랙트가 발생시킨 모든 freeze, unfreeze, seize 이벤트를 최신순으로, 한 페이지에 50개(1–200)씩 보여 주며, 각 행에는 subject, token, action, raw_event, tx_hash, block_time, finality가 있고 소각에는 amount_usd6가 있습니다. chain, token, kind, address로 필터링합니다. chain이 없으면 모든 네트워크를 나열하고 그렇다고 밝힙니다. GET /v1/freezes?tx=&chain=은 거래 하나가 발생시킨 기록을 답합니다. 피드가 아니라 조회입니다. address로 필터링한 페이지는 기록의 목록이지, 결코 판정이 아닙니다.

GET /v1/freezes/proposals는 발행사의 소유자 멀티시그 — 이더리움과 트론의 USDT, Gnosis MultiSigWallet — 에 제안된 기록을 최신순으로 나열합니다. status(pending, executed, failed, revoked, superseded, stale), required 중 confirmations, submitted_tx, 실행된 후에는 executed_tx, 둘 사이의 window_seconds, 그리고 대상의 balance_at_submission, balance_at_execution, moved_out이 있습니다. 대기 중인 제안은 주소, 거래, 금액 없이 나열되며(redacted[]가 어떤 필드인지 알려 줌), 실행되면 전체가 표시됩니다. 이더리움의 중앙값 간격은 44분, 트론은 25분입니다.

누가 무엇을 동결할 수 있는가라는 질문에는 세 가지 단위로 세 가지 조회가 답합니다. GET /v1/freezes/guide?chain=은 네트워크 하나입니다. 모든 스테이블코인을 freeze_tier(none, freeze, seize), capability, signer와 signer_kind(테더의 멀티시그, 서클(Circle)의 블랙리스트 관리 계정), 기록 건수, 그리고 스캐너의 표현으로 된 faq[]와 함께 보여 줍니다. GET /v1/freezes/networks는 색인으로, 네트워크마다 결과와 함께 행이 하나 있습니다. GET /v1/tokens/{token}/freezes는 네트워크 전체에 걸친 심볼 하나입니다. 오늘과 이번 달의 건수, 현재 유효한 총계, 최근 기록 열 건이 있습니다.

GET /v1/networks는 스캐너가 아는 모든 네트워크를 chain_id, slug, caip2, settled(true = 여기서 인덱싱됨)와 함께 나열합니다. GET /v1/tokens?chain=은 네트워크 하나의 스테이블코인을 symbol, address, decimals, variant(native 또는 bridged), freeze_tier와 함께 나열합니다. GET /v1/tokens/{address}/contract?chain=은 검증된 소스 코드 기록을 답합니다. verified, 출처(sourcify, tronscan, tron_onchain, registry), ABI, 읽기 및 쓰기 함수, 배포 정보입니다. 앞의 두 가지는 5분 동안 캐시하고, 모든 chain, token, decimals를 거기서 가져오십시오.

GET /v1/search?q=는 주소, 거래 해시, 블록 번호가 아닌 모든 것에 대해 사이트 검색창이 호출하는 것입니다. tokens[]는 q와 정확히 일치하거나 q로 시작하는 레지스트리 심볼이며, 각각 열어 볼 페이지와 네트워크가 함께 있습니다. addresses[]는 커뮤니티 라벨 이름에 q가 포함된 지갑으로, 가장 잘 맞는 것부터 — 정확히 일치, 접두사 일치, 더 짧은 이름 순 — 나옵니다. q는 2–64자입니다. 라벨은 귀속이지 검증된 신원이 아니며, 응답의 note가 그렇게 밝힙니다.

GET /v1/stats/home?window=24h|7d|30d&chain=은 첫 화면을 문서 하나로 담은 것입니다. 헤드라인(정산 volume_usd6, organic_volume_usd6, inorganic_fraction_pct, 왕복 거래), 30일 series[], chains[]와 tokens[] 표, 체인 × 토큰 행렬, 발행(발행, 소각, 순발행), top_routes와 top_addresses가 있습니다. 배치로 만들어지므로, 날짜는 built_at이 아니라 window_start/window_end에서 읽으십시오. GET /v1/stats/overview?chain=&window=는 네트워크 하나의 원시 대 유기적 거래량 분할을 실시간으로 보여 주며, per_token 행과 hot_window_start가 있습니다. 2026-10-24에 전체 시장은 하루에 1,259억 달러를 정산했으며, 그중 34 %가 유기적 거래량이었습니다.

GET /v1/tokens/{token}/addresses?window=24h|7d|30d&per_chain=은 네트워크별로, 한 심볼에서 회전액(잔액이 아니라 기간 안에 받은 금액과 보낸 금액의 합)이 가장 큰 주소들의 순위를 매기며, 각각 옆에 excluding_services 목록이 있습니다. GET /v1/tokens/{token}/routes는 payer → recipient 쌍을 volume_usd6와 tx_count로 순위를 매깁니다. 둘 다 토큰별 일일 상위 N에서 합산한 것이므로 순위일 뿐 결코 총계가 아니며, chains[].basis_days는 각 네트워크의 순위가 기간 중 며칠에서 합산되었는지 알려 줍니다. 가장 최근 날짜는 마감된 후 순위가 매겨지기 전까지 빠져 있습니다.

GET /v1/entities는 공개된 거래소를 30일 흐름이 큰 순서로 나열하며, 각각 addresses 수, flows_30d, balances, frozen, sanctioned가 있습니다. GET /v1/entities/{slug}는 거래소 하나입니다. 네 가지 기간(24h, 7d, 30d, 90d)의 흐름을 네트워크별·스테이블코인별로, 주소 목록의 앞부분, 그리고 거래한 다른 거래소들을 담고 있습니다. /addresses?chain=&group=own|deposit은 주소 집합을 한 페이지에 100개씩, 야간 빌드가 정한 순서로 페이지를 나눕니다. /daily는 90일 시계열입니다. 유입은 집합으로 들어오는 것, 유출은 집합에서 나가는 것이며, 핫월렛으로 모아진 입금은 internal입니다. 고객 입금은 한 번만 셉니다.

모든 거부 응답은 {"error": {"code", "message", "request_id"}}입니다. code로 분기하십시오. 400은 메시지에 해결 방법이 있으며 재시도할 가치가 전혀 없습니다. 429 rate_limited는 단 하나의 토큰 버킷(분당 요청 1,200건, 초당 20건, 버스트 40건)이 비었다는 뜻이므로 Retry-After만큼 기다리십시오. 503은 네 가지 코드 중 하나입니다. timeout(Retry-After: 5만큼 기다린 뒤 한 번 재시도), busy(무거운 주소 조회들이 정해진 수의 슬롯을 공유함, 대응은 같음), snapshot_pending(배치가 아직 만들지 않은 보기, Retry-After: 60), not_ready(/ready에서만)입니다. 오류 형식이 없는 5xx는 스캐너가 아니라 엣지에서 온 것입니다. 물러났다가 재시도하고, 절대 빈 응답으로 읽지 마십시오. 아래에 이 모든 것을 수행하는 클라이언트가 있습니다.

체인이 아니라 서비스를 지켜보는 조회가 네 가지 있습니다. /health와 /ready는 프로세스 가용성 — 실행 중이며 데이터베이스가 응답함 — 이며 인덱싱에 대해서는 아무것도 말하지 않습니다. GET /v1/sanctions는 OFAC 데이터셋입니다. 생태계별 건수(2026-10-24 기준 주소 385개: EVM 120개, 트론 261개, 솔라나 4개)와 updated_at이 있습니다. GET /v1/stats/slo?chain=은 서비스의 지연 시간 예산과 배치 기준점 — OFAC 목록, 주간 그래프 배치 — 의 경과 시간입니다. 그리고 응답에 서명하는 배포는 응답에 attestation 객체를 추가합니다. POST /v1/verify-attestation은 본문을 그것과 대조해 확인하며, 무료이고 독립적입니다. 이 배포는 현재 서명하지 않으며, /.well-known/jwks.json은 비어 있습니다.

세 번의 호출을 이 순서로 합니다. 판정과 두 주소가 처음 거래하는지 알기 위해 from=에 자신의 주소를 넣은 /risk, 등급이 none이 아닐 때 사실을 보기 위한 개요, 탐색이 잘려 판정이 unknown일 때 어디까지 갔는지 보기 위한 /exposure입니다. 프로그램은 세 단어 중 하나 — refuse, allow, escalate — 로 답하고 요청 ID와 computed_at을 로그에 기록합니다. 하드코딩된 정책은 스캐너가 고집하는 단 하나뿐입니다. unknown은 상위 검토로 넘기며, 절대 허용하지 않습니다.

결제는 /v1/verify?tx=가 found: true를 답하고 행의 finality가 final일 때 확인됩니다. 그때까지 프로그램은 네트워크의 freshness_seconds가 허용하는 동안 15초(라우트의 max-age)마다 폴링하며, found: null은 아니오가 아니라 다시 요청으로 취급합니다. 찾으면 수신자 개요를 한 번 읽어, 받은 스테이블코인이 그 체인에서 동결되어 있는지 확인합니다. 결제가 도착하고도 잃을 수 있는 경우입니다. 프로그램은 confirmed, pending, not-found, frozen 중 하나를 본 내용과 함께 출력합니다.

하루 한 번의 작업, 세 번의 조회입니다. 네 가지 기간, 네트워크별 잔액, as_of_day를 위한 /v1/entities/{slug}, 시계열을 위한 /v1/entities/{slug}/daily — 프로그램은 여기서 최근 7일의 순흐름을 출력하고 90일 기준 표준편차 두 배를 벗어난 날을 표시합니다 — 그리고 30일 회전액 순으로 정렬된 자체 지갑을 위한 /v1/entities/{slug}/addresses?chain=&group=own입니다. 모든 수치는 마감된 UTC 날짜(as_of_day)에서 읽으므로, 작업은 야간 빌드(built_at, 약 08:00 UTC) 후에 한 번 실행되고, 보고하는 모든 기간 옆에 complete 플래그를 유지합니다.

상태가 하나 — 처리한 가장 최근 기록의 (block_time, tx_hash, log_index) — 뿐인 폴러입니다. 30초(max-age)마다 /v1/freezes/acts를 읽고, 이미 본 것에 도달할 때까지 next_cursor를 따라가며, 대상이 감시 목록에 있는 모든 새 기록이나 임계값을 넘는 모든 소각에 대해 알림을 보냅니다. 프로그램은 새 기록마다 한 줄을 출력하고 상태를 파일에 보관하므로, 재시작해도 다시 알리지 않습니다. 텔레그램 봇은 사람을 위해 같은 일을 합니다(/v1/subscriptions가 위치를 알려 줍니다). 이것은 여러분의 코드를 위한 버전입니다.