Arc 主网 API
你正在测试网站点上
自区块 0 起完整索引
链 5042 自创世区块起被完整索引，没有缺口，其背后的节点保留全部历史。任何区块、任何交易、任何收据、任何余额，一直回溯到链的起点。
不必凭信：一次调用即可自证，下面的数字就是从那次调用读出来的。
读自 /v1/chain，最快每小时刷新一次。
基础 URL
基础 URL 只有一个，就是它。
https://api-testnet.arc-scan.io可直接从浏览器调用：响应带有 access-control-allow-origin: *，允许 GET、HEAD 和 OPTIONS。并暴露 ETag、限流相关头部和 X-Request-Id，客户端可以直接读取而无需猜测。仅限这三种方法：浏览器无法在此发送 POST，因此 MCP 端点无法通过这种方式访问。curl、后端、机器人或索引器不受影响。
从这里开始
本页每一条命令都在运行中的服务上真实执行过，展示的每一段应答都是实际返回的内容。
持有什么，以及有多新
链的常量、节点能力，以及确切被索引的区块范围。一次调用之后，本页其余内容都不必凭信。
curl -s -H 'User-Agent: my-app/1.0' https://api-testnet.arc-scan.io/v1/chain
返回了
{ "chain_id": 5042, "name": "Arc", "is_testnet": false, "mainnet_soon": false, "native": { "symbol": "USDC", "decimals": 18 }, "erc20_native": { "address": "0x3600000000000000000000000000000000000000", "decimals": 6 }, "block_time_ms": 506, "finality": "instant", "capabilities": { "ots": false, "ots_search": false, "trace": true, "debug": false, "archive": true, "tx_index": true, "holder_index": true, "verified_source": false, "verified_source_note": "<-- elided -->", "internal_transactions": true }, "index": { "available": true, "streams": [ { "stream": "balances", "genesis_block": 0, "last_contiguous_block": 13849844, "from_block": 0, "to_block": 13849844, "ranges": 1, "blocks_indexed": 13849845, "contiguous_from_genesis": true }, { "stream": "chain", "genesis_block": 0, "last_contiguous_block": 13849856, "from_block": 0, "to_block": 13849856, "ranges": 1, "blocks_indexed": 13849857, "contiguous_from_genesis": true }, { "stream": "traces", "genesis_block": 0, "last_contiguous_block": -1, "from_block": null, "to_block": null, "ranges": 0, "blocks_indexed": 0, "contiguous_from_genesis": false } ], "head_block": 13849856, "chain_blocks_indexed": 13849857, "chain_genesis_block": 0, "chain_first_indexed_block": 0, "covers_chain_from_block": 0, "complete_above_start_block": true, "unindexed_blocks_below_start": 0, "complete": true, "message": null }, "capabilities_note": null, "capabilities_note_phrases": [] }
请发送 User-Agent
你现有的 Etherscan 代码已经在发的那个调用
密钥作为 <mono>apikey</mono> 放在查询串里，这正是 Etherscan 客户端已经放置它的位置。
curl -s -H 'User-Agent: my-app/1.0' "https://api-testnet.arc-scan.io/api?module=account\ &action=txlist&address=0x03a13352ef67977d1601ec1276e9bc27c0ee7b75\ &startblock=13800000&endblock=13830000&page=1&offset=1&sort=desc\ &apikey=YourApiKeyToken"
返回了
{ "status": "1", "message": "OK", "result": [ { "blockNumber": "13830000", "timeStamp": "1785842041", "hash": "0x3ae69af3843877c10d1aedde0fb299f0de358a76c4b704f338fc738b5d952ef5", "nonce": "88966", "blockHash": "", "transactionIndex": "0", "from": "0x92Df01DB3C69a49f4c4E694849E44C75D62B6752", "to": "0x03a13352eF67977d1601ec1276e9BC27C0Ee7b75", "value": "0", "gas": "598264", "gasPrice": "40000000000", "isError": "0", "txreceipt_status": "1", "input": "", "contractAddress": "", "cumulativeGasUsed": "348673", "gasUsed": "348673", "confirmations": "2933", "methodId": "0x38aaba3d", "functionName": "open" } ] }
迁移现有的 Etherscan 代码
某个地址交易的 CSV
每次导出都是针对一个地址，因此 <mono>address</mono> 是必填的，而区块或日期范围只是进一步收窄。四个数据集——<mono>transactions</mono>、<mono>internal</mono>、<mono>logs</mono>、<mono>token-transfers</mono>——并且 <mono>/v1/export/limits</mono> 会在你撞上上限之前先说明它们。
curl -s -H 'User-Agent: my-app/1.0' "https://api-testnet.arc-scan.io/v1/export/transactions/csv\ ?address=0x03a13352ef67977d1601ec1276e9bc27c0ee7b75\ &from_block=13800000&to_block=13800010"
返回了
block_number,block_time_utc,block_timestamp,tx_hash,tx_index,from,to,created_contract,direction,value_raw,value_18dec,fee_raw,fee_18dec,gas_limit,gas_used,effective_gas_price_raw,nonce,tx_type,method_id,input_size,status 13800001,2026-08-04T07:00:48Z,1785826848,0xb244d2791aa392fcc49e2c6bca9df0b6c402da2c1cd322f6356724fb77cc3131,0,0x8031885f93e31676132128557e987a011ff99d27,0x03a13352ef67977d1601ec1276e9bc27c0ee7b75,,in,0,0,13951720000000000,0.01395172,570664,348793,40000000000,141603,2,0x38aaba3d,516,success
新区块是被推送的，不是轮询来的
/v1/stream/head 是真正的 text/event-stream：每个已提交区块一条事件，在半秒出块的链上约每秒两条，每条都携带服务器自己的时钟，便于消费者校正时差。保持连接打开，区块就会自己到来。没有什么可轮询，也没有间隔需要调。
跟随链头
这条命令不会返回。下面是一次实时连接中相邻的两条事件，相隔三秒。
curl -N -H 'User-Agent: my-app/1.0' https://api-testnet.arc-scan.io/v1/stream/head
返回了
event: head data: {"height": 13830746, "hash": "0xc580470583007f827ebfb3098b66d0682528c4ebaca4eb1213ab992c5952e65e", "timestamp": 1785842418, "tx_count": 1, "server_now": 1785842422, "available": true} event: head data: {"height": 13830751, "hash": "0x63d064be03dc0f5d530e10350b8dddd3de2cc8e6dbbffbe59306bb9fdc96c162", "timestamp": 1785842421, "tx_count": 1, "server_now": 1785842422, "available": true}
提供什么
逐条路由在运行中的主网服务上人工核对，而非由 schema 生成。服务发布的路由比这里列出的多；列出的是我们支持的。
| 端点 | 回答什么 |
|---|---|
/v1/chain | 链 id、原生代币、节点能力，以及每个索引流所持有的确切区块范围。 |
/v1/network/status/v1/network/validators | 链头及其秒级年龄、实测出块时间，以及活跃验证者集合。 |
/v1/blocks/v1/blocks/{ref}/v1/blocks/{ref}/txs | 由新到旧的区块、单个区块，以及其中的交易。每个区块都写明提议它的验证者。 |
/v1/txs/v1/txs/{hash}/v1/txs/{hash}/trace/v1/txs/{hash}/raw | 由新到旧的交易、单笔交易及其状态与回滚原因、为其还原出的内部调用帧，以及其背后未经修改的节点对象。 |
/v1/address/{addr}/v1/address/{addr}/txs/v1/address/{addr}/logs/v1/address/{addr}/activity | 一个地址及其余额与活动、它收发的交易、它发出的事件日志，以及一条汇总了所有涉及它之事的时间线。 |
/v1/address/{addr}/tokens/v1/address/{addr}/facts/v1/address/{addr}/contract | 地址持有的代币余额、它的资金来源与首末活跃时间，若为合约还包括其已部署的字节码。 |
/v1/tokens/{addr}/v1/tokens/{addr}/holders/v1/tokens/{addr}/transfers | 单个代币的链上事实、按余额排名的持有者，以及它的转账。 |
/v1/approvals/{addr} | 某地址已授予且未撤销的全部 ERC-20、ERC-721 与 ERC-1155 授权。 |
/v1/search/v1/search/suggest | 解析高度、哈希、地址或代币，并在输入时给出建议。 |
/v1/stats/summary/v1/stats/gas/v1/stats/tx-history | 网络概览、gas 统计，以及按完整 UTC 日计的每日交易历史。 |
/v1/charts/v1/charts/{metric}/v1/charts/{metric}/csv | 二十四项每日指标的目录，每项都可读作 JSON 或 CSV。 |
/v1/explore/* | 全链列表：账户、合约、代币、代币转账、地址标签、具名实体名录，以及选定窗口内的顶级统计。 |
/v1/filter/limits/v1/filter/transactions/v1/filter/token-transfers | 按地址、方法、金额、资产、状态与范围查询交易与代币转账。限制路由会在你撞上边界之前先说明边界。 |
/v1/export/limits/v1/export/resolve/v1/export/{dataset}/csv | 交易、内部交易、日志与代币转账的 CSV，另有一个把日期范围映射为区块范围的路由。导出永远是针对一个地址的：address 必填，范围只是收窄而不是替代它。 |
/v1/actions/categories | 用于归类一笔交易实际做了什么的类别。 |
/v1/stream/head | 服务器推送事件，每个已提交区块一条，各自携带服务器时钟，便于消费者校正时差。 |
Etherscan 形态的接口
一个路径，按查询串里的 module 与 action 分派。每个应答都是 HTTP 200，因此严格的客户端库不会因状态码而崩溃。GET 与 form-encoded 的 POST 都接受，而 module=proxy 会把十三个 JSON-RPC 方法直接透传给节点。
| module | action | 回答什么 |
|---|---|---|
account | balance | 原生余额，18 位小数的整数字符串 |
account | balancemulti | 每次调用最多 20 个地址 |
account | txlist | 某个地址发出或收到的交易，读自索引 |
account | tokentx | 取自已扫描窗口；需要 startblock 与 endblock本链上代币名称、符号与小数位字段返回为空。请从代币路由读取精度，而不要从转账记录里读。 |
account | tokenbalance | 真正的 ERC-20 查询；返回合约自身的小数精度 |
account | addresstokenbalance | 一个地址持有的全部代币余额 |
block | getblockreward | blockReward 是交易费之和；没有增发，也没有叔块奖励 |
block | getblocknobytime | 在高度上做二分查找；不可变，永久缓存 |
block | getblockcountdown | 使用实测出块时间，而非常量 |
transaction | getstatus | 执行状态 |
transaction | gettxreceiptstatus | 收据状态 |
logs | getLogs | 范围受限；超范围请求会在响应中指明最大跨度 |
contract | getabi | 在 Arcscan 上已验证合约的 ABI本链上尚无任何合约通过验证，因此 getabi 返回 NOTOK，getsourcecode 返回一条空记录。无论哪种情况，已部署的字节码都会提供。 |
contract | getsourcecode | 已验证的源码、编译器设置与 ABI本链上尚无任何合约通过验证，因此 getabi 返回 NOTOK，getsourcecode 返回一条空记录。无论哪种情况，已部署的字节码都会提供。 |
token | tokenholderlist | 单个代币的持有人和余额 |
stats | tokensupply | 总供应量，直接读自合约 |
stats | ethsupply | 原生供应量，18 位小数的整数字符串 |
stats | ethprice | gas 代币按构造即为美元，因此这里返回 1.00 |
stats | dailytxnfee | 每个完整 UTC 日的交易手续费总额 |
stats | dailynewaddress | 每个完整 UTC 日内首次出现的地址数 |
proxy | eth_* | 区块、交易、call、code、storage、gas 与裸发送方法 |
速率限制、错误与分页
速率限制
公共调用者拥有 300 次请求的突发额度，并以每秒 60 次的速度回填。每个应答都会告诉你当前位置，而被拒绝时是 HTTP 429，并带上 retry-after。
该桶按我们边缘所看到的调用方地址计数，因此共用一个 NAT 或同一个云出口地址的调用方共享同一个桶。
x-ratelimit-limit: 300 x-ratelimit-remaining: 299
错误
在 /api 上，拒绝是 HTTP 200，其中 status 为 0，result 里是一句说明原因的话，而绝不是 404，因此严格的客户端库不会在它上面崩溃。
在 /v1 上，被判定为非法的请求经边缘返回的是 404 而不是 400。在断定某条路由不存在之前，先检查参数。
分页
列表路由使用游标分页：应答里带有 page.next，把它作为 cursor 传回即可取得下一页。每页上限为 100 条。
这个 API 不回答什么
公开出来，是为了让你提前绕开，而不是自己撞上去才发现。
内部交易
就单笔交易发问，你会拿到它的内部调用：单笔交易的轨迹路由返回 200 与真实的帧，account/txlistinternal 在传入 txhash 时返回同样的帧。就某个地址或整条链发问，得到的则是拒绝，因为本部署上 Arcscan 自己的轨迹索引没有任何区块：/v1/explore/internal-txs 返回 501 CAPABILITY_UNAVAILABLE 并写明缺失的能力，account/txlistinternal 按 address 查询会拒绝并说明原因，internal 的 CSV 导出只返回表头、没有数据行。那是一个你能察觉的拒绝，而绝不是一份你无法察觉的残缺列表。状态变更是另一个缺口：单笔交易的状态路由仍然返回 501，因为状态差异必须把交易放回其所在区块之前的状态上重新执行才能得到，而本链所读取的那个端点不提供这项调用。
一次日志查询能覆盖多远
logs/getLogs 在链 5042 上可以作答，单次跨度最多 10,000 个区块；超出范围的请求会被拒绝并写明这个上限，而不是悄悄只回答其中一部分。account/tokentx 同样可以作答，需要 startblock 与 endblock，且跨度最多 200,000 个区块。这两个上限都不适用于我们自己的索引，更大范围的问题由它来回答：按地址走地址日志路由，按代币走代币转账路由，全链则走 /v1/explore/token-transfers。
已验证的源码
我们的验证提供方不覆盖链 5042，因此今天这里没有任何合约通过验证，在此改变之前也无法通过。已部署字节码、创建字节码与合约创建者仍然照常提供。
链下数据
没有预言机价格，没有市值，没有 logo，没有网站，没有人工整理的交易所标签。我们发布的地址标签，是能从链上数据证明的那些——验证者、系统合约、我们亲眼看着部署的合约——而且不会有靠猜的标签。
以拒绝作答的操作
每一条都在 result 里带上自己的原因，而不是一个笼统的错误。
contract.getcontractcreation- 链 5042 背后的节点未暴露 otterscan 命名空间。合约的创建者与创建交易在按地址的合约路由上。
account.getminedblocks- Arc 没有挖矿，也没有出块奖励：区块由轮换的 BFT 验证者集合提议，区块中唯一的价值就是其交易手续费。提议者那一列也没有索引，因此不做全表扫描就无法回答。改由区块路由写明验证者。
account.tokennfttx- ERC-721 转账有索引，但不是按地址索引：转账表没有发送方与接收方的索引，因此按地址过滤将是一次全表扫描。它们可按代币以及全链读取。
account.token1155tx- ERC-1155 同上。
account.addresstokennftbalance- 我们的余额流只存储同质化余额——每个「代币与持有者」一个数额，没有 token id 维度——因此无法从中读出 NFT 清单。这个问题的 ERC-20 形态是有答案的。
token.tokeninfo- 该操作的多数字段都在链下：价格、市值、网站、社交链接。Arcscan 不持有任何链下代币数据，也不查询价格预言机。链上的那一半——名称、符号、小数位、总供应量、持有者数——由代币路由提供。
contract.verifysourcecode- 验证不接受 Etherscan 那种把源码摊平的表单字段。请通过验证页面提交 Solidity 标准 JSON，那里才是该路由可达的地方。
申请密钥
从服务自身 schema 生成的逐路由完整参考，在 API 文档页面。