Документация API

Типизированный API живёт по пути /v1. Именно из него рендерится сам этот сайт, поэтому всё, что вы видите на странице, можно прочитать и как JSON — в том же виде.

Совместимый API живёт по адресу /api?module=…&action=…. Он воспроизводит де-факто стандартный REST-контракт эксплореров, который уже понимают кошельки, индексаторы, скрипты деплоя и боты, так что существующие инструменты переводятся на Arc сменой одного базового URL. Каждое скалярное значение внутри result — строка, ровно как этого требует контракт.

GET /v1/blocks/latest
GET /api?module=proxy&action=eth_blockNumber
GET /api?module=account&action=balance&address=0x…

Примеры выше — это метод и путь, без хоста перед ними. Опубликованного базового URL для API пока нет — см. уведомление в начале страницы.

Регистр:

Ключи JSON — snake_case. Адреса и хеши на проводе в нижнем регистре; отображаемую форму несёт поле checksum. На входе принимается любой регистр.

Большие целые:

Каждое значение, способное превысить 2⁵³ — суммы, газ, предложение — передаётся десятичной строкой. Высоты блоков — это числа JSON. Разбор суммы как JavaScript-числа тихо её портит.

Суммы:

Суммы передаются объектом Money: raw (целое строкой), decimals, formatted (точно, с полной точностью), usd и symbol. Знаки после запятой всегда читаются из контракта; никогда не выводите масштаб из символа.

Время:

Секунды Unix, никогда не отформатированные заранее. Метки времени блоков имеют разрешение в одну секунду, а блоки приходят примерно дважды в секунду, поэтому метки времени не задают полного порядка — не сортируйте и не разбивайте по ним на страницы.

Постраничность:

Непрозрачные курсоры, а не номера страниц. Курсор остаётся годным навсегда, потому что в Arc нет реорганизаций. Оконные эндпоинты дополнительно возвращают диапазон блоков, который был реально просканирован.

Ошибки:

{"error":{"code":"NOT_FOUND","message":"…","detail":null}}

Коды: INVALID_INPUT (400), NOT_FOUND (404), RATE_LIMITED (429), CAPABILITY_UNAVAILABLE (501), UPSTREAM_ERROR (502), UPSTREAM_TIMEOUT (504).

Кеширование:

Всё, что определяется зафиксированной высотой блока или хешем попавшей в блок транзакции, неизменяемо и отдаётся с Cache-Control: public, max-age=31536000, immutable. Это более сильная гарантия, чем может дать вероятностная цепь, и на неё стоит опираться.

/v1/stream/head — это поток server-sent events, выдающий по одному событию head на каждый зафиксированный блок. Полезная нагрузка несёт server_now, чтобы клиент мог скорректировать расхождение часов, а не доверять часам браузера.

event: head
data: {"height":54190133,"hash":"0x…","timestamp":1785345456,"tx_count":11,"server_now":1785345456}

Потока ожидающих транзакций нет. Пространство имён mempool в этой сети отключено, а при полусекундном блоке страница ожидания показывала бы транзакцию меньше времени, чем нужно, чтобы её прочитать.

Газ оплачивается долларами:

Токен газа — USDC. Комиссии, балансы и суммы транзакций выражены в долларах, и Arcscan показывает точную долларовую величину без всякого оракула.

В совместимом API значения остаются 18-знаковыми:

value, gasPrice, gasUsed и cumulativeGasUsed остаются целыми строками с 18 знаками. Разделите на 10¹⁸ — получите верную долларовую величину. Мы никогда не «помогаем» их пересчитать: это испортило бы каждого интегрирующегося бота в триллион раз.

Один доллар, два представления:

Нативный баланс несёт 18 знаков; интерфейс ERC-20 того же актива — 6. Прекомпайл держит их в паритете, поэтому erc20 = native / 10^12 ровно. account.balance возвращает нативную величину, а account.tokenbalance — величину ERC-20. Верны обе. Их сложение считает одни и те же доллары дважды.

Знаки токена никогда не берутся по умолчанию:

tokenDecimal всегда читается из контракта. Два контракта в этой сети могут иметь одинаковый символ и разный масштаб, поэтому таблица «символ → знаки» здесь неверна по построению.

Финальность детерминирована:

confirmations выдаётся ради совместимости, а рядом с ним выдаётся дополнительное поле isFinalized. Вероятностного окна безопасности нет: зафиксированный блок финален. В собственном интерфейсе Arcscan никогда не показывает число подтверждений.

Имена полей сохраняют написание:

Имена методов и полей в совместимом интерфейсе — это идентификаторы протокола, и они воспроизводятся точно, чтобы существующие клиенты продолжали работать. От Arc здесь только значения.

Они возвращают стандартную оболочку ошибки с HTTP 200 — никогда 404, чтобы клиентская библиотека не падала. У каждого своя причина, а не одна общая фраза: индекс, который мы не строим; структурное свойство самой сети Arc; либо работающий эндпоинт под другим именем.

• account.getminedblocks
• account.tokennfttx
• account.token1155tx
• account.addresstokennftbalance
• token.tokeninfo
• contract.verifysourcecode

Два действия с историей NFT запрашивают чаще всего, и ни на одно из них нельзя ответить по адресу. Форма для ERC-20, account.tokentx, отвечает и требует явно указанных startblock и endblock.

Ограничение частоты:

Token bucket по IP, применяется на пограничном узле, а не в приложении. Какой именно бюджет будет действовать для внешних клиентов, ещё не решено, поэтому числа здесь нет; оно появится на этой странице, когда API откроют.

Диапазон логов:

Запросы логов ограничены максимальным размахом блоков. Запрос сверх лимита отклоняется с указанием максимума в сообщении, а не обрезается молча.

Тяжёлые эндпоинты:

Эндпоинты трассировки и диффа состояния работают на небольшом выделенном пуле с бюджетом по времени и лимитом размера ответа и сообщают truncated: true, а не зависают.