文档

基于 nodexch 开发

首次集成所需的一切,按你遇到的顺序排列。每个路由及其字段都在 API 参考中。

快速开始

nodexch 使用 Coinset API:每个方法都是 https://api.nodexch.com 上的 POST /<method>,带 JSON 请求体,节点的应答逐字节原样返回。Coinset 客户端只需更换基础 URL 并加上密钥。

每个示例都从 NODEXCH_URL 读取网关地址,从 NODEXCH_KEY 读取你的密钥。它们在每次发布前都会对真实网关运行,因此照写即可使用。

examples/curl/first-call.sh
#!/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

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。

状态码代码何时出现
400bad_request, validation_failed请求体不是 JSON,或某个字段缺失或格式错误;错误信息会指出该字段。
401unauthorized没有密钥,或密钥网关不认识、已被吊销。
401key_expired密钥所属套餐已过有效期。
403forbidden该密钥不能使用此路由:在运营者路由上使用了可公开密钥,或从未经授权的来源发出。
404not_found没有此路由或方法。
429rate_limited, quota_exceeded超出每分钟速率或月度额度;请等待 retry-after 秒。
501not_enabled此部署不提供该类方法(“index not enabled”)。
502upstream_failed节点或上游没有应答。
503unavailable正在启动或预算已用完;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 计数网关发出的每一帧,所以只订阅部分类型的数据流会看到编号间隔,这并不是丢失的帧。

examples/typescript/events.ts
// 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 表示它是否为交易区块。

    示例帧
    peak
    {
      "network": "mainnet",
      "seq": 1,
      "message": {
        "type": "peak",
        "data": {
          "height": 8412345,
          "header_hash": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
          "tx": true,
          "timestamp": 1790480000
        }
      }
    }
  • transaction

    成批推送的内存池 ID:到达时为 pending,被区块打包时为 confirmed(附带该区块),未被打包就离开时为 removed。

    示例帧(3)
    transaction · pending
    {
      "network": "mainnet",
      "seq": 2,
      "message": {
        "type": "transaction",
        "data": {
          "ids": [
            "0x7777777777777777777777777777777777777777777777777777777777777777"
          ],
          "status": "pending",
          "height": null
        }
      }
    }
    transaction · confirmed
    {
      "network": "mainnet",
      "seq": 3,
      "message": {
        "type": "transaction",
        "data": {
          "ids": [
            "0x7777777777777777777777777777777777777777777777777777777777777777"
          ],
          "status": "confirmed",
          "height": 8412346
        }
      }
    }
    transaction · removed
    {
      "network": "mainnet",
      "seq": 4,
      "message": {
        "type": "transaction",
        "data": {
          "ids": [
            "0x8888888888888888888888888888888888888888888888888888888888888888"
          ],
          "status": "removed",
          "height": null
        }
      }
    }
  • reorg

    最新区块切换到了另一条分支;在旧高度上读取的任何数据都可能已经改变。

    示例帧
    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)
    dashboard · mempool_delta
    {
      "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"
          ]
        }
      }
    }
    dashboard · live
    {
      "network": "mainnet",
      "seq": 7,
      "message": {
        "type": "dashboard",
        "data": {
          "kind": "live",
          "peak_height": 8412345,
          "mempool_size": 236,
          "mempool_cost": 88500547228,
          "mempool_fees": 350012,
          "synced": true
        }
      }
    }
    dashboard · block
    {
      "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
          }
        }
      }
    }
    dashboard · netspace
    {
      "network": "mainnet",
      "seq": 10,
      "message": {
        "type": "dashboard",
        "data": {
          "kind": "netspace",
          "bytes": "16487192343748823040000",
          "difficulty": 2384,
          "height": 8412345
        }
      }
    }
  • offer

    来自 Splash 网络的新报价单,带有 Coinset 的报价单字段以及用于接受它的报价单文件(此处已缩短)。

    示例帧
    offer
    {
      "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}",即可改为从环境变量读取。

examples/mcp/claude-code.sh
#!/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 会询问),或者从智能体页面获取已填好密钥的文件;那里也说明了每个文件的位置。

examples/mcp/claude-desktop.json
{
  "mcpServers": {
    "nodexch": {
      "command": "npx",
      "args": ["-y", "@nodexch/mcp"],
      "env": {
        "NODEXCH_KEY": "nxs_your_secret_key"
      }
    }
  }
}

工具

每个工具做什么,以及一次调用最多花费多少:它所执行路由的权重之和,缓存应答为四分之一,失败不收费。每个结果都会说明花费了多少、还剩多少。

工具积分作用
search_assets1按代码或名称查找代币的资产 ID。
offer_book2某个交易对的未成交报价,最便宜的在前。
best_offer3某个交易对最便宜的报价,附带可直接接受的文本。
get_offer1单个未成交报价:数量、价格、到期时间及其文本。
partial_offers2Partial offers
get_partial_offer1Get a partial offer
decode_offer2读取报价文本:给出什么、要求什么、价格多少。
post_offer5把你的钱包创建的报价发布到报价簿和 Splash 网络。
recent_trades1已成交的报价,最新的在前。
loan_board1本网络上未成交的借贷报价。
prices2XCH 的美元价格和代币的 XCH 价格。

协议消息本身(initialize、tools/list)不收费。套餐不含某个频道时,工具会返回错误并指出包含该频道的套餐。

手动调用

examples/curl/mcp.sh
#!/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"}'