cardano-api/README.md

cardano-api

REST API over cardano-db-sync + cardano-node. FastAPI + asyncpg + Redis.

Read paths hit the db-sync Postgres. UTxO queries, protocol params, and tx submit shell out to cardano-cli against a local node socket. Auth is TRP token-gated via CIP-8 wallet signatures.

Stack

• FastAPI / uvicorn
• asyncpg → cardano-db-sync Postgres (cexplorer)
• redis.asyncio → rate limiting + response cache + API-key storage
• cardano-cli (baked into the image) → node socket queries + tx submit
• pycardano + PyNaCl + cbor2 → CIP-8 verification

Run

docker compose up -d --build

Listens on :8765 inside the container. Wire it to whatever proxy / port-forward the deploy wants.

Tiers + rate limits

Tier	TRP needed	Rate (req/min)	tx submit (per min)	Node read	Node submit
anonymous	0	20	0	no	no
standard	≥50	100	2	yes	no
elevated	≥500	1000	10	yes	yes
master	n/a	unlimited	unlimited	yes	yes

Anonymous is rate-limited per source IP. Authed tiers are rate-limited per key.

TRP-gated keys expire 48h after issue and must be re-auth'd. A background task re-checks balances every 10 minutes and re-tiers in place.

Auth flow (TRP-gated)

POST /v1/auth/challenge  { "address": "addr1..." }
  → { "nonce": "...", "expires_at": "..." }

# sign nonce with the wallet via CIP-8

POST /v1/auth/verify     { "address", "nonce", "signature", "key" }
  → { "api_key": "capi_...", "tier", "trp_balance" }

POST /v1/auth/refresh    (X-API-Key header — self-service only)
  → { "tier", "trp_balance", "expires_at", ... }

Master key is issued out-of-band via API_MASTER_KEY env. Master-key-created keys (/admin/keys) don't expire.

Header is preferred (X-API-Key: capi_...); ?api_key= works too.

Endpoints

GET  /health
GET  /v1/sync/status

GET  /v1/block/latest
GET  /v1/block/{block_no}

GET  /v1/address/{address}/balance
GET  /v1/address/{address}/tokens?page=&limit=
GET  /v1/address/{address}/transactions?page=&limit=&order=
GET  /v1/address/{address}/utxos                            (standard+)

GET  /v1/tx/{tx_hash}
POST /v1/tx/submit                                          (elevated+)

GET  /v1/asset/{policy_id}/info?page=&limit=
GET  /v1/asset/{policy_id}/{asset_name}/holders?limit=

GET  /v1/pool/{pool_id}/info

GET  /v1/protocol-params                                    (standard+)

POST /v1/auth/challenge
POST /v1/auth/verify
POST /v1/auth/refresh

POST   /admin/keys                                          (master)
DELETE /admin/keys/{key}                                    (master)
GET    /admin/keys                                          (master)
POST   /admin/refresh-tiers                                 (master)
GET    /admin/stats                                         (master)

Cache TTLs (Redis)

balance        60s
tokens         60s
transactions   30s
block_latest   10s
tx_details    300s   (immutable)
asset_info    120s
pool_info     120s
sync_status     5s
protocol_params 300s
utxos          10s

Validation

Inputs hit regex gates before any DB query:

• bech32 mainnet/testnet addresses (addr1... / addr_test1...)
• 64-hex tx hashes
• 56-hex policy IDs

Tx submit body is capped at 64 KB (middleware reads the actual stream; chunked transfer can't bypass).

CIP-8 verification rejects non-EdDSA (alg ≠ -8), wrong key length, empty payload, payload-not-nonce, and bad key→address hash binding.

Key storage

Keys are stored as sha256(key). The raw key is returned exactly once at issue. Lookups, admin listing, and revoke all operate on the hash.

TRP-gated keys are tracked in a trp_gated_keys Redis set so the refresh task can batch a single Postgres query for all owner addresses instead of N+1.

Known policy IDs

TRP  9c4bd4a90cdb73d9ff681215ecf7dea9fb183d916d30487d17098e05
MAP  24bd9e7b9ae3a61df79eca72fd8355d0f7767e4c55a04a0d919c019c

Environment

DB_HOST            (default: postgres-dbsync — compose service name)
DB_PORT            5432
DB_NAME            cexplorer
DB_USER            dbsync
DB_PASS

REDIS_HOST         (default: redis-api — compose service name)
REDIS_PORT         6379

API_MASTER_KEY     unrestricted-tier key

CARDANO_NODE_SOCKET_PATH   /node-ipc/node.socket
CARDANO_NETWORK            mainnet

TRUSTED_PROXIES (in main.py) is the set of IPs whose X-Forwarded-For header is honoured. Defaults to loopback + the docker default bridges. If the deployment fronts the API with a different proxy, override the set.