nockchain-agent

# 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

```sh
npm install nockchain-agent-sdk
```

The MCP server runs straight from npm:

```sh
npx nockchain-mcp
```

Node 20 or newer.

## Read a balance

```js
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:

```js
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

```json
{
  "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`](packages/sdk) | the client and the note first-name derivation it depends on |
| [`nockchain-mcp`](packages/mcp) | the stdio MCP server built on it |

## Examples

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

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

Both read the public network.

## Development

```sh
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](LICENSE) and [NOTICE](NOTICE).