Introduction

Access ErgoScan data: blocks, boxes, transactions, addresses, tokens, NFTs, Spectrum DEX, Rosen, oracles, storage rent, mempool. Free. No signup. No key. Same host as the explorer.

A link to ErgoScan is welcome. It is not required.

Base

/api/v1 and /v1 are the same router.

• Docshttps://ergoscan.me/docs
• OpenAPIhttps://ergoscan.me/openapi.json
• GraphQL · POSThttps://ergoscan.me/api/v1/graphql
• WebSocketwss://ergoscan.me/v1/stream

API Specification

OpenAPI 3 at /openapi.json. GraphQL is POST only (/v1/graphql, /api/v1/graphql). GET GraphQL is 405.

/api/v1 and /v1 are the same router. Wallet paths (unspent, balance, submit, headers) live on this host.

Responses come from our Postgres index and mempool RAM. This is the ErgoScan explorer API, not a live proxy of another site.

nanoERG and token raw amounts are decimal strings. Parse with BigInt. JSON numbers overflow LP and emission.

Heights, global indexes, and sizes are JSON numbers. Timestamps are unix milliseconds (UTC).

User GET does not call the node. The only user write is POST /mempool/transactions/submit and GraphQL submitTx. Client errors: rejected or submit_failed.

An address that fails the Ergo checksum returns 400 { error: bad_address, reason: checksum }. A valid address with no history returns an empty result.

Existing fields stay. New fields and paths may appear. GET /tokens catalog shape is frozen.

GraphQL reads the same index. Depth ≤ 7. gix windows ≤ 10 000 (4s). submitTx shares the submit limit.

Cross-Origin Resource Sharing

CORS is open: Access-Control-Allow-Origin: *. Wallets and dApps call from the browser. Do not send cookies or credentials.

Authentication

None. No API key. No paid plan.

Pagination

Keyset cursor. If another page exists, JSON has hasMore: true and nextCursor. Repeat with ?cursor=<nextCursor>. Wallet lists also take limit ≤ 100 and offset ≤ 500 as a small skip on an address index — not OFFSET down the chain. Prefer cursor.

Rate Limit

Reads: 120 requests per minute per IP. The window is one minute. Submit (REST + GraphQL submitTx): 10 per minute, 2 in flight, one shared bucket. Over limit: 429 { error: "rate_limited", retryAfterSec }. Reads also send X-RateLimit-Limit and X-RateLimit-Remaining. WebSocket /v1/stream and /v1/media/ are not in the read bucket.

Reads

120 requests / minute / IP

Submit

10 / minute, 2 in flight. REST submit and GraphQL submitTx share this bucket.

Over limit

429, JSON { error: rate_limited, retryAfterSec }

Examples

Machines

The same contract is in OpenAPI info.description. Paths and schemas follow. Amounts in schemas are strings.