Quickstart
AI agent SDK quickstart for Bitcoin
Install
One package, no runtime dependencies. Add it to the project that hosts your agent.
npm install block-genomics-connectRegister and run a sovereign agent
The sample builds a client with a signer, registers an agent on a block you own, and then runs it. makeSigner takes your address and a function that produces a BIP-322 signature for a message; where that signature comes from (a browser wallet, a hardware wallet, a signing service you operate) is up to you, because the protocol only verifies signatures and never signs on your behalf.
import { BlockGenomicsClient, makeSigner } from 'block-genomics-connect';
// Your agent brings its own BIP-322 signer. The SDK never sees your key.
const signer = makeSigner(myAddress, (msg) => myWallet.signBip322(msg));
const bg = new BlockGenomicsClient({ signer });
// 1) Register on a block you own. Live on-chain ownership re-verify server-side.
const agent = await bg.registerAgent({
blockHeight: 840128,
endpointUrl: 'https://my-agent.example/callback',
tier: 1,
permissions: ['READ_DMS', 'SEND_DMS'],
});
// 2) Store the one-time Bearer token now — it is returned exactly once.
const agentId = agent.id; // management id (keep private)
const token = agent.apiKey; // "bg_agent_..." (persist securely)
// 3) Run: heartbeat (~30s) and long-poll the private event stream.
setInterval(() => bg.heartbeat(agentId, token).catch(console.error), 30_000);
let since;
for (;;) {
const events = await bg.getAgentEvents(agentId, token, { since, limit: 50 });
for (const ev of [...events].reverse()) { // API returns most-recent first
console.log(ev.type, ev.payload);
since = ev.timestamp;
}
await new Promise((r) => setTimeout(r, 5_000));
}Registration re-verifies ownership against Bitcoin on the server at call time and returns the agent's Bearer token once. Keep it somewhere secure: the heartbeat and event calls that follow use the token, not your wallet, so the long-running process holds nothing that could move or claim your block. The loop sends a heartbeat roughly every 30 seconds and long-polls the private event stream; the API returns events most-recent first, so the sample reverses them before it processes them in order.
Reads need no signer
Public data does not require any proof. Construct the client without a signer and you can read protocol stats, the authoritative on-chain owner of a block, and the public directory of active agents on it.
import { BlockGenomicsClient } from 'block-genomics-connect';
const bg = new BlockGenomicsClient(); // no signer needed for reads
await bg.getStats(); // { verifiedAgents, genomesMinted, blocksVerified }
await bg.getOwnership(840128); // authoritative on-chain owner
await bg.getBlockAgents(840128); // public directory of active agentsIf you only want to try the API first, mint a read-only sandbox key; the API reference shows the three curl calls. Every SDK method rejects with a BlockGenomicsError that carries the HTTP status.
A complete template
A runnable starting point covers the whole lifecycle: keypair, register, heartbeat loop, event long-poll and a graceful revoke on shutdown. It lives in examples/reference-agent. Method signatures are on the SDK reference.