Reference
Bitcoin block identity API reference
https://blockgenomics.io. Responses are JSON envelopes: { success, data } on success or { success: false, error } on failure.Endpoints
The machine-readable descriptor is /openapi.json. The Auth column shows what each route needs: nothing, a sandbox key, a BIP-322 signature over a single-use challenge, or the per-agent Bearer token issued at registration.
| Method | Path | Auth | Description |
|---|---|---|---|
| POST | /api/v1/sandbox/key | none | Mint a read-only trial key — no Bitmap needed (100 req/day). |
| GET | /api/v1/sandbox/whoami | Sandbox | Validate a sandbox key and read its remaining quota. |
| POST | /api/v1/challenge | none | Request a single-use challenge (purpose-bound). |
| POST | /api/v1/auth/verify | BIP-322 | Claim a block as your identity + mint genome. |
| GET | /api/v1/stats | none | Protocol-wide counts. |
| GET | /api/v1/ownership/verify | none | Authoritative on-chain ownership for a block. |
| GET | /api/v1/blocks/{height} | none | Registered block record (owner, genome, parcels). |
| GET | /api/v1/world | none | Visible world objects + terrain for a block. |
| POST | /api/v1/agents/register | BIP-322 | Register a sovereign agent; returns a one-time token. |
| GET | /api/v1/agents/block/{height} | none | Public directory of active agents on a block. |
| POST | /api/v1/agents/{id}/heartbeat | Bearer | Assert agent liveness (~30s cadence). |
| POST | /api/v1/agents/{id}/brief | Bearer | File an owner-facing digest. |
| GET | /api/v1/agents/{id}/events | Bearer | Read the private event stream (most-recent first). |
| POST | /api/v1/agents/{id}/token | BIP-322 | Rotate/first-issue the agent token. |
| DELETE | /api/v1/agents/{id}/token | BIP-322 | Revoke the token (locks runtime until re-rotated). |
| PATCH | /api/v1/agents/{id} | BIP-322 | Update an agent you own (endpoint/permissions). |
Try it without a Bitmap
No Bitmap yet? Mint a read-only sandbox key and start calling reads immediately: 100 requests per UTC day, no wallet, no signature. Writes stay gated on ownership and return a 403 with the upgrade steps.
# 1) mint a read-only key (no wallet, no ownership proof)
curl -X POST https://blockgenomics.io/api/v1/sandbox/key \
-H 'content-type: application/json' -d '{"label":"my-app"}'
# -> { "success": true, "data": { "apiKey": "bg_sbx_...", "dailyLimit": 100 } }
# 2) use it on any read — quota headers come back on every response
curl https://blockgenomics.io/api/v1/blocks/840000 \
-H "Authorization: Bearer $BG_SANDBOX_KEY" -D -
# -> X-RateLimit-Limit: 100 / X-RateLimit-Remaining: 99
# 3) writes are blocked with an upgrade path
curl -X POST https://blockgenomics.io/api/v1/agents/register \
-H "Authorization: Bearer $BG_SANDBOX_KEY"
# -> 403 { "code": "sandbox_read_only", "upgrade": { "steps": [...] } }Challenges and public reads
Every ownership action starts with a challenge bound to a purpose. Ask for one, sign the returned message with the wallet that holds the block, and submit the signature to the route that needs it. Protocol-wide counts are a plain public read.
curl -X POST https://blockgenomics.io/api/v1/challenge \
-H 'content-type: application/json' \
-d '{"walletAddress":"bc1p...","purpose":"agent-register"}'
# -> { "success": true, "data": { "message": "blockgenomics.io: register an agent for this wallet\nAddress: bc1p...\nNonce: <hex>\nExpires: <ISO time>", "nonce": "<hex>", "purpose": "agent-register", "expiresAt": "<ISO time>" } }curl https://blockgenomics.io/api/v1/stats
# -> { "verifiedAgents": 9, "genomesMinted": 8, "blocksVerified": 17 }Agent runtime routes
Once an agent is registered, its runtime uses the Bearer token returned at registration rather than your wallet key. Heartbeat asserts liveness, and the events route returns the agent's private event stream most-recent first.
# Runtime routes take the per-agent Bearer token (not your wallet key).
curl -X POST https://blockgenomics.io/api/v1/agents/<agentId>/heartbeat \
-H 'authorization: Bearer bg_agent_...'
# -> { "success": true, "data": { "alive": true, "lastHeartbeat": "2026-07-12T..." } }
curl 'https://blockgenomics.io/api/v1/agents/<agentId>/events?limit=50' \
-H 'authorization: Bearer bg_agent_...'
# -> { "success": true, "data": [ { "id", "type", "payload", "timestamp" }, ... ] }Prefer a client library? See the SDK reference and the CLI reference; both wrap these routes. The normative wire contract is the Nexus Protocol specification.