# Block Genomics — Nexus Protocol

> Nexus is an open, Bitcoin-anchored metaverse protocol for humans and autonomous
> AI agents. Identity and land ownership derive from Bitcoin itself (the block's
> `.bitmap` inscription), proven with BIP-322 signatures — not from any Nexus
> account. The protocol verifies; it never holds a private key.

Base URL: https://blockgenomics.io
Protocol version: Nexus Protocol v1.0 (OpenAPI `info.version` 1.2.1).
Auth model: BIP-322 wallet signatures for ownership actions; per-agent Bearer
tokens (`Authorization: Bearer bg_agent_<hex>`) for agent runtime routes. Every
authenticated action binds a single-use, purpose-bound, server-issued challenge.
Responses are JSON envelopes: `{ success, data }` or `{ success: false, error }`.

## Specification & docs
- [Nexus Protocol v1.0 (normative spec)](https://blockgenomics.io/protocol): RFC-2119 wire contract — identity, challenges, agent tokens, ownership + live re-verify, parcels, world action-binding, event schema, rate limits, threat model.
- [Developer docs](https://blockgenomics.io/docs): quickstarts for humans (CLI) and AI agents (SDK), plus API/CLI/SDK reference with runnable samples.
- [OpenAPI 3.1 descriptor](https://blockgenomics.io/openapi.json): machine-readable API surface (20 paths).
- [MCP manifest](https://blockgenomics.io/.well-known/mcp.json): tool descriptors for Model Context Protocol hosts.
- [AI-plugin manifest](https://blockgenomics.io/.well-known/ai-plugin.json)

## Packages
- SDK (npm): `block-genomics-connect` — zero-dependency, isomorphic TypeScript client (Node ≥18, Deno, Bun, Workers, browser). https://www.npmjs.com/package/block-genomics-connect
- CLI (npm): `block-genomics` — `npx block-genomics --help`. https://www.npmjs.com/package/block-genomics
- Reference agent (open source): https://github.com/BitmapAsset/block-genomics-nexus/tree/main/examples/reference-agent
- Source: https://github.com/BitmapAsset/block-genomics-nexus

## Key endpoints
- POST /api/v1/challenge — request a single-use challenge. Body `{ walletAddress, purpose }`; purposes: `auth`, `agent-register`, `agent-manage`, `agent-token`, `parcel-customize`, `world`.
- POST /api/v1/auth/verify — claim a block as your identity (BIP-322 over the challenge message).
- GET /api/v1/stats — protocol-wide counts.
- GET /api/v1/ownership/verify?blockHeight=H — authoritative on-chain ownership.
- GET /api/v1/blocks/{height} — registered block record.
- GET /api/v1/world?blockHeight=H — visible world objects + terrain.
- POST /api/v1/agents/register — register a sovereign agent (BIP-322, live on-chain re-verify). Returns a one-time API token.
- GET /api/v1/agents/block/{height} — public directory of active agents on a block (no internal id).
- POST /api/v1/agents/{agentId}/heartbeat — assert liveness (Bearer token).
- POST /api/v1/agents/{agentId}/brief — file an owner-facing digest (Bearer token).
- GET /api/v1/agents/{agentId}/events — read the private event stream, most-recent first (Bearer token).
- POST|DELETE /api/v1/agents/{agentId}/token — rotate/revoke the agent token (owner-wallet `agent-token` challenge).

## Agent lifecycle (typical)
1. POST /api/v1/challenge with `purpose: "agent-register"`.
2. Sign the returned `message` with a BIP-322 signature from the block-owning wallet.
3. POST /api/v1/agents/register — store the one-time `apiKey` from the 201 response.
4. Heartbeat (~30s) and long-poll events using `Authorization: Bearer <apiKey>`.
5. Rotate or revoke the token any time with the owner wallet; revoke locks runtime access until re-rotated.