开发者

API v1

公开

本浏览器的公开 JSON API,供 NEB 社区钱包和 OTC 网站使用。基础 URL https://62-83-18-7.nip.io/api/v1。

约定

  • 金额是基本单位的十进制字符串(1 NEB = 100,000,000)。请用 BigInt 解析,切勿当作浮点数。
  • 哈希、ID 和锁均为不带 0x 的小写十六进制。ID 按字节顺序输出(不反转)。时间为 Unix 秒。
  • 每个 :addr 都接受 neb1… 地址或 64 位十六进制锁。多签锁和未知锁的 address 为 null;浏览器将其显示为 lock:<hex>。
  • 错误:HTTP 4xx/5xx,返回 { "error": string, "code": string }。错误码:bad_request、bad_address、bad_txid、bad_cursor、not_found、invalid_tx、rejected、rate_limited(429,带 Retry-After)、upstream(502,节点)、unavailable(503,索引)、internal。
  • 所有端点(包括 POST /tx/broadcast)均为 CORS *。已确认的数据缓存几秒(Cache-Control);UTXO 和广播不缓存。
  • 每位访问者每分钟的限额:简单读取 240 次,列表和搜索 120 次,UTXO、富豪榜和节点列表 60 次,广播 20 次。

端点

/api/v1 下共 13 个端点

快速开始

curl https://62-83-18-7.nip.io/api/v1/info
curl https://62-83-18-7.nip.io/api/v1/address/neb1…/utxos
curl -X POST -H 'content-type: application/json' -d '{"hex":"01…"}' https://62-83-18-7.nip.io/api/v1/tx/broadcast

参考

路径相对于基础 URL。示例中用 … 表示省略。

GET/info

节点和索引状态、手续费策略。

{ "network": "mainnet", "chainId": "da2f5a…39ae", "height": 2900, "tipHash": "…", "tipTime": 1795184460,
  "indexedHeight": 2900, "synced": true, "nodeVersion": "1.0.2", "peers": 4,
  "feePolicy": { "minFeePerByte": "1", "minFee": "10000", "dust": "1000" }, "coinbaseMaturity": 100 }

当索引已包含节点的最新区块时 synced 为 true。手续费策略的数值为基本单位(与所有金额一样是字符串)。

GET/blocks?limit=20&before=<height>

区块摘要,最新的在前(limit 最多 100);before 不包含本身。

{ "blocks": [ { "height": 2900, "id": "…", "time": 1795184460, "txCount": 1, "size": 624, "bits": 3154056948,
  "difficulty": 33676240.59, "miner": { "address": "neb1…", "lock": "…", "amount": "1900000000" },
  "reward": "2000000000", "fees": "0" } ] }

reward 为该高度的区块补贴;miner 为第一个 coinbase 输出(多签锁的 address 为 null)。difficulty = 工作量证明上限目标 / 目标。

GET/block/:heightOrId

单个区块:摘要加上 parent、bodyRoot、nonce、shareCount、confirmations 及其交易 ID(coinbase 在前)。

{ …BlockSummary, "parent": "…", "bodyRoot": "…", "nonce": 123456, "shareCount": 31, "confirmations": 12, "txids": ["…"] }
GET/tx/:txid

已确认的交易,或通过本浏览器广播的未确认交易。

{ "txid": "…", "status": "confirmed", "height": 2890, "blockId": "…", "time": 1795183860, "confirmations": 11,
  "coinbase": false, "size": 270, "fee": "10000",
  "inputs": [ { "prevTxid": "…", "prevIndex": 0, "address": "neb1…", "lock": "…", "lockType": 1, "amount": "500000000", "publicKey": "…" } ],
  "outputs": [ { "index": 0, "amount": "100000000", "lockType": 1, "lock": "…", "address": "neb1…", "spentBy": null } ] }

只有当节点的 getrawmempool(实时读取)包含该交易时,status 才为 "mempool"(height、blockId、time 为 null,confirmations 为 0)。已转发但未确认就离开内存池(被丢弃或替换)的交易返回 404 not_found,绝不会是过时的 "mempool";位于索引器尚未存储的区块中的交易,会根据节点数据报告为 "confirmed"。coinbase 只有一个输入,其 prevTxid 全为零、prevIndex 为 4294967295、其余字段为 null,fee 为 "0"。未知的交易 ID 返回 404 not_found,包括未在此广播的内存池交易。

GET/address/:addr

来自索引的锁余额和合计(neb1… 或 64 位十六进制锁)。

{ "address": "neb1…", "lock": "…", "lockType": 1, "balance": "4000000000", "spendable": "2000000000", "immature": "2000000000",
  "received": "…", "sent": "…", "txCount": 12, "utxoCount": 3, "firstSeenHeight": 10, "lastSeenHeight": 2899, "rank": 42 }

spendable 不包括在下一高度仍未成熟的 coinbase 输出。从未出现过的地址返回零、null 高度和 null 排名。

GET/address/:addr/txs?limit=25&cursor=

历史记录,最新的在前(limit 最多 100);将 nextCursor 作为 cursor 传入以获取下一页。

{ "txs": [ { "txid": "…", "height": 2899, "time": 1795184400, "delta": "-100010000", "fee": "10000", "coinbase": false } ], "nextCursor": "2875.1" }

delta 带符号:该交易中此锁的收到 − 发出。

GET/address/:addr/utxos

未花费输出,直接来自节点的 getutxos(权威数据,仅已确认)。从不缓存。

{ "tipHeight": 2900, "utxos": [ { "txid": "…", "index": 0, "amount": "1900000000", "height": 2850, "coinbase": true, "lockType": 1, "mature": false } ] }

mature 按 tipHeight + 1 计算。节点拒绝未花费输出超过 20,000 个的锁(502 upstream)。

POST/tx/broadcast

广播已签名的交易。请求体:{ "hex": "<transaction hex>" }。

{ "txid": "…" }

先解码并检查结构(400 invalid_tx),然后发送给节点;节点拒绝时返回 400 { "error": "<node message>", "code": "rejected" }。节点拒绝花费未确认输出,以及已被内存池中交易花费的输出。每位访问者每分钟限 20 次请求。

GET/mempool

节点内存池中的交易 ID;仅通过本浏览器广播的交易有大小和手续费(否则为 null)。

{ "count": 1, "txs": [ { "txid": "…", "size": 270, "fee": "10000", "seenAt": 1795184470 } ] }
GET/richlist?limit=100&offset=0

按余额排序的锁(limit 最多 1000)。total 为余额为正的锁的数量。

{ "total": 543, "holders": [ { "rank": 1, "address": "neb1…", "lock": "…", "lockType": 1, "balance": "…", "share": 0.0431 } ] }

share 为占流通供应量的比例(0 到 1)。包含项目份额锁和不可花费的创世锁。

GET/stats

供应量和网络数据。

{ "height": 2900, "issued": "8823189999952", "circulating": "8823189999952", "holders": 543, "txCount24h": 600,
  "avgBlockTime1h": 59.8, "difficulty": 33676240.59, "attemptsPerSecond": 590000000000, "projectShareTotal": "290100000000" }

issued = 高度 0..height 的计划奖励 + 创世结转;circulating = 所有未花费输出之和。txCount24h 不含 coinbase。attemptsPerSecond = 最近一小时区块的期望尝试次数 / 其时间跨度。

GET/peers

节点的对等节点。

[ { "addr": "203.0.113.5:3440", "inbound": false, "subver": "neb-node/1.0.2", "height": 2900, "connected": 1025 } ]
API · NEB Explorer