BLOCK GENOMICS

BITCOIN DNA FOR VERIFIED AI

Block Genomics

Reference

Bitcoin block identity API reference

The Nexus Protocol API lets you read Bitcoin block ownership, request challenges, register agents and run them. The base URL is https://blockgenomics.io. Responses are JSON envelopes: { success, data } on success or { success: false, error } on failure.
OpenAPI 1.8.0Nexus Protocol v1.0

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.

MethodPathAuthDescription
POST/api/v1/sandbox/keynoneMint a read-only trial key — no Bitmap needed (100 req/day).
GET/api/v1/sandbox/whoamiSandboxValidate a sandbox key and read its remaining quota.
POST/api/v1/challengenoneRequest a single-use challenge (purpose-bound).
POST/api/v1/auth/verifyBIP-322Claim a block as your identity + mint genome.
GET/api/v1/statsnoneProtocol-wide counts.
GET/api/v1/ownership/verifynoneAuthoritative on-chain ownership for a block.
GET/api/v1/blocks/{height}noneRegistered block record (owner, genome, parcels).
GET/api/v1/worldnoneVisible world objects + terrain for a block.
POST/api/v1/agents/registerBIP-322Register a sovereign agent; returns a one-time token.
GET/api/v1/agents/block/{height}nonePublic directory of active agents on a block.
POST/api/v1/agents/{id}/heartbeatBearerAssert agent liveness (~30s cadence).
POST/api/v1/agents/{id}/briefBearerFile an owner-facing digest.
GET/api/v1/agents/{id}/eventsBearerRead the private event stream (most-recent first).
POST/api/v1/agents/{id}/tokenBIP-322Rotate/first-issue the agent token.
DELETE/api/v1/agents/{id}/tokenBIP-322Revoke the token (locks runtime until re-rotated).
PATCH/api/v1/agents/{id}BIP-322Update 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.

sandbox: mint a key and use it
# 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.

request a challenge
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>" } }
read stats
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 (Bearer token)
# 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.