nockchain-agent

A typed TypeScript client and an MCP server for reading Nockchain from an agent.

Built by Prism. Not affiliated with, endorsed by, or operated by Nockchain, Nock Community Co, Zorp, or National Compute.

Install

npm install nockchain-agent-sdk

The MCP server runs straight from npm:

npx nockchain-mcp

Node 20 or newer.

Read a balance

import { NockchainClient } from "nockchain-agent-sdk";

const client = new NockchainClient();
const balance = await client.getBalance("2s3K...");

console.log(`${balance.nock} NOCK (${balance.nicks} nicks) across ${balance.notes.length} notes`);

Verify a payment

Issue one address per invoice, then ask whether it has been paid:

import { NockchainClient } from "nockchain-agent-sdk";

const client = new NockchainClient();
const result = await client.verifyPayment({
  address: invoiceAddress,
  minNock: "1.5",
  sinceHeight: 133400,
  confirmations: 3,
});

if (result.paid) {
  console.log(`${result.confirmedNock} NOCK settled at height ${result.tipHeight}`);
}

Use it from an MCP client

{
  "mcpServers": {
    "nockchain": {
      "command": "npx",
      "args": ["-y", "nockchain-mcp"]
    }
  }
}

Seven tools, all read-only:

tool	what it answers
nock_tip	current height, with a freshness reading per endpoint
nock_balance	what an address can spend right now
nock_verify_payment	has this address been paid, with confirmations
nock_block	block contents by height or block ID
nock_transaction	transaction contents, or why the node could not decode them
nock_metrics	cache and refresh state of the selected endpoint, and its peer table
nock_endpoints	the full endpoint health table

Why this exists

Two things about reading Nockchain today cost more time than they should.

Balances come back as zero. The public WalletGetBalance call accepts an address selector, and for notes in the current v1 format that selector returns nothing at all. The balance lives under the note first-name, which you reach by hashing the pay-to-pubkey-hash behind the address. Two derivations matter, because coinbase notes lock differently from ordinary ones, and the real balance is the union of both. getBalance does that work and returns the figure the address can actually spend.

Public nodes go stale quietly. Three endpoints, measured within the same minute on 2026-08-25:

endpoint	height	age of its chain state
api.nockscan.net:443	133598	157 s
23.252.122.18:5556	133598	214 s
rpc.nockbox.org:443	133226	50625 s, close to 14 hours

A response carries no sign of which of these answered it. The client probes every endpoint in its pool and declines to read from one that fails the freshness threshold, raising a typed error that names the ages it measured. client.health() returns the whole table.

Limitations

Read-only. No signing library for Nockchain exists, so sending NOCK needs the official nockchain-wallet CLI. The SDK will submit a transaction the CLI has already produced. It will not build or sign one.

A balance is the live unspent-note set. It answers what an address can spend at the current tip. A spent note leaves the set, so the total is no record of what an address has received over its lifetime. Nothing the wallet sends carries a memo or a tag on the wire either, which is why payment correlation works by issuing one address per invoice.

Upstream GetTransactionDetails fails on transactions produced after the Logos upgrade. The node answers with a decoder error instead of the transaction. getTransactionDetails catches that case and returns { ok: false, reason: "upstream_decoder_bug", txId, fallback }, where fallback carries the inclusion facts that GetTransactionBlock and GetBlockDetails could still establish, such as the block height and its timestamp.

The public API is alpha and unauthenticated. There is no key to obtain and no rate limit to plan against. Endpoints move and lag without notice.

Packages

package	contents
nockchain-agent-sdk	the client and the note first-name derivation it depends on
nockchain-mcp	the stdio MCP server built on it

Examples

The examples import the workspace build, so build it once first.

npm install
npm run build
node examples/balance.mjs 2s3K...
node examples/verify-payment.mjs 2s3K... 1.5

Both read the public network.

Development

npm install
npm run build
npm test

Tests run offline against fixtures, including the golden vectors generated from the upstream Rust crates. Nothing in the test suite opens a socket.

License

Apache-2.0. See LICENSE and NOTICE.