explorer-monorepo/docs/API.md

# API Reference

Canonical, machine-readable spec: [`backend/api/rest/swagger.yaml`](../backend/api/rest/swagger.yaml)
(OpenAPI 3.0.3). This document is a human index regenerated from that
file — run `scripts/gen-api-md.py` after editing `swagger.yaml` to
refresh it.

## Base URLs

| Env | URL |
|-----|-----|
| Production | `https://api.d-bis.org` |
| Local dev | `http://localhost:8080` |

## Authentication

Track 1 endpoints (listed below under **Track1**, **Health**, and most
of **Blocks** / **Transactions** / **Search**) are public. Every other
endpoint requires a wallet JWT.

The flow:

1. `POST /api/v1/auth/nonce` with `{address}`  → `{nonce}`
2. Sign the nonce with the wallet.
3. `POST /api/v1/auth/wallet` with `{address, nonce, signature}`
   → `{token, expiresAt, track, permissions}`
4. Send subsequent requests with `Authorization: Bearer <token>`.
5. Refresh before `expiresAt` with
   `POST /api/v1/auth/refresh` (see [ARCHITECTURE.md](ARCHITECTURE.md)).
6. Log out with `POST /api/v1/auth/logout` — revokes the token's
   `jti` server-side.

Per-track TTLs:

| Track | TTL |
|-------|-----|
| 1 | 12h |
| 2 | 8h |
| 3 | 4h |
| 4 | 60m |

## Rate limits

| Scope | Limit |
|-------|-------|
| Track 1 (per IP) | 100 req/min |
| Tracks 2–4 | Per-user, per-subscription; see subscription detail in `GET /api/v1/access/subscriptions` |

## Endpoint index

## Health
Health check endpoints
- `GET /health` — Health check

## Auth
Wallet and user-session authentication endpoints
- `POST /api/v1/auth/nonce` — Generate wallet auth nonce
- `POST /api/v1/auth/wallet` — Authenticate with wallet signature
- `POST /api/v1/auth/refresh` — Rotate a still-valid JWT (adds a new `jti`; revokes the old one) — PR #8
- `POST /api/v1/auth/logout` — Revoke the current JWT by `jti` — PR #8
- `POST /api/v1/auth/register` — Register an explorer access user
- `POST /api/v1/auth/login` — Log in to the explorer access console

## Access
RPC product catalog, subscriptions, and API key lifecycle
- `GET /api/v1/access/me` — Get current access-console user
- `GET /api/v1/access/products` — List available RPC access products (backed by `backend/config/rpc_products.yaml`, PR #7)
- `GET /api/v1/access/subscriptions` — List subscriptions for the signed-in user
- `GET /api/v1/access/admin/subscriptions` — List subscriptions for admin review
- `POST /api/v1/access/admin/subscriptions` — Request or activate product access
- `GET /api/v1/access/api-keys` — List API keys for the signed-in user
- `POST /api/v1/access/api-keys` — Create an API key
- `POST /api/v1/access/api-keys/{id}` — Revoke an API key
- `DELETE /api/v1/access/api-keys/{id}` — Revoke an API key
- `GET /api/v1/access/usage` — Get usage summary for the signed-in user
- `GET /api/v1/access/audit` — Get recent API activity for the signed-in user
- `GET /api/v1/access/admin/audit` — Get recent API activity across users for admin review
- `GET /api/v1/access/internal/validate-key` — Validate an API key for nginx auth_request or similar edge subrequests
- `POST /api/v1/access/internal/validate-key` — Validate an API key for internal edge enforcement

## Blocks
Block-related endpoints
- `GET /api/v1/blocks` — List blocks
- `GET /api/v1/blocks/{chain_id}/{number}` — Get block by number

## Transactions
Transaction-related endpoints
- `GET /api/v1/transactions` — List transactions

## Search
Unified search endpoints
- `GET /api/v1/search` — Unified search

## Track1
Public RPC gateway endpoints (no auth required)
- `GET /api/v1/track1/blocks/latest` — Get latest blocks (Public)

## MissionControl
Public mission-control health, bridge trace, and cached liquidity helpers
- `GET /api/v1/mission-control/stream` — Mission-control SSE stream
- `GET /api/v1/mission-control/liquidity/token/{address}/pools` — Cached liquidity proxy
- `GET /api/v1/mission-control/bridge/trace` — Resolve a transaction through Blockscout and label 138-side contracts

## Track2
Indexed explorer endpoints (auth required)
- `GET /api/v1/track2/search` — Advanced search (Auth Required)

## Track4
Operator endpoints (Track 4 + IP whitelist)
- `POST /api/v1/track4/operator/run-script` — Run an allowlisted operator script

## Error shape

All errors use:

```json
{
  "error": "short_code",
  "message": "human-readable explanation"
}
```

Common codes:

| HTTP | `error` | Meaning |
|------|---------|---------|
| 400 | `bad_request` | Malformed body or missing param |
| 401 | `unauthorized` | Missing or invalid JWT |
| 401 | `token_revoked` | JWT's `jti` is in `jwt_revocations` (PR #8) |
| 403 | `forbidden` | Authenticated but below required track |
| 404 | `not_found` | Record does not exist |
| 405 | `method_not_allowed` | HTTP method not supported for route |
| 429 | `rate_limited` | Over the track's per-window quota |
| 503 | `service_unavailable` | Backend dep unavailable or migration missing |

## Generating client SDKs

The `swagger.yaml` file is standard OpenAPI 3.0.3; any generator works.

```bash
# TypeScript fetch client
npx openapi-typescript backend/api/rest/swagger.yaml -o frontend/src/api/types.ts

# Go client
oapi-codegen -package explorerclient backend/api/rest/swagger.yaml > client.go
```