文档
基于 nodexch 开发
首次集成所需的一切,按你遇到的顺序排列。每个路由及其字段都在 API 参考中。
快速开始
nodexch 使用 Coinset API:每个方法都是 https://api.nodexch.com 上的 POST /<method>,带 JSON 请求体,节点的应答逐字节原样返回。Coinset 客户端只需更换基础 URL 并加上密钥。
每个示例都从 NODEXCH_URL 读取网关地址,从 NODEXCH_KEY 读取你的密钥。它们在每次发布前都会对真实网关运行,因此照写即可使用。
#!/bin/sh
# The health check needs no key; every Coinset method is POST /<method> with a JSON body.
set -eu
url="${NODEXCH_URL:-https://api.nodexch.com}"
curl -fsS "$url/health"
echo
curl -fsS "$url/get_blockchain_state" \
-H "Authorization: Bearer $NODEXCH_KEY" \
-d '{}'
echo// The chain's peak through the typed client: every path and body is checked by TypeScript.
import { createNodexch } from "../../clients/typescript/src/index.ts";
const nodexch = createNodexch({
baseUrl: process.env.NODEXCH_URL ?? "https://api.nodexch.com",
key: process.env.NODEXCH_KEY,
});
const { data, error, response } = await nodexch.POST("/get_blockchain_state", { body: {} });
if (error || !data || data.success !== true) {
throw new Error(`get_blockchain_state answered ${response.status}: ${JSON.stringify(error ?? data)}`);
}
// The node's fields, described in the API reference; the spec types them as open objects.
const state = data.blockchain_state as { peak: { height: number }; sync: { synced: boolean } };
console.log(`peak ${state.peak.height}, synced: ${state.sync.synced}`);//! The chain's peak with reqwest: every Coinset method is `POST /<method>` with a JSON body.
//! (`cargo run --example first_call` from gateway/; in your own crate: reqwest with the `json`
//! feature, tokio and serde_json.)
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let url = std::env::var("NODEXCH_URL").unwrap_or_else(|_| "https://api.nodexch.com".into());
let key = std::env::var("NODEXCH_KEY")?;
let state: serde_json::Value = reqwest::Client::new()
.post(format!("{url}/get_blockchain_state"))
.bearer_auth(key)
.json(&serde_json::json!({}))
.send()
.await?
.error_for_status()?
.json()
.await?;
if state["success"] != true {
return Err(format!("the gateway said: {}", state["error"]).into());
}
let peak = &state["blockchain_state"]["peak"]["height"];
let synced = &state["blockchain_state"]["sync"]["synced"];
println!("peak {peak}, synced: {synced}");
Ok(())
}TypeScript 示例使用由 API 的 OpenAPI 文档生成的类型化客户端:每个路径和请求体都由编译器检查。/openapi.json 是同一份文档,可供任何其他生成器使用。
超过 253 的整数(网络算力、大额数量)按节点写出的原样到达,而 JSON.parse 会悄悄对它们取整:在需要精确值的地方,请用支持大整数的解析器解析此类应答;事件帧把它们写成字符串。
可以调用什么
nodexch 响应 Coinset 的方法,并在 /x/… 下提供自己的通道。以下是各个类别及其部分路由;全部路由及每个字段都在 API 参考中。
- 区块
- 区块、区块记录、其中的花费,以及它们新增和移除的币。
/get_block_record_by_height/get_blocks/get_block_spends/get_additions_and_removals - 币
- 按名称、puzzle hash、父币或 hint 查询币记录;puzzle 与 solution。
/get_coin_record_by_name/get_coin_records_by_puzzle_hash/get_coin_records_by_hint/get_puzzle_and_solution - 交易
- 交易及 Coinset 对其行为的摘要,以及重组。
/get_transaction/get_transactions_by_p2/get_pending_transactions_by_p2/get_reorgs - 地址、代币和 NFT
- 一个地址持有什么:XCH、CAT 代币、NFT 和 singleton。
/get_xch_balance_by_p2/get_cat_balances_by_p2/get_nft_ids_by_p2/get_singleton_info - 内存池和手续费
- 内存池中等待的内容、现在一笔花费的费用,以及提交花费。
/get_all_mempool_items/get_mempool_item_by_tx_id/get_fee_estimate/push_tx - 报价
- 按 ID、代币、NFT 或地址查询报价及其状态,以及成交历史。
/get_offer/get_offers_by_cat_asset_id/push_offer/x/offers/v1/trades - nodexch 自己的通道
- 网络中的节点、分档的内存池和手续费、代币名称和图标、XCH 价格。
/x/node/v1/network/x/node/v1/mempool/x/node/v1/fees/x/assets/v1/assets/x/price/v1/xch - 实时事件
- 同一条链的数据流:WebSocket 或 server-sent events。
/ws/events
密钥
以 Authorization: Bearer <key> 发送密钥。没有密钥时,只有探针(/up、/ready、/health)、OpenAPI 文档(/openapi.json)和本网站会应答。
- 私密密钥(
nxs_…)用于服务器。绝不要把它放进网页、应用包或 URL。 - 可公开密钥(
nxp_…)用于浏览器。它们只在签发时指定的来源下有效,对单个访客地址的配额不超过无密钥访客,并且永远不能访问运营者路由。 - 浏览器无法在 WebSocket 或
EventSource上设置请求头,因此/ws和/events也接受以?key=形式传入的可公开密钥。URL 中的私密密钥会被拒绝。 - 泄露的密钥会被轮换:新密钥立即生效,旧密钥立即停用,因此轮换时请准备好部署新密钥。
限制
密钥的套餐规定每分钟速率、每月额度和可同时打开的数据流数量。每个带密钥的应答都会告诉你当前状况:
| 响应头 | 含义 |
|---|---|
x-ratelimit-limit, x-ratelimit-remaining | 本分钟的请求数 |
x-quota-limit, x-quota-remaining | 本月的请求数 |
retry-after | 遇到 429 或 503 时:距离下次尝试可能成功还有多少秒 |
x-nodexch-tier | 应答来自哪里:某一缓存层(immutable、peak、state、mempool)、none、index、passthrough 或 stream |
ETag | 把它作为 If-None-Match 发回,在内容未变时得到 304 |
区块链未发生变化的应答来自缓存,所以轮询很便宜;下面的实时事件更便宜。
套餐与额度
套餐如何付款、包含什么,以及边界情况会发生什么。账户页面会为你的账户显示全部内容。
- 每个套餐可按月或按年订阅;年价是十二个月的价格减去定价页面显示的优惠。Chia 没有代扣,所以每个周期都是一张你在账户页面用 XCH 支付的账单:用 Sage 一键支付,或用 Chia 保险库按地址、金额和备注支付。续费账单在周期结束前 7 天生成;如果你提供了邮箱,还会收到邮件提醒。
- 额度是每个账户一份,所有密钥共享。它从你订阅的那一天算到下个月的同一天,年套餐也一样(按月发放)。未用完的请求不会结转。账户页面显示剩余额度和重新开始的日期(UTC)。
- 额度用完时,请求返回 429 quota_exceeded,带有 retry-after 头,以及响应体中的 x-quota-reset 和 resets_at:即额度重新开始的时刻。每个响应都带有 x-quota-limit、x-quota-remaining 和 x-quota-reset。没有加购:升级会从今天起开始新的周期和完整额度。
- 升级现在一次付清,并从当天起开始新的周期;旧周期的剩余部分不折算。降级和取消在已付周期结束时生效。不退款:你已付款的周期会用完。
- 如果续费未付款,周期结束后有 7 天宽限期。之后账户及其密钥回到免费套餐:不会被封锁,只是按免费额度。之后的付款会从当天起开始新的周期。
- 邮箱地址是可选的,但付费套餐需要已确认的地址:续费提醒和安全通知会发到这里。它不能用来登录。如果丢失了所有通行密钥,发到它的链接可以注册一个新的通行密钥,24 小时后才能登录;你仍持有的通行密钥可以在此之前取消。没有邮箱地址,丢失的通行密钥无法找回。
错误
nodexch 自身的错误是带有 HTTP 状态码和稳定错误代码的 JSON:
{"success": false, "error": "an API key is required: send Authorization: Bearer <key>", "code": "unauthorized"}节点本身的拒绝则保留 Coinset 的格式:HTTP 200,带 success: false 和 error(例如请求一个不存在的区块)。请在每个应答中检查 success。
| 状态码 | 代码 | 何时出现 |
|---|---|---|
| 400 | bad_request, validation_failed | 请求体不是 JSON,或某个字段缺失或格式错误;错误信息会指出该字段。 |
| 401 | unauthorized | 没有密钥,或密钥网关不认识、已被吊销。 |
| 401 | key_expired | 密钥所属套餐已过有效期。 |
| 403 | forbidden | 该密钥不能使用此路由:在运营者路由上使用了可公开密钥,或从未经授权的来源发出。 |
| 404 | not_found | 没有此路由或方法。 |
| 429 | rate_limited, quota_exceeded | 超出每分钟速率或月度额度;请等待 retry-after 秒。 |
| 501 | not_enabled | 此部署不提供该类方法(“index not enabled”)。 |
| 502 | upstream_failed | 节点或上游没有应答。 |
| 503 | unavailable | 正在启动或预算已用完;retry-after 会告诉你何时重试。 |
分页
Coinset 方法的分页方式与 Coinset 相同:用 start 和 end 指定高度范围(不包含 end,一次最多 1,000 个区块)。
nodexch 自有的 /x/… 列表接受 limit 和 cursor。每页都带有 next_cursor;把它作为 cursor 传入以获取下一页,直到它为 null。
curl -s "https://api.nodexch.com/x/offers/v1/trades?asset_id=xch&limit=100" \
-H "Authorization: Bearer $NODEXCH_KEY"
curl -s "https://api.nodexch.com/x/offers/v1/trades?asset_id=xch&limit=100&cursor=<next_cursor>" \
-H "Authorization: Bearer $NODEXCH_KEY"实时事件
一个 WebSocket:/ws?events=peak,transaction,reorg,dashboard,或者在 /events 上以服务器推送事件接收相同的帧。不指定 events 时,数据流会收到 Coinset 的四种类型;offer 是 nodexch 独有的,仅在请求时推送。
每一帧都是 {"network", "seq", "message": {"type", "data"}}。seq 计数网关发出的每一帧,所以只订阅部分类型的数据流会看到编号间隔,这并不是丢失的帧。
// The live events: open /ws, wait for the next peak, close. Frames are
// {"network","seq","message":{"type","data"}}, as Coinset sends them.
import { eventsUrl } from "../../clients/typescript/src/index.ts";
const base = process.env.NODEXCH_URL ?? "https://api.nodexch.com";
// Browsers put a publishable key in the URL; a server may send its secret key as a header instead.
const socket = new WebSocket(eventsUrl(base, ["peak"], process.env.NODEXCH_PUBLISHABLE_KEY));
let done = false;
const timeout = setTimeout(() => {
console.error("no peak within 60 s");
process.exit(1);
}, 60_000);
socket.addEventListener("message", (event) => {
const frame = JSON.parse(String(event.data));
if (frame.message?.type === "peak") {
console.log(`peak ${frame.message.data.height} on ${frame.network} (seq ${frame.seq})`);
done = true;
clearTimeout(timeout);
socket.close();
}
});
socket.addEventListener("error", () => {
if (done) return;
console.error("the stream failed");
process.exit(1);
});peak一个新区块;
tx表示它是否为交易区块。示例帧
{ "network": "mainnet", "seq": 1, "message": { "type": "peak", "data": { "height": 8412345, "header_hash": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "tx": true, "timestamp": 1790480000 } } }transaction成批推送的内存池 ID:到达时为
pending,被区块打包时为confirmed(附带该区块),未被打包就离开时为removed。示例帧(3)
{ "network": "mainnet", "seq": 2, "message": { "type": "transaction", "data": { "ids": [ "0x7777777777777777777777777777777777777777777777777777777777777777" ], "status": "pending", "height": null } } }{ "network": "mainnet", "seq": 3, "message": { "type": "transaction", "data": { "ids": [ "0x7777777777777777777777777777777777777777777777777777777777777777" ], "status": "confirmed", "height": 8412346 } } }{ "network": "mainnet", "seq": 4, "message": { "type": "transaction", "data": { "ids": [ "0x8888888888888888888888888888888888888888888888888888888888888888" ], "status": "removed", "height": null } } }reorg最新区块切换到了另一条分支;在旧高度上读取的任何数据都可能已经改变。
示例帧
{ "network": "mainnet", "seq": 5, "message": { "type": "reorg", "data": { "old_peak_height": 8412346, "old_peak_hash": "0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "new_peak_height": 8412346, "new_peak_hash": "0xcccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc", "reorg_depth": 1, "detected_at_ms": 1790480031250 } } }dashboard区块浏览器首页所需的数据流,每次一种
kind。示例帧(4)
{ "network": "mainnet", "seq": 6, "message": { "type": "dashboard", "data": { "kind": "mempool_delta", "added": [ { "id": "0x7777777777777777777777777777777777777777777777777777777777777777", "first_seen_ms": 1790480012000, "fee_mojos": 50000000, "cost": 12000000, "spends": 2, "additions": [ { "parent_coin_info": "0xdddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd", "puzzle_hash": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee", "amount": 1000 } ], "removals": [ { "parent_coin_info": "0xffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff", "puzzle_hash": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee", "amount": 1000 } ], "addition_count": 3, "removal_count": 2, "kind": "cat", "asset_ids": [ "0x9999999999999999999999999999999999999999999999999999999999999999" ], "assets": { "xch": "50000000", "cats": [ { "asset_id": "0x9999999999999999999999999999999999999999999999999999999999999999", "amount": "1000" } ], "nfts": 0, "dids": 0, "singletons": 0 } } ], "removed": [ "0x8888888888888888888888888888888888888888888888888888888888888888" ] } } }{ "network": "mainnet", "seq": 7, "message": { "type": "dashboard", "data": { "kind": "live", "peak_height": 8412345, "mempool_size": 236, "mempool_cost": 88500547228, "mempool_fees": 350012, "synced": true } } }{ "network": "mainnet", "seq": 8, "message": { "type": "dashboard", "data": { "kind": "block", "height": 8412345, "header_hash": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "timestamp": 1790480000, "fees": 350012, "additions": 42, "removals": 17, "record": { "height": 8412345, "header_hash": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "timestamp": 1790480000, "fees": 350012, "weight": 36893488147419103000 }, "spends": 17, "assets": { "xch": "12209542198803", "cats": [ { "asset_id": "0xcccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc", "amount": "3938" } ], "nfts": 1, "dids": 0, "singletons": 2 } } } }{ "network": "mainnet", "seq": 10, "message": { "type": "dashboard", "data": { "kind": "netspace", "bytes": "16487192343748823040000", "difficulty": 2384, "height": 8412345 } } }offer来自 Splash 网络的新报价单,带有 Coinset 的报价单字段以及用于接受它的报价单文件(此处已缩短)。
示例帧
{ "network": "mainnet", "seq": 10, "message": { "type": "offer", "data": { "offer_id": "8b239d3813a72e10cec3efa6b05841017cef2828add97026cd8352a53378e4da", "status": "open", "first_seen_ms": 1790480012000, "last_updated_ms": 1790480012000, "maker_p2s": [ "d8b1e0d9a0e46b3403dff2f6c27fc46bc13e6f5ee5ff09dc28d28d28d51be422" ], "offered_cat_asset_ids": [ "ec25b77bc54df637392d6a0f542de65f45020405d0f36ced723bff2870c378b1" ], "requested_cat_asset_ids": [], "offered_nft_ids": [], "requested_nft_ids": [], "offered_xch_mojos": 0, "requested_xch_mojos": 500003000000, "offered_cat_mojos": { "ec25b77bc54df637392d6a0f542de65f45020405d0f36ced723bff2870c378b1": 1000 }, "fee_mojos": 0, "pending_p2s": [], "offer": "offer1qqr83wcuu2rykcmqvpsxygqqemhmlaekcenaz02ma6hs5w600dhjlv…", "source": "splash", "network": "mainnet" } } }
智能体(MCP)
AI 智能体通过 nodexch 的 MCP 服务器 https://api.nodexch.com/mcp 读取数据:某个交易对的报价簿(最便宜的在前)、带文本的单个报价、报价解码、近期成交、借贷看板和价格。它只读,从不接触钱包,每次工具调用都按其使用的路由在你的私密密钥上扣除积分。
Claude Code
在智能体页面为智能体创建一个密钥,它会自动填入这条命令,然后添加一次服务器。Claude Code 会把密钥保存在其设置中;在项目的 .mcp.json 中在服务器的 env 里写 "NODEXCH_KEY": "${NODEXCH_KEY}",即可改为从环境变量读取。
#!/bin/sh
# Connects Claude Code to nodexch in one install (@nodexch/mcp, TASK-176.04): the offer book,
# offers, trades, the loan board and prices, publishing an offer, metered in credits on your secret
# API key (nodexch.com, Account); and the Xchonnect wallet tools, run on your computer, which ask
# your wallet to take, make or cancel offers (nodexch never sees those requests).
#
# --scope user: every project of yours; the key is stored in ~/.claude.json. In a project's
# .mcp.json write "NODEXCH_KEY": "${NODEXCH_KEY}" in its env instead: Claude Code reads it from
# the environment, and the key stays out of the file.
# The key is passed to `claude mcp add` as an argument (-e), visible in the process list while it runs.
set -eu
: "${NODEXCH_KEY:?set NODEXCH_KEY=nxs_...}"
url="${NODEXCH_URL:-https://api.nodexch.com}"
command -v npx >/dev/null 2>&1 || { echo "nodexch: Node.js 22.12 or newer is needed (npx runs @nodexch/mcp)" >&2; exit 1; }
claude mcp add --scope user nodexch -e NODEXCH_KEY="$NODEXCH_KEY" -e NODEXCH_URL="$url" \
-- npx -y @nodexch/mcp
claude mcp list同一次安装也带来 Xchonnect 钱包工具(@nodexch/mcp 在你的电脑上运行它们):智能体与你的钱包配对, 请钱包接受或创建报价,钱包在你为智能体设定的规则内做决定。交易从不经过 nodexch。
网页、桌面和手机上的 Claude
把 https://api.nodexch.com/mcp 添加为自定义连接器;Claude 会用你的通行密钥通过 nodexch 登录并获得自己的密钥,无需复制任何内容。Claude Free 只允许一个自定义连接器,钱包插件就没有位置了:智能体页面的 Claude 标签页说明了这意味着什么,以及如何仍然进行交易。
在浏览器中,无需插件
智能体页面会自己与你的钱包配对,供在你的浏览器中工作的智能体使用,例如 Claude in Chrome。会话加密保存在该浏览器中;nodexch 为你的账户签署每次配对,无法读取会话;其中继只传递密封的消息。智能体及其提供方能看到页面。它可以在页面上读取你的钱包规则,接受和创建报价,挂出阶梯并取消;它比本地插件慢,且尚未用 Claude in Chrome 测试。
Claude Desktop、Cursor 和 VS Code
同样的安装,写在配置文件中。用你的密钥替换 nxs_your_secret_key(VS Code 会询问),或者从智能体页面获取已填好密钥的文件;那里也说明了每个文件的位置。
{
"mcpServers": {
"nodexch": {
"command": "npx",
"args": ["-y", "@nodexch/mcp"],
"env": {
"NODEXCH_KEY": "nxs_your_secret_key"
}
}
}
}{
"mcpServers": {
"nodexch": {
"command": "npx",
"args": ["-y", "@nodexch/mcp"],
"env": {
"NODEXCH_KEY": "nxs_your_secret_key"
}
}
}
}{
"inputs": [
{
"type": "promptString",
"id": "nodexch-key",
"description": "nodexch secret API key (nxs_…)",
"password": true
}
],
"servers": {
"nodexch": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@nodexch/mcp"],
"env": {
"NODEXCH_KEY": "${input:nodexch-key}"
}
}
}
}工具
每个工具做什么,以及一次调用最多花费多少:它所执行路由的权重之和,缓存应答为四分之一,失败不收费。每个结果都会说明花费了多少、还剩多少。
| 工具 | 积分 | 作用 |
|---|---|---|
search_assets | 1 | 按代码或名称查找代币的资产 ID。 |
offer_book | 2 | 某个交易对的未成交报价,最便宜的在前。 |
best_offer | 3 | 某个交易对最便宜的报价,附带可直接接受的文本。 |
get_offer | 1 | 单个未成交报价:数量、价格、到期时间及其文本。 |
partial_offers | 2 | Partial offers |
get_partial_offer | 1 | Get a partial offer |
decode_offer | 2 | 读取报价文本:给出什么、要求什么、价格多少。 |
post_offer | 5 | 把你的钱包创建的报价发布到报价簿和 Splash 网络。 |
recent_trades | 1 | 已成交的报价,最新的在前。 |
loan_board | 1 | 本网络上未成交的借贷报价。 |
prices | 2 | XCH 的美元价格和代币的 XCH 价格。 |
协议消息本身(initialize、tools/list)不收费。套餐不含某个频道时,工具会返回错误并指出包含该频道的套餐。
手动调用
#!/bin/sh
# The MCP server for agents is POST /mcp with a secret key: one JSON-RPC message per request.
# An MCP client (Claude Code) does this for you; here is what it sends.
set -eu
: "${NODEXCH_KEY:?set NODEXCH_KEY=nxs_...}"
url="${NODEXCH_URL:-https://api.nodexch.com}"
mcp() {
curl -fsS "$url/mcp" \
-H "Authorization: Bearer $NODEXCH_KEY" \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-d "$1"
echo
}
mcp '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'
mcp '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'