简体中文
English
Українська
한국어

简体中文

English
Українська
한국어

REST API ​

链通过两个 HTTP 服务对外提供访问：

服务默认地址用途
Gateway（Node.js）http://localhost:3000dApp 和 Web 应用调用的服务。代理节点，并提供 WebSocket、AI 工具和缓存
节点 RPC（Rust）http://localhost:9933唯一的事实来源。部分运维端点只在这里提供

大多数路径在两者上相同。下表会标出只存在于其中一方的端点。示例使用 $GATEWAY 和 $NODE_RPC——参见从这里开始。

约定 ​

金额 ​

  • 链上金额是以 uNRO 为单位的整数（1 NRO = 1 000 000 uNRO）。
  • 响应会在每个金额旁附带格式化好的 *_human 字符串（balance_human、value_human、stake_human……）。请直接展示这些字段，不要在客户端自行换算。
  • 在请求体中，除非端点另有说明，金额一律以 uNRO 为单位、作为 JSON 数字发送。

签名操作 ​

每个会改变状态的端点都需要签名。分为两类：

类型签名消息nonce
交易（POST /api/v1/transactions）`nc-tx-v2from
操作（其他所有端点）`nc-tx-v2actor

目标（target）是一个用于标识操作的保留系统地址；表格中在 签名目标 一列给出。每个请求都携带 signature（hex）、public_key（hex 格式的 ML-DSA-65）和 nonce。参见钱包 → 签名操作。

在 CHAIN_ENV=mainnet（默认值）下，缺失或无效的签名会被以 401 拒绝。在 CHAIN_ENV=testnet 下节点只记录一条警告——仅用于本地开发。

大多数操作在共识中应用：响应返回 "status": "pending" 和一个 tx_hash；该交易进入区块后，效果才可见。

载荷签名 ​

上面的签名涵盖了执行者、目标和数值，但不涵盖操作的其余部分——收款方、会话密钥的权限范围、一张投票。在 mainnet 上，每个操作还会携带一个覆盖其作用对象全部内容的载荷签名，使区块提议者和中继节点都无法篡改它：

  • 操作（质押、信任列表、投票、NFT 转移、会话密钥、保险库、注册……）：端点不会直接将操作加入队列，而是返回 { "needs_payload_signature": true, "op", "sign_payload", "prepared" }。用同一把密钥对 sign_payload（nc-op-v1|…，由节点构造）签名，再将 { …prepared, "payload_signature": "<hex>" } 发送到 POST /api/v1/markers/submit，由它将操作加入队列。
  • 资产与交易所操作：将请求（使用 human 金额）连同 route、from 和 nonce 发送到 POST /api/v1/dex/prepare；它返回 canonical 消息、原始 payload 和人类可读的 summary。对 canonical 签名，然后将同一请求附带 payload_signature 发送到对应端点。

个人中心和交易所会替你完成这两步，并在你签名之前展示该操作。

错误 ​

错误以 JSON 返回：{"error": "<message>"}，有时附带 hint 或其他字段。使用的 HTTP 状态码：

状态码含义
200成功——但部分较老的端点也会以 200 返回 {"error": …}；务必检查 error
400请求错误、校验失败、被 Sentinel 拒绝
401签名缺失或无效，密钥未绑定到该地址
403在当前模式下被禁止（mainnet 上的水龙头、mainnet 上不经共识的写调用），部署被 VMGuardian 拒绝
404未找到
409名称已被占用
429触发速率限制
502 / 503Gateway 无法连接节点

分页 ​

列表端点接受 limit 和 offset（部分还接受 page）。每个端点都对 limit 设有上限（通常为 100 或 200）。

速率限制与 CORS ​

位置默认值变量
节点 RPC，按 IP100 次请求/秒NEUROCHAIN_RPC_RATE_LIMIT
Gateway，按 IP200 次请求/秒GLOBAL_RL_MAX_RPS
Gateway AI 端点（/contracts/audit、/contracts/generate……），按 IP10 次请求/分钟AI_RL_MAX_RPM

允许的来源：两个服务均通过 CORS_ALLOWED_ORIGINS 配置（默认 *）。

网络与节点 ​

方法路径说明
GET/healthstatus、height、round、mempool、peers、tps、total_txs、validator_count、bft_quorum、bft_ready
GET/status, /api/v1/status仅节点。高度、验证者、分片、网络名称
GET/api/v1/network/status仅 Gateway。供浏览器使用的网络概览
GET/metricsPrometheus 文本格式——参见运行节点
GET/api/v1/shards各分片的高度和根
GET/api/v1/state/rootglobal_root、shard_roots、height、root_height、n_shards
GET/api/v1/state/snapshot仅节点。用于引导新节点的完整签名状态快照
GET/api/v1/checkpoints已签名的检查点。offset、limit
GET/peers仅节点。已连接的对等节点
GET/api/v1/gas/estimatebase_fee、各操作的 gas、total_burned、nft_transfer_fee——参见 Gas 与手续费
GET/api/v1/wasm/version仅 Gateway。浏览器 WASM 模块的版本清单

区块 ​

方法路径说明
GET/api/v1/blockslimit（≤ 100，默认 20）、offset、page。最新的在前
GET/api/v1/blocks/latest仅 Gateway。{ "block": … }
GET/api/v1/blocks/:height单个区块：height、hash、parent_hash、proposer、tx_root、state_root、tx_count、gas_used、base_fee、fees_burned、shard、round、timestamp
GET/api/v1/blocks/:height/transactions区块中的交易

交易 ​

方法路径签名目标说明
POST/api/v1/transactions交易本身请求体见下文
GET/api/v1/transactions—address、hash、type（staking 列出质押操作）、limit（≤ 200）、offset、page
GET/api/v1/transactions/:hash—单笔交易，含 status、gas、fee、fee_human、value_human
GET/api/v1/tx/:hash/proof—Merkle 包含证明：leaf_index、proof、tx_root、block_height
POST/api/v1/transactions/:hash/confirmneuro:system.trust确认一笔被暂扣的转账（仅限所有者的主密钥）——参见 Sentinel
POST/api/v1/transactions/:hash/cancelneuro:system.trust取消一笔被暂扣的转账
GET/api/v1/held/:address—某地址被暂扣的转账
GET/api/v1/cross-shard/queue—跨分片中继。status、limit、offset

POST /api/v1/transactions 请求体

字段类型必填含义
fromstring是发送方地址
tostring是接收方、合约，或 neuro:system.deploy
valuenumber是uNRO
noncenumber是下一个账户 nonce
signaturestring是对 `nc-tx-v2
public_keystring是ML-DSA-65 公钥，hex
gas_pricenumber否每单位 gas 的 uNRO；必须 ≥ 基础费用
datastring否以 JSON 字符串表示的合约调用或部署（也接受 hex）——参见 ABI、部署

响应：tx_hash、status: "pending"、estimated_block；当 Sentinel 标记该交易时还会附带 sentinel_score 和 sentinel_warning，当策略层暂扣它时附带 held 详情。

账户 ​

方法路径说明
GET/api/v1/accounts/:addressbalance、balance_human、nonce……
GET/api/v1/accounts/:address/transactions历史记录。limit、offset
GET/api/v1/accounts/:address/token-transfers涉及该地址的代币（NRC-20）转账
GET/api/v1/accounts/:address/totals仅节点。发送和接收的总额
POST/api/v1/faucet仅限测试网络（CHAIN_ENV=testnet）。请求体：address、public_key、amount（uNRO，可选）
POST/api/v1/wallet/derive-address请求体：words。从助记词推导 .human 地址——会把助记词发送到服务器。mainnet 上关闭；测试网络上仅在 NEUROCHAIN_ALLOW_SERVER_DERIVE=true 时可用

名称与 NFT ​

方法路径签名目标请求体 / 说明
POST/api/v1/addresses/humanneuro:system.name仅节点。name、owner + 签名字段。注册自定义 .human 名称
GET/api/v1/addresses/human/price—仅节点。?name= → 按长度计算的价格
POST/api/v1/nodes/registerneuro:system.nodename、owner、可选的 node_address（用于注册 .app / .vault）+ 签名字段
GET/api/v1/nodes—已注册的节点
GET/api/v1/nodes/:address—单个节点记录
PUT/POST/api/v1/nodes/:address/profileneuro:system.nodedescription、website、commission_bps、p2p_endpoint、rpc_endpoint
POST/api/v1/nodes/:address/unjailneuro:system.node监禁期结束后重新进入验证者集合（由所有者签名）
POST/api/v1/nft/transferNFT 地址nft_address、from（当前所有者）、to + 签名字段。手续费 100 uNRO
GET/api/v1/nft/:address—NFT 记录和转移历史
GET/api/v1/nft/owner/:address—某地址拥有的 NFT
POST/api/v1/agents/registerneuro:system.agentname、owner + 签名字段。注册 .agent
GET/api/v1/agents/:address—Agent 记录

质押 ​

方法路径签名目标请求体 / 说明
POST/api/v1/staking/stakeneuro:system.stakeaddress、amount + 签名字段
POST/api/v1/staking/unstakeneuro:system.stakeaddress + 签名字段
POST/api/v1/staking/delegate验证者地址delegator、validator、amount + 签名字段
POST/api/v1/staking/undelegate验证者地址delegator、validator + 签名字段
GET/api/v1/staking/info/:address—某地址的质押、锁定和奖励
GET/api/v1/staking/validators—验证者及其质押和委托
GET/api/v1/staking/delegations/:validator—委托给某验证者的委托
GET/api/v1/staking/my-delegations/:address—某地址发起的委托
GET/api/v1/staking/rewards/:address—奖励历史；`source=stake
GET/api/v1/validators—共识验证者，含 stake、trust_score、blocks_proposed、votes_cast、last_active
GET/api/v1/slashing/history—仅节点。罚没记录。limit

参见质押与委托。

治理 ​

方法路径签名目标请求体 / 说明
POST/api/v1/governance/proposeneuro:system.governanceproposer、title、description、kind（text / PARAM_CHANGE）、payload、voting_duration + 签名字段
POST/api/v1/governance/:id/voteneuro:system.governancevoter、accept（bool）+ 签名字段
GET/api/v1/governance/proposals—status、limit（≤ 100）、offset
GET/api/v1/governance/:id—单个提案及其投票
GET/api/v1/governance/params—所有参数及其取值和说明

参见治理。

保险库（多重签名） ​

方法路径签名目标请求体 / 说明
GET/api/v1/vault/:addr/config—threshold、members
GET/api/v1/vault/:addr/proposals—支付提案
GET/api/v1/vault/member/:addr—某地址所属的保险库
POST/api/v1/vault/:addr/proposals保险库地址proposer、to、amount、description + 签名字段
POST/api/v1/vault/:addr/proposals/:id/sign保险库地址signer + 签名字段。签名数达到阈值时执行支付
POST/api/v1/vault/:addr/members保险库地址member、requester + 签名字段
POST/api/v1/vault/:addr/threshold保险库地址threshold、requester + 签名字段

实验性

保险库操作目前由接收请求的节点直接应用，而不经过共识。在其迁移到共识之前，请对同一个保险库只使用单个节点。

合约 ​

方法路径签名目标请求体 / 说明
GET/api/v1/contracts—owner、limit、offset
GET/api/v1/contracts/:address—元数据、security_score、所有者、代码哈希
GET/api/v1/contracts/:address/token-info—仅 Gateway。NRC-20 名称、符号、小数位数、供应量
POST/api/v1/contracts/:address/call—function、args、dry_run、gas_limit、caller。用 dry_run: true 读取；mainnet 上拒绝写入
POST/api/v1/contracts/deployneuro:system.deploy仅节点。owner、bytecode_hex 或 base64_wasm、name、description、template + 签名字段
POST/api/v1/contracts/analyze—仅节点。bytecode_hex → risk_score、security_score、ml_score、model、violations
POST/api/v1/contracts/attest—bytecode_hex → 以 ML-DSA-65 签名的分析结果：score、bytecode_hash、timestamp、signature、pubkey
POST/api/v1/contracts/audit—仅 Gateway。bytecode_hex → 节点分析结果（不接受源代码）
POST/api/v1/contracts/reaudit—仅 Gateway。address → 对已部署合约重新运行分析
POST/api/v1/contracts/generate—仅 Gateway。合约模板生成（SmartForge）
POST/api/v1/contracts/certifyneuro:system.cert签发安全证书（VMGuardian 运营方）
POST/api/v1/contracts/whitelistneuro:system.whitelist仅节点。bytecode_hash——受信任的模板字节码
PATCH/api/v1/contracts/:address/scoreneuro:system.score仅节点。security_score
GET/api/v1/certificates—owner、limit、offset
GET/api/v1/certificates/:id—单个证书
GET/api/v1/certificates/contract/:address—某合约的证书
GET/api/v1/templates—已注册的合约模板
GET/api/v1/templates/:id—单个模板及其 ABI
POST/api/v1/templates/registerneuro:system.templatesauthor（一个 .node）、name、description、category、bytecode_hex、abi_json、fee_unro + 签名字段
POST/api/v1/templates/deprecateneuro:system.templates仅节点。template_id、author、delete + 签名字段

AI 与模型 ​

方法路径说明
GET/api/v1/ai/status仅 Gateway。AI 模型状态
POST/api/v1/sentinel/score对交易特征打分：value、gas_price、nonce、last_nonce、balance、tx_count_last_10、recipient_tx_count、is_self_transfer → score、anomalous、category
GET/api/v1/oracle/logAI 决策日志。model、kind、subject、limit、offset
GET/api/v1/oracle/log/:id单条决策
GET/api/v1/models/registry链上模型注册表。limit、offset
GET/api/v1/models/registry/:id单个模型版本
POST/api/v1/models/register仅限验证者；签名目标为 neuro:models.registry。from、name、version、weights_hash、architecture、params_count、accuracy + 签名字段
GET/api/v1/ai/export/{blocks,txs,validators,oracle}训练数据导出（JSON Lines）
POST/api/v1/assistant/ask, GET /api/v1/assistant/health仅 Gateway。文档助手（除非设置 ASSISTANT_ENABLED=1，否则关闭）

Sentinel 信任列表 ​

方法路径签名目标请求体
POST/api/v1/trust/addneuro:system.trustowner、recipient + 签名字段
POST/api/v1/trust/removeneuro:system.trustowner、recipient + 签名字段
GET/api/v1/trust/:owner—受信任的收款方及其生效高度

账户抽象 ​

方法路径签名目标请求体
POST/api/v1/session/grantneuro:system.sessionaccount、session_pk、scope、cap、expiry_block + 签名字段
POST/api/v1/session/revokeneuro:system.sessionaccount、session_pk + 签名字段
GET/api/v1/session/list/:account—某账户的会话密钥
POST/api/v1/sponsor/depositneuro:system.sponsoraddress、amount + 签名字段
POST/api/v1/sponsor/withdrawneuro:system.sponsoraddress、amount + 签名字段
GET/api/v1/sponsor/:address—赞助池余额

参见账户抽象。

身份与恢复 ​

这些端点签名的是各自专用的消息（例如 nc-rotate|addr|add|remove|nonce），而不是 nc-tx-v2；参见身份。

方法路径请求体
POST/api/v1/identity/rotateowner、add、remove + 签名字段
POST/api/v1/identity/recovery/setupowner、guardians、threshold、timelock + 签名字段
POST/api/v1/identity/recovery/requesttarget、new_key + 签名字段
POST/api/v1/identity/recovery/approvetarget、guardian + 签名字段
POST/api/v1/identity/recovery/rejecttarget、guardian + 签名字段
POST/api/v1/identity/recovery/withdrawtarget + 签名字段
POST/api/v1/identity/recovery/cancelowner + 签名字段
GET/api/v1/identity/:addr密钥和版本
GET/api/v1/identity/recovery/:addr恢复配置及任何未完成的请求
GET/api/v1/identity/guardian-of/:addr该地址担任守护者的身份

原生资产与交易所 ​

方法路径请求体 / 说明
GET/api/v1/assets已发行的资产
GET/api/v1/assets/:id单个资产
GET/api/v1/assets/check-symbol?symbol=——该代码是否可用且有效
GET/api/v1/assets/balances/:addr资产余额
POST/api/v1/assets/issuefrom、name、symbol、decimals、initial、max_supply、reissuable、reissue_unlock_height、issue_nonce + 签名字段。手续费 asset_issue_fee
POST/api/v1/assets/transferfrom、to、asset_id、amount + 签名字段
GET/api/v1/dex/pools, /api/v1/dex/pools/:id资金池
POST/api/v1/dex/poolsfrom、asset_x、asset_y、amount_x、amount_y + 签名字段
POST/api/v1/dex/liquidity/addfrom、pool_id、max_a、max_b + 签名字段
POST/api/v1/dex/liquidity/removefrom、pool_id、shares + 签名字段
GET/api/v1/dex/quote兑换报价
POST/api/v1/dex/swapfrom、pool_id、asset_in、amount_in、min_out、deadline_height + 签名字段。在下一个区块提交时批量清算
GET/api/v1/dex/window当前批次窗口
POST/api/v1/dex/deposit, /api/v1/dex/withdraw在主余额与交易所余额之间划转资金
GET/api/v1/dex/balances/:addr, /dex/positions/:addr, /dex/activity/:addr, /dex/transactions交易所余额、LP 头寸、活动记录

| POST | /api/v1/dex/prepare | 上述任一操作的请求，外加 route（例如 dex/swap）、from、nonce → canonical、payload、summary；不会加入任何队列 |

所有资产与交易所操作的签名目标均为 neuro:system.assets，并在共识中应用，同时以 payload_signature 携带对节点准备的消息（nc-asset-op-v1|op|from|fields|nonce）的载荷签名。受保护或已保留的代码或资产名称会被拒绝。

预备操作 ​

方法路径请求体 / 说明
POST/api/v1/markers/submit{ tx, auth_to, auth_value, payload_signature }——操作响应中的 prepared 部分，加上对其 sign_payload 的签名。校验两个签名后将操作加入队列

IBC v2 实验性 ​

方法路径请求体 / 说明
POST/api/v1/ibc/channel/openfrom、channel、port、counterparty_chain、allowed_denoms + 签名字段
POST/api/v1/ibc/channel/pausefrom、channel、paused + 签名字段
POST/api/v1/ibc/transferfrom、channel、dest_chain、receiver、denom、amount + 签名字段
POST/api/v1/ibc/recvfrom、packet_id、receiver、denom、amount + 签名字段
POST/api/v1/ibc/ackfrom、id + 签名字段
POST/api/v1/ibc/redeemfrom、channel、dest_chain、receiver、denom、amount + 签名字段
POST/api/v1/ibc/client/update, /api/v1/ibc/attest轻客户端更新与证明（中继器）
GET/api/v1/ibc/channels, /ibc/packets, /ibc/denoms, /ibc/client/:chainId, /ibc/header/latest, /ibc/voucher/:addr, /ibc/pq/test-vector状态与测试向量

所有 IBC v2 操作的签名目标均为 neuro:system.ibc；recv、ack 以及通道和客户端操作仅限 IBC 运营方密钥。参见 IBC v2 与分片。

开发者文档 · nro.world

© 实验性研究软件