SpringOpen
搜索 K

外观

Web3 Open Platform API ​

受众：开发者 摘要：/api/v1/open/web3/** 链信息、余额、Token、授权、钱包、Gas、交易、事件、价格、批量转账、资金归集；后台 Token / NFT 只读运维。

何时使用 ​

场景建议
对第三方开发者开放 Web3 能力/api/v1/open/web3/**
后台运维查 Token / NFT 状态/api/v1/money/web3/tokens 等
生产支付确认 / 事件扫描 / 结算节点走 private-rpc-urls，不对外暴露

Open Platform Web3 v1 API ​

Open Platform Web3 v1 是给第三方应用或外部系统使用的开放能力入口，统一走 /api/v1/open/web3/**，并且必须通过 AppKey/AppSecret 签名、防重放、scope 和限流。它复用 Web3 starter 的能力，但不把 web3j、私钥管理、底层 Provider 或第三方 SDK 泄露给调用方。

链信息接口会返回可公开 RPC URL，即 spring.open.web3.chains.<chain>.rpc-urls；永远不会返回 private-rpc-urls。配置类和运行时链配置快照中的私有 RPC 字段也带有 JSON 忽略注解，防止误序列化时泄露私有节点；开放 API 仍然使用 VO 白名单输出。

内置 scope：

Scope说明
open:web3:network:read查询链信息、可公开 RPC 节点和 Gas Price
open:web3:balance:read查询原生币和 ERC-20 Token 余额
open:web3:wallet:read查询钱包地址信息和 nonce
open:web3:wallet-signature:verify校验 personal_sign 和 EIP-712 typed data 签名
open:web3:transaction:read查询交易、回执、确认数和 input 解码
open:web3:event:read查询链上事件日志
open:web3:token:read查询 ERC-20 Token 信息和授权额度
open:web3:price:read查询 Token 价格，可按请求选择价格 Provider
open:web3:transfer:write批量转账计划预览和真实签名，按请求选择是否广播
open:web3:fund-collection:write资金归集计划预览和真实签名，按请求选择是否广播

当前已实现 API：

APIScope说明
GET /api/v1/open/web3/chainsopen:web3:network:read查询已启用链摘要和可公开 rpc-urls
GET /api/v1/open/web3/chains/{chain}/infoopen:web3:network:read查询指定链摘要和可公开 rpc-urls
GET /api/v1/open/web3/chains/{chain}/gas-priceopen:web3:network:read查询当前 Gas Price
GET /api/v1/open/web3/chains/{chain}/balances/native?address=...open:web3:balance:read查询原生币余额
POST /api/v1/open/web3/chains/{chain}/balances/native/batchopen:web3:balance:read批量查询原生币余额，请求体最多 100 个地址
GET /api/v1/open/web3/chains/{chain}/accounts/{address}open:web3:wallet:read查询钱包地址余额、交易计数、是否合约地址和浏览器链接
GET /api/v1/open/web3/chains/{chain}/accounts/{address}/nonce?block=pendingopen:web3:wallet:read查询地址 nonce，默认 pending
POST /api/v1/open/web3/chains/{chain}/wallet-signatures/personal/verifyopen:web3:wallet-signature:verify校验钱包 personal_sign 签名，只返回验签结果
POST /api/v1/open/web3/chains/{chain}/wallet-signatures/typed-data/verifyopen:web3:wallet-signature:verify校验 EIP-712 typed data 签名，只返回验签结果
POST /api/v1/open/web3/chains/{chain}/gas/estimateopen:web3:transaction:read按 toAddress、data、value 预估 Gas
GET /api/v1/open/web3/chains/{chain}/tokens/erc20?contractAddress=...open:web3:token:read查询 ERC-20 名称、符号、精度、总供应量和合约浏览器链接
GET /api/v1/open/web3/chains/{chain}/tokens/erc20/allowance?contractAddress=...&ownerAddress=...&spenderAddress=...open:web3:token:read查询 ERC-20 allowance 授权额度
GET /api/v1/open/web3/chains/{chain}/balances/erc20?contractAddress=...&ownerAddress=...open:web3:balance:read查询 ERC-20 余额和格式化余额
GET /api/v1/open/web3/chains/{chain}/transactions/{hash}open:web3:transaction:read查询交易详情，并返回常见 input 解码摘要
GET /api/v1/open/web3/chains/{chain}/transactions/{hash}/receiptopen:web3:transaction:read查询交易回执、执行状态、Gas 消耗和事件日志
GET /api/v1/open/web3/chains/{chain}/transactions/{hash}/confirmation?requiredConfirmations=12open:web3:transaction:read查询交易确认数和是否达到要求确认数
POST /api/v1/open/web3/chains/{chain}/transactions/confirmations/batchopen:web3:transaction:read批量查询交易确认数和成功失败状态，请求体最多 100 个 Hash
POST /api/v1/open/web3/chains/{chain}/transaction-inputs/decodeopen:web3:transaction:read解码常见 EVM input，不访问链上节点
POST /api/v1/open/web3/chains/{chain}/event-logs/searchopen:web3:event:read按区块范围、合约地址和 topics 搜索事件日志
POST /api/v1/open/web3/chains/{chain}/token-pricesopen:web3:price:read查询 Token 价格，可传入 providerName 选择价格 Provider
POST /api/v1/open/web3/chains/{chain}/transfer-plans/batchopen:web3:transfer:write预览批量转账计划，不接收私钥、不签名、不广播，只计算 nonce、gas、总额、余额是否足够和逐条计划
POST /api/v1/open/web3/chains/{chain}/transfers/batchopen:web3:transfer:write批量转账真实签名；默认 broadcast=false，显式传入 true 才广播
POST /api/v1/open/web3/chains/{chain}/fund-collection-plansopen:web3:fund-collection:write预览资金归集计划，不接收私钥、不签名、不广播，只计算余额、nonce、gas、可归集金额和逐钱包计划
POST /api/v1/open/web3/chains/{chain}/fund-collectionsopen:web3:fund-collection:write多钱包资金归集真实签名；默认 broadcast=false，显式传入 true 才广播

计划预览接口不会接收私钥，也不会生成 rawTransaction，适合在后台或第三方系统里先做金额、Gas、nonce 和余额检查。真实写交易接口会接收私钥用于本次签名。框架不会把私钥写入返回结果，调用日志也不记录请求体；生产环境仍建议只在可信服务端调用这类接口，不要让浏览器、小程序或 App 客户端直接提交私钥。

开放平台完整签名规则、调用示例、限流和计费规划见 Open Platform。

诊断接口会按链输出生产配置检查项。检查项不包含 RPC URL，也不返回任何密钥或签名材料：

coderequired说明
chain-configured是链配置已被应用加载
chain-id-configured是已显式配置链 ID
native-currency-configured否已配置原生代币符号
block-explorer-configured否已配置区块浏览器地址
connect-timeout-configured是已配置 RPC 连接超时
read-timeout-configured是已配置 RPC 读取超时
rpc-connected是RPC 可连接并返回链头基础信息
chain-id-matched是配置链 ID 与 RPC 实际链 ID 匹配
healthy是该链整体健康

生产环境建议至少保证所有 required=true 的检查项通过。block-explorer-configured 虽不是运行必需项，但建议配置，方便后台跳转核验交易、地址和区块。

交易巡检接口用于后台运维排查支付、链上任务、通知补偿和事件扫描问题。它们只读 RPC，不写订单、不写流水、不签名、不广播：

接口说明
GET /api/v1/money/web3/chains/{chainName}/transactions/{hash}查询交易本体，返回发送方、接收方、金额、Gas Price、输入数据和区块浏览器链接
GET /api/v1/money/web3/chains/{chainName}/transactions/{hash}/receipt查询交易回执，返回状态、Gas 消耗、合约地址、回滚原因和事件日志
GET /api/v1/money/web3/chains/{chainName}/transactions/{hash}/confirmation查询确认数，返回是否上链、是否成功、当前确认数和是否达到要求确认数
POST /api/v1/admin/web3/transaction-inputs/decode直接解码一段 EVM 交易 input，不访问 RPC，适合后台页面、开放平台或日志运维复用
POST /api/v1/money/web3/chains/{chainName}/event-logs/search按区块范围、合约地址和 topics 搜索事件日志，返回 topics、data 和已解码 values
POST /api/v1/money/web3/chains/{chainName}/calls/raw执行原始 eth_call，传入 to 和 data，返回节点原始十六进制结果
POST /api/v1/money/web3/chains/{chainName}/contract-calls执行 ABI 合约只读调用，传入方法名、入参和输出类型，返回 rawData 和解码 values
POST /api/v1/money/web3/chains/{chainName}/contract-calls/batch执行 ABI 合约批量只读调用，适合一次读取多个合约字段，支持单条失败后继续
POST /api/v1/money/web3/chains/{chainName}/gas-estimates执行 eth_estimateGas，用于交易前模拟 Gas，不签名不广播

巡检响应中 found=false 表示节点当前未返回交易或回执，通常是 hash 错误、交易尚未传播、交易仍 pending 或节点裁剪导致。确认数接口未传 requiredConfirmations 时默认使用 12，小于 1 时按 1 处理。

交易本体查询会返回 inputSummary，用于把常见 EVM 交易 input 解码成人类可读结构，方便后台运维快速判断交易意图：

字段说明
empty是否为空 input，普通原生币转账通常为空
selector4 字节方法选择器
known是否命中内置常见方法
decoded是否解码成功
functionName方法名称
signature方法签名
category分类，例如 erc20、erc721、erc1155、dex
parameters已解析参数，包含 name、type、value、text

当前内置解析覆盖 ERC-20 transfer、approve、transferFrom，ERC-721 / ERC-1155 常见转账与授权，以及 PancakeSwap / Uniswap V2 风格 DEX swapExact*、addLiquidity、removeLiquidity 等常用方法。未知 selector 会原样返回 selector，不会阻断交易查询；复杂或未内置 ABI 的合约仍建议使用 ABI 合约只读调用或业务侧自定义解码。

如果已经有一段 input 数据，也可以不查交易 Hash，直接调用独立解码接口：

http
POST /api/v1/admin/web3/transaction-inputs/decode
json
{
  "input": "0xa9059cbb0000000000000000000000000000000000000000000000000000000000000002..."
}

业务代码可直接复用 Web3 starter facade：

java
Web3TransactionInput input = Web3.decodeTransactionInput("0xa9059cbb...");

该方法不访问 RPC，也不依赖链配置，适合后台、样板页、开放平台和日志运维共同复用同一套解析能力。

交易巡检接口会在已配置 block-explorer-url 时返回 transactionUrl、blockUrl、currentBlockUrl、fromAddressUrl、toAddressUrl、contractAddressUrl 等跳转链接。事件日志中的 topics、data 和已解码 values 会原样返回给后台运维页面，方便人工核验；业务自动结算仍必须走独立 Service 做金额、地址、Token 合约、链 ID 和幂等校验。

事件日志搜索请求使用 JSON body，避免大量地址和 topic 让 URL 过长：

json
{
  "fromBlock": "latest",
  "toBlock": "latest",
  "addresses": ["0x0000000000000000000000000000000000000001"],
  "topics": ["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"]
}

fromBlock 和 toBlock 未传时默认只查 latest。addresses 最多 20 个，topics 最多 4 个。该接口适合后台人工排查、事件扫描规则调试和支付补偿前只读核验，不适合无上限大范围扫链；需要持续扫描时应使用 Web3 扫描检查点和 Scheduler。

原始 eth_call 示例：

json
{
  "from": null,
  "to": "0x0000000000000000000000000000000000000001",
  "data": "0x70a08231"
}

ABI 合约只读调用示例：

json
{
  "contractAddress": "0x0000000000000000000000000000000000000001",
  "functionName": "balanceOf",
  "inputs": [
    {
      "type": "address",
      "value": "0x0000000000000000000000000000000000000002"
    }
  ],
  "outputs": ["uint256"]
}

Gas 预估示例：

json
{
  "from": "0x0000000000000000000000000000000000000002",
  "to": "0x0000000000000000000000000000000000000001",
  "data": "0x",
  "value": 0
}

这些接口只用于后台调试和运维排查。即使 eth_estimateGas 成功，也不代表真实交易一定会成功；真实业务仍必须在自己的 Service 中校验链 ID、地址、金额、Token 合约、nonce、签名主体和幂等状态。

Token / NFT 只读运维 API ​

Token / NFT 后台接口用于人工核验资产、授权和 Transfer 事件。它们复用 Web3TokenClient，只读 RPC，不写链、不签名、不广播，也不会修改本地订单或用户资产：

接口说明
GET /api/v1/money/web3/chains/{chainName}/erc20/{contractAddress}查询 ERC-20 name、symbol、decimals、totalSupply
GET /api/v1/money/web3/chains/{chainName}/erc20/{contractAddress}/balances/{ownerAddress}查询 ERC-20 balanceOf
GET /api/v1/money/web3/chains/{chainName}/erc20/{contractAddress}/allowances?ownerAddress=...&spenderAddress=...查询 ERC-20 allowance
POST /api/v1/money/web3/chains/{chainName}/erc20/{contractAddress}/transfers/search搜索 ERC-20 Transfer 事件
GET /api/v1/money/web3/chains/{chainName}/nfts/{contractAddress}/standards查询 ERC-165、ERC-721、ERC-1155 标准支持情况
GET /api/v1/money/web3/chains/{chainName}/erc721/{contractAddress}查询 ERC-721 基础信息
GET /api/v1/money/web3/chains/{chainName}/erc721/{contractAddress}/balances/{ownerAddress}查询 ERC-721 持有数量
GET /api/v1/money/web3/chains/{chainName}/erc721/{contractAddress}/tokens/{tokenId}/owner查询 ERC-721 ownerOf
GET /api/v1/money/web3/chains/{chainName}/erc721/{contractAddress}/tokens/{tokenId}/uri查询 ERC-721 tokenURI
GET /api/v1/money/web3/chains/{chainName}/erc721/{contractAddress}/tokens/{tokenId}/approved查询 ERC-721 getApproved
GET /api/v1/money/web3/chains/{chainName}/erc721/{contractAddress}/approved-for-all?ownerAddress=...&operatorAddress=...查询 ERC-721 isApprovedForAll
POST /api/v1/money/web3/chains/{chainName}/erc721/{contractAddress}/transfers/search搜索 ERC-721 Transfer 事件
GET /api/v1/money/web3/chains/{chainName}/erc1155/{contractAddress}/balances/{ownerAddress}/tokens/{tokenId}查询 ERC-1155 balanceOf
POST /api/v1/money/web3/chains/{chainName}/erc1155/{contractAddress}/balances/batch批量查询 ERC-1155 balanceOfBatch
GET /api/v1/money/web3/chains/{chainName}/erc1155/{contractAddress}/tokens/{tokenId}/uri查询 ERC-1155 uri
GET /api/v1/money/web3/chains/{chainName}/erc1155/{contractAddress}/approved-for-all?ownerAddress=...&operatorAddress=...查询 ERC-1155 isApprovedForAll
POST /api/v1/money/web3/chains/{chainName}/erc1155/{contractAddress}/transfer-singles/search搜索 ERC-1155 TransferSingle 事件
POST /api/v1/money/web3/chains/{chainName}/erc1155/{contractAddress}/transfer-batches/search搜索 ERC-1155 TransferBatch 事件

Transfer 搜索请求：

json
{
  "fromBlock": "latest",
  "toBlock": "latest",
  "fromAddress": "0x0000000000000000000000000000000000000001",
  "toAddress": "0x0000000000000000000000000000000000000002",
  "operatorAddress": "0x0000000000000000000000000000000000000003",
  "tokenId": 1,
  "blockRangeSize": 1000
}

fromBlock 和 toBlock 未传时默认只查询 latest。如果需要排查较大区间，可以传 blockRangeSize 让客户端按区块段拆分 RPC 查询；生产环境不建议通过后台接口无上限扫链，持续扫描应使用 Web3 扫描检查点和 Scheduler。

ERC-1155 批量余额请求：

json
{
  "ownerAddresses": [
    "0x0000000000000000000000000000000000000001"
  ],
  "tokenIds": [1]
}

ownerAddresses 和 tokenIds 一一对应，最多 100 组。接口返回合约地址、区块浏览器链接和每组余额明细，方便后台页面直接展示。

相关 ​

Released under the Apache License 2.0.

Copyright © SpringOpen