REST API

The REST API provides indexed views over Arch blocks, transactions, programs, tokens, accounts, and network statistics. This page is generated from the OpenAPI specification shipped with the API server, so it stays in sync with the backend.

Base URL

# Mainnet
https://explorer.arch.network/api/v1/mainnet

# Testnet
https://explorer.arch.network/api/v1/testnet

Legacy JSON-RPC compatibility

The JSON-RPC compatibility endpoint is for applications migrating away from direct Arch validator RPC calls. Existing clients can switch their base URL to the indexer while keeping the validator method names and JSON-RPC 2.0 envelope. New read-heavy integrations should prefer the native REST and WebSocket APIs above.

Endpoints

# Mainnet
https://explorer.arch.network/api/v1/mainnet/rpc

# Testnet
https://explorer.arch.network/api/v1/testnet/rpc

# Default network context
https://explorer.arch.network/api/v1/rpc

The endpoint supports JSON-RPC 2.0 single requests, notifications, and batches. It is feature-gated on the API server with RPC_COMPAT__ENABLED=true.

Example request

curl "https://explorer.arch.network/api/v1/testnet/rpc" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"get_block_count","params":[]}'

Discover supported methods

Call rpc.discover to see the methods exposed by the running indexer and whether each method is served from indexed data, proxied to the validator, or answered locally.

curl "https://explorer.arch.network/api/v1/testnet/rpc" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"rpc.discover","params":[]}'

Method sources

• db - served from the indexer's Postgres copy of chain data.
• hybrid - served from Postgres first, with validator fallback for indexer lag or schema gaps.
• proxy - forwarded to the configured upstream validator.
• local - answered by the API server process.

Supported validator methods

The compatibility surface tracks the production Arch validator RPC module. Methods that the validator does not expose are intentionally not invented here.

Migration guidance

1. Point existing validator JSON-RPC clients at the indexer RPC endpoint.
2. Run smoke tests for the methods your application uses.
3. Use rpc.discover to identify which calls are indexed, hybrid, proxied, or local.
4. Migrate read-heavy paths to native REST endpoints as equivalents exist.
5. Use WebSockets for live updates instead of polling JSON-RPC reads.
6. Keep transaction submission on JSON-RPC until a purpose-built native write endpoint is available.

Recommended migration examples: block and transaction reads should move to the REST endpoints in this page; realtime updates should move to WebSockets; validator-local state and write methods can remain on JSON-RPC during the transition.

WebSockets

Subscribe to realtime blocks, transactions, and account updates over a single WebSocket connection.

Endpoints & authentication

The realtime API exposes a single WebSocket endpoint plus a small HTTP status endpoint:

• wss://explorer.arch.network/ws – primary WebSocket endpoint for realtime events.
• GET https://explorer.arch.network/api/v1/mainnet/websocket/stats – status for mainnet.
• GET https://explorer.arch.network/api/v1/testnet/websocket/stats – status for testnet.

Authenticate by passing your API key as a query parameter:

Connection URL

wss://explorer.arch.network/ws?apikey=YOUR_API_KEY

Messages

Messages are JSON objects with a simple RPC-style shape:

{"method": "subscribe", "topic": "block"}

{"method": "ping"}

{"status": "pong", "timestamp": 1735689600}

Sample events

Every event sent by the server has the shape { "topic": string, "data": object, "timestamp": string }. Supported topics today are:

• block – new blocks as they are indexed.
• transaction – transactions as they are processed.
• account_update – account balance / state changes.
• rolledback_transactions – transactions rolled back due to a reorg.
• reapplied_transactions – transactions re-applied after a reorg.
• dkg – distributed key generation / validator coordination events.

{
  "topic": "block",
  "data": {
    "height": 12345,
    "hash": "....",
    "transaction_count": 42,
    "timestamp": "2025-01-01T00:00:00Z"
  },
  "timestamp": "2025-01-01T00:00:00Z"
}

Client example

const apiKey = process.env.ARCH_API_KEY!;
const ws = new WebSocket('wss://explorer.arch.network/ws?apikey=' + apiKey);

ws.onopen = () => {
  ws.send(JSON.stringify({ method: 'subscribe', topic: 'block' }));
};

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  console.log('[block]', msg);
};

ws.onclose = () => {
  console.log('connection closed');
};

Authentication

All non-public Arch Indexer API endpoints require an API key. Keys are tied to an account and plan (Free or Enterprise) and are used for both HTTP and WebSocket access.

Getting an API key

1. Register a new account via the Developer Portal at /dev or with POST /api/v1/auth/register.
2. Optionally log in with POST /api/v1/auth/login for backend workflows.
3. Use the onboarding wizard in the Developer Portal to create your first app.
4. From the app dashboard, create additional app-scoped keys as needed for different environments (e.g. Production vs Staging).

Example: create an account

POST /api/v1/auth/register
Content-Type: application/json

{
  "email": "you@example.com",
  "password": "a-strong-password"
}

Using API keys with REST

Send your key in either of these headers:

• Authorization: Bearer <API_KEY> (recommended)
• X-API-Key: <API_KEY>

curl example

# Mainnet
curl "/api/v1/mainnet/blocks?limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Testnet
curl "/api/v1/testnet/blocks?limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

JavaScript example (fetch)

// Mainnet
const res = await fetch('/api/v1/mainnet/blocks?limit=10', {
  headers: {
    Authorization: 'Bearer ' + process.env.ARCH_API_KEY,
  },
});
const data = await res.json();

// Testnet
const res = await fetch('/api/v1/testnet/blocks?limit=10', {
  headers: {
    Authorization: 'Bearer ' + process.env.ARCH_API_KEY,
  },
});
const data = await res.json();

Using API keys with WebSockets

For WebSockets, pass the API key as a query parameter. This mirrors how platforms like Alchemy authenticate realtime connections.

wss://explorer.arch.network/ws?apikey=YOUR_API_KEY

Apps and app-scoped keys

Each account can own multiple apps. Apps are logical containers for keys and usage – for example, "Wallet backend" or "Analytics dashboard". You create and manage apps and their keys from the Developer Portal; the underlying management APIs are not exposed as part of the public surface area.

Error responses

Authentication errors use a consistent JSON shape:

HTTP 401
{
  "error": "missing_api_key",
  "message": "API key is required. Provide it via the Authorization: Bearer <key> header or X-API-Key header."
}

Rate limits & quotas

The Arch Indexer API enforces per-key rate limits and monthly quotas to ensure reliable service for everyone.

Free plan

• ~25 requests per second per API key.
• ~30M requests per month per account (across keys).
• Reasonable WebSocket usage for realtime subscriptions.

Throttling behavior

When a limit is exceeded, the API responds with HTTP 429:

HTTP 429
{
  "error": "rate_limit_exceeded",
  "message": "Per-second request limit exceeded for this API key.",
  "limit_rps": 25
}

For monthly quota exhaustion:

HTTP 429
{
  "error": "monthly_quota_exceeded",
  "message": "Monthly quota exceeded for this API key.",
  "limit_monthly": 30000000
}

Best practices

• Implement client-side retries with exponential backoff on 429.
• Spread traffic across a small number of keys rather than many tiny keys.
• Use WebSockets for high-frequency realtime updates instead of polling.