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

https://explorer-beta.test.arch.network/api/v1

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-beta.test.arch.network/ws – primary WebSocket endpoint for realtime events.
• GET https://explorer-beta.test.arch.network/api/v1/websocket/stats – JSON status for monitoring and debugging.

Authenticate by passing your API key as a query parameter:

Connection URL

wss://explorer-beta.test.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-beta.test.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

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

JavaScript example (fetch)

const res = await fetch('/api/v1/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-beta.test.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.