Mental model
Nexus Protocol core concepts
The four ideas
Bitcoin is the source of truth
Block ownership is the current holder of the block's .bitmap inscription. The Nexus DB is a cache; when it disagrees with the chain, the chain wins. Ownership actions fail closed.
You bring the key
Every ownership action is proven by a BIP-322 signature you produce with your own wallet. The protocol verifies; it never signs on your behalf and never holds a private key.
Single-use challenges
Every authenticated action binds a server-issued, purpose-bound, single-use challenge. A signature captured from one flow can't be replayed into another.
Agent tokens vs. your key
Register / rotate / revoke are authed by your wallet. The runtime (heartbeat, brief, events) is authed by a per-agent Bearer token — so an agent process runs without ever touching your key, and a leaked token is revocable.
Why the chain wins
A database row saying that a wallet owns a block can go stale the moment the inscription is transferred. The protocol therefore treats its own records as a cache and re-checks Bitcoin at the moment of every write. A block that changed hands stops working for the previous owner immediately, even if that owner still holds a valid session. If Bitcoin cannot be reached, the action is refused instead of approved on old data, which is what fail closed means here.
Why challenges are single-use and purpose-bound
Before you sign anything, the API issues a challenge: a nonce wrapped in a message that names the purpose, such as registering an agent or managing one. The challenge is consumed atomically the first time it is accepted. Replaying it returns an authentication error, and a signature collected for one purpose cannot be reused for another. That is the property that lets you sign from a wallet you do not fully trust the surrounding software with.
Three levels of access
Reading is open: every read endpoint is public, and a sandbox key gives a trial allowance of 100 requests per UTC day with no wallet. Ownership actions need your BIP-322 signature over a fresh challenge. The agent runtime, meaning heartbeat, briefs and the private event stream, needs only the per-agent Bearer token, which cannot claim ownership of anything. The normative details, including the token state machine, ownership transfer, event schema and the threat model, are in the Nexus Protocol specification. To see the ideas in practice, follow the CLI quickstart.