nockchain-agent

一个类型化的 TypeScript 客户端，以及一个可供 agent 读取 Nockchain 的 MCP 服务器。

由 Prism 构建。与 Nockchain、Nock Community Co、Zorp 或 National Compute 均无隶属关系，不为其背书，也不由其运营。

安装

npm install nockchain-agent-sdk

MCP 服务器可以直接从 npm 运行：

npx nockchain-mcp

Node 20 或更高版本。

读取余额

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`);

验证付款

每张发票对应一个地址，然后查询该地址是否已收到付款：

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}`);
}

在 MCP 客户端中使用

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

共七个工具，全部为只读：

为什么存在

目前读取 Nockchain 时有两件事比应有的耗时更长。

余额会以 0 返回。 公共 WalletGetBalance 调用接受一个地址选择器，而在当前 v1 格式的 notes 上，该选择器返回为空。余额实际位于 note 的 first-name 字段中，要获得它，需要对地址背后的 pay-to-pubkey-hash 进行哈希。两条派生路径都很关键，因为 coinbase notes 与普通 notes 的锁定方式不同，而真实余额是两者的并集。getBalance 完成这一计算，并返回该地址实际可花费的余额。

公共节点会悄然过期。 三个端点，于 2026-08-25 同一分钟测得：

响应不会显示来自哪个端点。客户端会拒绝从不满足新鲜度阈值的端点读取数据，并抛出一个类型错误，其中列出它各端点的滞后时延。client.health() 返回完整表格。

限制

只读。 Nockchain 目前没有签名库，因此发送 NOCK 只能使用官方 nockchain-wallet CLI。SDK 会提交 CLI 已经构建好的交易，但不能自行构造或签名交易。

**余额仅是当前未花费 note 集合的快照。 它告诉你一个地址在当前 tip 上可以花费的余额；被花费的 note 会离开集合，所以这个总额并不记录该地址的历史收款总额。此外，钱包发送的链上消息也不包含 memo 或额外 tag，这就是每当一张发票需要单独一个地址的原因。

上游 GetTransactionDetails 对 Logos 升级之后产生的交易会失败。 节点返回的是解码错误而非交易数据。getTransactionDetails 会捕获该情况，并返回 { ok: false, reason: "upstream_decoder_bug", txId, fallback }，其中 fallback 携带 GetTransactionBlock 和 GetBlockDetails 仍能给出的额外信息（如区块高度及其 timestamp）。

公共 API 仍是 alpha 版本，无需认证。 没有需要申请的分发 key，也没有需要出演的速率限制。端点的信息会移动和滞后，且不提前通知。

Packages

示例

示例引用工作区的构建产物，因此请先构建一次。

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

两个示例都读取公共网络。

开发

npm install
npm run build
npm test

测试会离线执行，在测试数据上运行，包括由上游 Rust crates 生成的 golden 向量。整个测试套件不会打开任何网络套接口。

许可

Apache-2.0。参见 LICENSE 与 NOTICE。