REST API
Arcscan は HTTP の API を通して Arc を読んでおり、その API はキーもアカウントも無しに外部から到達できます。このページのすべてのパスは、書き留める前に公開インターネット越しに呼び出しました。
ベース URL#
API にはチェーンごとに専用のホスト名があります。Arc メインネット (チェーン 5042) は api.arc-scan.io、Arc テストネット (チェーン 5042002) は api-testnet.arc-scan.io です。開発の対象にすべきはこの 2 つです:
https://api.arc-scan.io/v1 # Arc mainnet, chain 5042 https://api-testnet.arc-scan.io/v1 # Arc Testnet, chain 5042002
どちらのホストも同じ 2 つの面を提供します。/v1/… は型付きの REST API で、リソースごとに 1 つの経路を持ち、このエクスプローラー自身が描画に使っているのと同じ文書を返します。/api?module=…&action=… は既存のツールがすでに話せる、おなじみの互換契約です。2 つのホストの違いはどちらのチェーンに答えるかだけなので、クライアントをテストネットに向けるのはホスト名の変更だけで済みます。
サイト自身の /_api という経路は API ではありません
エクスプローラーが自分のオリジンから /_api/v1/… を取得していること、そして自分で呼んでも応答することに気づくかもしれません。それは同じサービスへ向かうサイト内部の書き換え経路で、サイト自身のページのために置かれているものです。CORS のヘッダーは一切返さず、noindex のヘッダー付きで配信され、あなたとは無関係な理由で変更されることがあります。上のホスト名を対象にし、1 か所で変えられるようホストは 1 つの定数に固定してください。ブラウザから呼び出せます — ただしこのホストに限ります
API のホストはクロスオリジンに応答します:Access-Control-Allow-Origin: *、プリフライトでは Content-Type、X-Api-Key、If-None-Match が許可され、呼び出し側には ETag、X-Request-Id とレート制限のヘッダーが公開されます。エクスプローラー自身の /_api の経路は Access-Control- ヘッダーを 1 つも返さないため、そこへ向けた fetch() はブラウザでは失敗し、同じ呼び出しが curl では通ります — 誤ったアドレスが見過ごされてきたのは、まさにこのためです。2 つの面#
同じノードと同じインデックスが、2 つの異なる形で応答します。型付きの API はこのエクスプローラーが描画に使っているものなので、ページ上で見えるものは同じ形の JSON として読めます。互換 API は、ウォレット・デプロイ用スクリプト・インデクサーがすでに話している事実上のエクスプローラーの REST 契約を再現するので、既存のツールはベース URL を 1 つ変えるだけで Arc に向けられます。
| 面 | 形 | 成功時のエンベロープ |
|---|---|---|
/v1/… | 型付き REST、リソースごとに 1 つのパス | 文書そのもの、キーは snake_case |
/api?module=…&action=… | 1 つのパスを、クエリ文字列で振り分け | {"status":"1","message":"OK","result":…} |
エンドポイント#
以下のパスはすべて、このページを書いた時点でメインネットに対して呼び出しました。すべて応答があり、うち 2 つは 501 でした。その 2 つも省かずに、あるべき場所に記しています — 文書化された拒否は、空白よりも価値があります。
チェーン、ホーム、ヘッド#
/v1/chain が最初に呼ぶべきものです。チェーン ID、ネイティブ通貨とその小数桁、この配備が持つ機能、そしてチェーンのどれだけがインデックスされているかを正確に述べます。それらをハードコードせずにここから読んでください — 2 つのチェーンは異なりますし、インデックスの項目が何を伝えているかはデータの収録範囲で説明しています。
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 | 最新のブロックとトランザクションを 1 つの文書で |
GET /v1/stats/summary | ホームページが示す主要なカウンター |
GET /v1/stats/gas | 手数料トラッカー: 現在と直近のガス価格 |
GET /v1/stream/head | Server-sent events、新しいブロックごとに 1 フレーム |
/v1/stream/head は JSON の文書ではなく SSE のストリームです — 接続を開いたまま、1 秒に約 2 回フレームを送ります。どのフレームにも 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 だからで、空の答えではなく 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} はその 1 系列を返します。tx はそのうちの 1 つです。デコードはこのページで唯一の 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=… はおなじみのエクスプローラーの契約を話します。1 つのパス、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 の読み方#
名前を挙げる価値のある統合時の不具合は、4 つの取り決めから生じます。最初のものが高くつきます。小数 18 桁の数量は JavaScript の Number では表せないため、数量は文字列として送られ、そのように解析しなければなりません。
| 取り決め | 通信上の意味 |
|---|---|
| 数量 | 数値ではなくオブジェクトです: raw（整数の文字列）、decimals、formatted（正確な値）、usd、symbol。ガスの数値と供給量も 10 進の文字列です。ブロック高は JSON の数値です。 |
| 表記 | キーは snake_case です。アドレスとハッシュは小文字で、表示用の形は横の checksum の項目にあります。入力はどの大文字小文字でも受け付けます。 |
| 時刻 | Unix 秒で、あらかじめ整形されることはありません。ブロックは 1 秒に約 2 回届き、タイムスタンプの分解能は 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 の応答に付きます。あるリクエストについて問い合わせる必要があるときは、これを引用してください。 |
ほかに 2 つの上限が実在し、隠さずに報告されます。ログのクエリはブロック範囲の最大幅に切り詰められ、範囲を超えたリクエストは黙って縮められるのではなく、その最大値をメッセージに明記して拒否されます。トレースとステート差分の呼び出しは、実時間の予算とサイズの上限を持つ小さな専用プールで走り、応答が止まる代わりに truncated: true を設定します。
当方のインデックスを介さずに Arc を読む
当方のビューではなくチェーンそのものが必要なら、メインネット向けにパブリックで読み取り専用の JSON-RPC エンドポイントも運用しています — パブリック RPCをご覧ください。スキーマより先に文章を読むもののために、このエクスプローラーが何を保持しているかを記したプレーンテキストの /llms.txt新しいタブで開きます もあります。