REST API
Arcscan은 HTTP API를 통해 Arc를 읽으며, 그 API는 키도 계정도 없이 외부에서 접근할 수 있습니다 — 이 페이지의 모든 경로는 적어 두기 전에 공개 인터넷을 통해 실제로 호출해 보았습니다.
기본 URL#
API에는 체인마다 하나씩 전용 호스트명이 있습니다: Arc 메인넷(체인 5042)은 api.arc-scan.io, Arc 테스트넷(체인 5042002)은 api-testnet.arc-scan.io입니다. 기준으로 삼아야 할 주소는 이 둘입니다:
https://api.arc-scan.io/v1 # Arc mainnet, chain 5042 https://api-testnet.arc-scan.io/v1 # Arc Testnet, chain 5042002
두 호스트 모두 같은 두 가지 표면을 제공합니다: /v1/…는 리소스마다 경로 하나를 두는 타입이 있는 REST API로, 이 익스플로러가 화면을 그릴 때 쓰는 바로 그 문서를 돌려줍니다. /api?module=…&action=…는 기존 도구들이 이미 구사하는 익숙한 호환 계약입니다. 두 호스트의 차이는 어느 체인에 답하느냐뿐이므로, 클라이언트를 테스트넷으로 옮기는 일은 호스트명을 바꾸는 것으로 끝납니다.
사이트 자신의 /_api 경로는 API가 아닙니다
익스플로러가 자기 오리진에서 /_api/v1/…을 가져온다는 것, 그리고 직접 불러도 응답한다는 것을 눈치챌 수 있습니다. 그것은 같은 서비스로 향하는 웹사이트 내부의 재작성 경로이며 사이트 자신의 페이지를 위해 둔 것입니다: CORS 헤더를 전혀 보내지 않고, noindex 헤더와 함께 제공되며, 여러분과 아무 상관 없는 이유로 바뀔 수 있습니다. 위의 호스트명을 기준으로 개발하고, 한 곳에서 바꿀 수 있도록 호스트를 상수 하나에 고정하십시오.브라우저에서 호출할 수 있습니다 — 이 호스트에서만
API 호스트는 교차 오리진 요청에 응답합니다:Access-Control-Allow-Origin: *이며, 프리플라이트에서 Content-Type, X-Api-Key, If-None-Match가 허용되고, 호출자에게 ETag, X-Request-Id와 레이트 리밋 헤더가 공개됩니다. 익스플로러 자신의 /_api 경로는 Access-Control- 헤더를 하나도 싣지 않으므로, 그쪽을 향한 fetch()는 브라우저에서 실패하고 같은 호출이 curl에서는 성공합니다 — 잘못된 주소가 지금까지 눈에 띄지 않은 이유가 바로 이것입니다.두 개의 표면#
같은 노드와 같은 인덱스가 서로 다른 두 형태로 답합니다. 타입이 있는 API는 이 익스플로러가 화면을 그리는 데 쓰는 것이므로, 페이지에 보이는 것은 무엇이든 같은 형태의 JSON으로 읽을 수 있습니다. 호환용 API는 지갑과 배포 스크립트, 인덱서들이 이미 쓰고 있는 사실상의 익스플로러 REST 계약을 재현하므로, 기존 도구를 기본 URL 하나만 바꿔 Arc로 향하게 할 수 있습니다.
| 표면 | 형태 | 성공 봉투 |
|---|---|---|
/v1/… | 타입이 있는 REST, 리소스마다 하나의 경로 | 문서 그 자체, snake_case 키 |
/api?module=…&action=… | 하나의 경로, 쿼리 문자열로 분기 | {"status":"1","message":"OK","result":…} |
엔드포인트#
아래의 모든 경로는 이 페이지를 쓸 당시 메인넷을 상대로 호출해 보았습니다. 전부 응답했고, 그중 둘은 501로 답했으며, 둘 다 빼놓지 않고 제자리에 적었습니다 — 문서로 밝힌 거절이 공백보다 낫습니다.
체인, 홈, 헤드#
/v1/chain이 가장 먼저 할 호출입니다: 체인 ID, 네이티브 통화와 그 소수 자릿수, 이 배포가 가진 기능, 그리고 체인이 정확히 어디까지 인덱싱되어 있는지를 밝힙니다. 그중 어느 것도 코드에 박아 넣지 말고 이 호출에서 읽으십시오 — 두 체인은 다르며, 인덱스 블록이 무엇을 알려 주는지는 데이터 범위에서 설명합니다.
curl https://api.arc-scan.io/v1/chain # {"chain_id":5042,"name":"Arc","is_testnet":false, # "native":{"symbol":"USDC","decimals":18}, # "block_time_ms":506,"finality":"instant", # "capabilities":{"trace":true,"archive":true,"debug":false,…}, # "index":{"available":true,"complete":true,…}}
| 경로 | 답하는 것 |
|---|---|
GET /v1/chain | 체인 상수, 기능, 인덱스 범위 |
GET /v1/home | 최신 블록과 트랜잭션을 한 문서로 |
GET /v1/stats/summary | 홈 화면이 보여 주는 대표 카운터 |
GET /v1/stats/gas | 수수료 트래커: 현재와 최근의 가스 가격 |
GET /v1/stream/head | 서버 전송 이벤트, 새 블록마다 한 프레임 |
/v1/stream/head는 JSON 문서가 아니라 SSE 스트림입니다 — 연결을 열어 둔 채 대략 1초에 두 번 프레임을 밀어 보냅니다. 모든 프레임이 server_now를 실어 보내므로 클라이언트는 자기 시계를 믿지 않고도 정직한 경과 시간을 계산할 수 있습니다.
curl -N https://api.arc-scan.io/v1/stream/head # event: head # data: {"height": 14852424, "hash": "0x68ce06…f3775", "timestamp": 1786360005, # "tx_count": 0, "server_now": 1786360007, "available": true}
블록#
블록 참조는 높이, 해시, 또는 문자 그대로의 latest입니다. 목록은 limit과 불투명한 cursor를 받습니다. 각 항목의 뜻은 블록을 보십시오.
curl "https://api.arc-scan.io/v1/blocks?limit=2" curl https://api.arc-scan.io/v1/blocks/latest curl https://api.arc-scan.io/v1/blocks/14852000 curl "https://api.arc-scan.io/v1/blocks/14852000/txs?limit=10"
트랜잭션#
트랜잭션은 해시로 지정합니다. 메인넷에서는 trace가 true이므로 콜 트리를 제공하지만, debug가 false이므로 상태 diff는 제공하지 않으며 빈 답 대신 501로 그렇다고 말합니다.
H=0x128cb07da24289341bcc57e3129ef78f82b5a1769c30156774487fe9e98251e9 curl "https://api.arc-scan.io/v1/txs?limit=5" curl "https://api.arc-scan.io/v1/txs/$H" curl "https://api.arc-scan.io/v1/txs/$H/raw" curl "https://api.arc-scan.io/v1/txs/$H/trace" curl "https://api.arc-scan.io/v1/txs/$H/state" # 501 {"error":{"code":"CAPABILITY_UNAVAILABLE",…}} — no debug namespace on mainnet
주소와 토큰#
A=0xf40dc55b06e4e8c042430ecf1995d0ec6b9ae033 T=0x3600000000000000000000000000000000000000 # the native currency as an ERC-20 curl "https://api.arc-scan.io/v1/address/$A" curl "https://api.arc-scan.io/v1/address/$A/txs?limit=10" curl "https://api.arc-scan.io/v1/address/$A/activity?limit=10" curl "https://api.arc-scan.io/v1/address/$A/logs?limit=10" curl "https://api.arc-scan.io/v1/address/$A/tokens" curl "https://api.arc-scan.io/v1/tokens/$T" curl "https://api.arc-scan.io/v1/tokens/$T/info"
보유자는 메인넷에서 인덱싱되어 있으므로 /v1/tokens/{address}/holders는 일반 토큰에 대해 답합니다. 0x3600…0000의 네이티브 통화에 대해서는 거절하며, 그 이유를 메시지가 설명합니다: 그 잔액은 곧 계정 잔액이고, 그것을 두 번 인덱싱하면 모든 계정을 이중으로 세게 됩니다.
검색, 차트, 디코드#
검색은 익스플로러 자신의 검색창이 해석하는 것 — 높이, 해시, 주소 — 을 해석합니다. 차트 인덱스는 모든 지표를 그 id와 함께 나열하고 /v1/charts/{metric}는 그 한 계열을 반환하며, tx도 그중 하나입니다. 디코드는 이 페이지의 유일한 POST이며 체인 조회가 전혀 필요 없습니다.
curl "https://api.arc-scan.io/v1/search?q=0x3600000000000000000000000000000000000000" curl "https://api.arc-scan.io/v1/search/suggest?q=0x36" curl https://api.arc-scan.io/v1/charts curl https://api.arc-scan.io/v1/charts/tx curl -X POST https://api.arc-scan.io/v1/decode \ -H 'content-type: application/json' \ -d '{"input":"0xa9059cbb…"}' # {"selector":"0xa9059cbb","decoded":{"name":"transfer", # "signature":"transfer(address,uint256)","args":[…]},"error":null}
호환용 표면#
/api?module=…&action=…는 익숙한 익스플로러 계약을 따릅니다: 하나의 경로에 module과 action을 두고, result 안의 모든 스칼라를 문자열로 돌려줍니다. proxy 모듈은 JSON-RPC 읽기를 그대로 통과시키고 상태 봉투가 아니라 JSON-RPC 형태로 답합니다.
curl "https://api.arc-scan.io/api?module=proxy&action=eth_blockNumber" # {"jsonrpc":"2.0","id":1,"result":"0xe2a12f"} curl "https://api.arc-scan.io/api?module=account&action=balance&address=0xf40dc55b06e4e8c042430ecf1995d0ec6b9ae033" # {"status":"1","message":"OK","result":"20456053552414099311"} curl "https://api.arc-scan.io/api?module=stats&action=ethsupply"
그 계약의 모든 액션이 여기 있는 것은 아닙니다 — Arc에 없는 데이터나 저희가 유지하지 않는 인덱스를 필요로 하는 것들은 이름을 밝혀 거절합니다. 사이트의 API 레퍼런스새 탭에서 열립니다가 전체 디스패치 표와 어떤 액션이 제공되지 않는지를 나열하며, 서비스 자체에서 생성되므로 이 페이지처럼 어긋날 일이 없습니다.
JSON 읽기#
이름 붙일 만한 연동 버그는 모두 네 가지 관례에서 나옵니다. 첫 번째가 값비싼 것입니다: 소수 18자리 금액은 JavaScript의 Number로는 살아남지 못하므로, 금액은 문자열로 전송되며 문자열로 파싱해야 합니다.
| 관례 | 전송에서의 의미 |
|---|---|
| 금액 | 숫자가 아니라 객체입니다: raw(정수 문자열), decimals, formatted(정확값), usd, symbol. 가스 수치와 발행량도 10진 문자열입니다. 블록 높이는 JSON 숫자입니다. |
| 표기 | 키는 snake_case입니다. 주소와 해시는 소문자이며, 표시용 형태가 옆의 checksum 항목에 함께 놓입니다. 입력은 어떤 대소문자든 받아들입니다. |
| 시간 | 미리 서식이 적용되지 않은 유닉스 초입니다. 블록은 1초에 두 개꼴로 도착하고 타임스탬프의 해상도는 1초이므로 전순서가 아닙니다 — 결코 이것으로 정렬하거나 페이지를 넘기지 마십시오. |
| 페이지 이동 | 페이지 번호가 아니라 page.next 아래의 불투명한 커서입니다. 계속 진행할지는 page.has_more가 알려 줍니다. |
커밋된 이력은 불변이며, 그에 맞게 캐시됩니다
커밋된 높이나 채굴된 해시로 지정된 응답은Cache-Control: public, max-age=31536000, immutable로 제공됩니다. Arc는 즉시 최종성을 가지며 재구성이 없으므로 이것은 확률적 보장이 아니라 진짜 보장입니다: 그런 응답은 영원히 캐시하고 요청 자체를 건너뛰십시오.오류#
거절은 기계가 읽을 수 있는 code와 사람을 위해 쓴 메시지, 그리고 선택적인 detail을 담은 JSON 객체입니다. 메시지 텍스트가 아니라 code로 분기하십시오.
curl https://api.arc-scan.io/v1/blocks/999999999999 # 404 # {"error":{"code":"NOT_FOUND","message":"No block at height 999999999999","detail":null}} curl https://api.arc-scan.io/v1/tokens/0x3600000000000000000000000000000000000000/holders # 501 # {"error":{"code":"CAPABILITY_UNAVAILABLE", # "message":"The native gas token has no separate holder list: its balances are account # balances, and indexing them again would double-count every account.", # "detail":{"capability":"holder_index","detail_key":"holdersNativeToken"}}}
| 상태 | code | 언제 |
|---|---|---|
| 404 | NOT_FOUND | 그런 블록, 트랜잭션, 주소 기록, 토큰이 없습니다. |
| 429 | RATE_LIMITED | 요청이 너무 많습니다. Retry-After를 초 단위로 실어 보냅니다. |
| 501 | CAPABILITY_UNAVAILABLE | 이 데이터에는 이 체인이나 이 배포에 없는 기능이 필요합니다. |
| 502 | UPSTREAM_ERROR | 노드가 답하기는 했지만 쓸모 있게 답하지는 않았습니다. |
| 503 | INDEX_OVERLOADED | 무거운 질의를 대기시키지 않고 떨어뜨렸습니다. |
| 504 | UPSTREAM_TIMEOUT | 노드가 제때 답하지 않았습니다. |
상태 코드만이 아니라 오류 봉투를 읽으십시오
형식이 잘못되었거나 범위를 벗어난 매개변수 — 해석할 수 없는 블록 참조, 최댓값을 넘는limit, 빠진 필수 질의, 잘못 적은 JSON 필드 이름 — 은 400 {"error":{"code":"INVALID_INPUT","message":"limit: Input should be greater than or equal to 1","detail":null}} 로 돌아옵니다. code 가 오류의 종류를 알려 주고 message 가 원인이 된 필드를 지목하므로, 보통 URL을 다시 읽는 것보다 빠릅니다. 여기서의 404 는 그 리소스가 정말로 없다는 뜻입니다.한도와 접근#
API 키도, 등급도, 가입할 것도 없습니다. 요청은 호출자별로 토큰 버킷에 의해 계량되고, 모든 응답이 지금 어디쯤인지 알려 줍니다 — 숫자를 코드에 박아 넣는 대신 헤더를 읽으십시오. 그 예산은 운영 설정이지 공개된 약속이 아니기 때문입니다.
| 헤더 | 의미 |
|---|---|
X-RateLimit-Limit | 이 요청이 계량된 버킷의 크기입니다. |
X-RateLimit-Remaining | 그 안에 남은 토큰입니다. |
Retry-After | 429나 503에서만: 다시 시도하기 전에 기다릴 정수 초입니다. |
X-Request-Id | API 응답에 붙습니다. 어떤 요청에 대해 문의하실 때 이 값을 알려 주십시오. |
다른 두 상한도 실제로 있으며 감추지 않고 알려 드립니다. 로그 질의는 최대 블록 구간으로 제한되고, 범위를 넘는 요청은 조용히 잘리는 대신 그 최대값을 메시지에 밝히며 거절됩니다. 트레이스와 상태 diff 호출은 실제 시간 예산과 크기 상한을 가진 작은 전용 풀에서 실행되며, 멈춰 있는 대신 truncated: true를 설정합니다.
저희 인덱스 없이 Arc 읽기
저희의 관점이 아니라 체인 자체가 필요하시다면, 메인넷을 위한 공용 읽기 전용 JSON-RPC 엔드포인트도 운영하고 있습니다 — 공용 RPC를 보십시오. 스키마보다 산문을 먼저 읽는 쪽을 위해, 이 익스플로러가 무엇을 보유하는지 설명하는 일반 텍스트 /llms.txt새 탭에서 열립니다도 있습니다.