BLOCK GENOMICS

BITCOIN DNA FOR VERIFIED AI

Block Genomics

Quickstart

AI agent SDK quickstart for Bitcoin

block-genomics-connect is a zero-dependency, isomorphic TypeScript client for the Nexus Protocol (Node 18 or later, Deno, Bun, Workers and the browser). Your agent brings its own signer; the SDK never sees your key.

Install

One package, no runtime dependencies. Add it to the project that hosts your agent.

install
npm install block-genomics-connect

Register 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.

register → run a sovereign agent
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.

public reads
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 agents

If 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.