RPC API 参考

节点向钱包提供的 HTTP 接口：四个端点，状态和错误使用 JSON，区块和付款使用紧凑的二进制编码。

公共测试节点的基础 URL 是 https://node.tint.top。该接口从不接触密钥或金额：钱包发送构建完成的付款，并读取完整的区块，由钱包自己解密。

端点

方法与路径	返回内容
`GET /v1/status`	链的当前状态，JSON 格式。
`GET /v1/blocks/{height}`	一个已最终确认的区块，使用线路编码。
`GET /v1/blocks?from=N`	从高度 N 起含有付款的区块，作为一个区块批次。
`POST /v1/transactions`	接收线路编码的付款；以 JSON 返回其标识符。

GET /v1/status

request

curl -s https://node.tint.top/v1/status

response (example values)

{
  "chain_id": 6073471695170043905,
  "height": 128431,
  "tip": "9f3c…e21a",
  "genesis": "04b7…c9d0",
  "queued": 0,
  "pools": [
    { "asset": 1, "native": 20000000000000, "other": 10000000000000, "fee_bps": 30 }
  ]
}

字段	含义
`chain_id`	网络的标识符，绑定在每个签名和区块哈希中。
`height`	最新已最终确认区块的高度。
`tip`	最新已最终确认区块的哈希，十六进制。
`genesis`	第一个区块的哈希，十六进制。两个测试网络可能共用同一个 `chain_id`；用它可以区分它们。
`queued`	等待进入区块的付款。
`pools[].asset`	该池用来与原生代币兑换的代币（1 是 `TUSD`）。
`pools[].native`, `pools[].other`	池中持有的数量，以单位计（1 个代币 = 100,000,000 个单位），截至最新已最终确认的区块。
`pools[].fee_bps`	池的手续费，以万分之几计；30 即 0.3%。

GET /v1/blocks/{height}

以 application/octet-stream 返回一个已最终确认的区块。已最终确认的区块永不改变，因此响应带有 Cache-Control: public, max-age=31536000, immutable。高度不是数字时返回 invalid_height，未知的高度返回 not_found。

GET /v1/blocks?from=N

以一个区块批次（application/octet-stream）返回从高度 N 起含有付款的区块，同时返回该响应所涵盖的最后高度（through）。正在追赶的钱包从 through 之后的高度再次请求。响应会随链增长，因此发送时带有 Cache-Control: no-store。from 必须是整数。

POST /v1/transactions

把构建完成的、线路编码的付款作为请求体发送。付款由钱包构建；其格式定义在 tint-core 的 wire.rs 模块中：定宽字段，每个值只有一种有效编码，没有多余的尾部字节。

request

curl -s -X POST https://node.tint.top/v1/transactions \
  -H 'content-type: application/octet-stream' \
  --data-binary @payment.bin

response

{ "txid": "5be1…07af" }

交易以资产（u32）、过期高度（u64）和类型（0 为付款，1 为兑换）开头，随后是一个数据包：标志、价值余额、锚点、操作数量，以及带证明的各个操作。兑换会额外加入所买入的代币、付入的金额和第二个数据包。

错误

错误为 JSON：{"error":{"code":"...","message":"..."}}。

HTTP	code	含义
400	`malformed`	请求体不是一笔付款。
400	`invalid_height`	高度或 `from` 不是整数。
404	`not_found`	该高度没有已最终确认的区块，或没有这个资源。
409	`double_spend`	这笔付款中的某张票据已被花费。
409	`conflict`	另一笔等待中的付款花费了同样的某张票据。
409	`price_moved`	兑换池已无法给出这次兑换所要求的数量。
413	`too_large`	付款超出了链所允许的大小。
422	`rejected`	付款违反了链的某条规则；message 会说明是哪条。
429	`rate_limited`	该客户端地址已用完其请求额度。请在 `Retry-After` 头指定的时间之后重试。
500	`internal`	节点无法检查或编码。
503	`busy`, `queue_full`	节点正在验证其他付款，或其队列已满。请重试；`Retry-After: 1`。

速率限制

默认情况下，每个客户端地址可持续每秒发出 50 个请求，突发上限为 100，并且所有客户端合计最多同时验证 4 笔付款。运营者可以更改这两项。在反向代理之后，节点按代理写入 X-Forwarded-For 的最后一个地址统计客户端；它不信任更早的条目。

示例：跟踪链

python (server side)

import json, time, urllib.request

BASE = "https://node.tint.top"

while True:
    with urllib.request.urlopen(f"{BASE}/v1/status", timeout=10) as r:
        status = json.load(r)
    print(status["height"], status["queued"])
    time.sleep(5)

节点运营者仍然能从这个接口了解到的，是付款来自哪个网络地址。金额、发送方和接收方都在证明和加密票据之内。