跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://docs.nexfi.robert.dpdns.org/llms.txt

Use this file to discover all available pages before exploring further.

​
Wallet 配置与资产

本页对照详细设计文档补充 Wallet 资产侧接口的用途、入参、出参与示例，适合作为 API Reference 的中文阅读入口。

​
GET /api/v1/config/environment

​
用途

获取钱包客户端运行环境、支持链与功能开关，客户端启动时优先调用。

​
请求参数

无。

​
响应字段

字段路径类型说明示例
codeInteger业务状态码，0 表示成功0
msgString返回消息ok
data.environmentString运行环境prod
data.testnetOnlyBoolean是否仅开放测试网络true
data.supportedChainIdsInteger[]当前客户端允许使用的链 ID 列表[8453, 11155111]
data.buildVersionString当前服务端配置版本1.0.0
data.featureFlagsObject功能开关集合{ "balancesEnabled": true }
data.announcementObject全局公告配置{ "enabled": false }
data.maintenanceObject维护模式配置{ "enabled": false }

​
响应示例

{
  "code": 0,
  "msg": "ok",
  "data": {
    "environment": "prod",
    "testnetOnly": true,
    "supportedChainIds": [8453, 11155111],
    "buildVersion": "1.0.0",
    "featureFlags": {
      "balancesEnabled": true,
      "historyEnabled": true,
      "contractsEnabled": true,
      "adminWriteEnabled": false
    },
    "announcement": {
      "enabled": false,
      "level": "info",
      "title": "",
      "message": ""
    },
    "maintenance": {
      "enabled": false,
      "reason": ""
    }
  }
}

​
业务说明

  • 该接口通常用于 App 冷启动配置加载。
  • supportedChainIds 应与网络列表接口联动使用。
  • featureFlags 用于前端灰度控制，不应用作最终权限依据。

​
GET /api/v1/networks

​
用途

返回已启用主网与测试网列表，供网络切换、资产页筛选和收款网络展示使用。

​
请求参数

无。

​
响应字段

字段路径类型说明示例
data.mainnetsArray主网列表[]
data.testnetsArray测试网列表[]
data.*[].chainIdInteger链 ID8453
data.*[].nameString链名称Base
data.*[].nativeSymbolString原生币符号ETH
data.*[].rpcUrlString默认 RPC 地址https://...
data.*[].explorerUrlString浏览器地址https://basescan.org
data.*[].faucetUrlString测试币水龙头地址https://...
data.*[].isTestnetBoolean是否测试网false
data.*[].enabledBoolean是否启用true

​
响应示例

{
  "code": 0,
  "msg": "ok",
  "data": {
    "mainnets": [
      {
        "chainId": 8453,
        "name": "Base",
        "nativeSymbol": "ETH",
        "rpcUrl": "https://mainnet.base.org",
        "explorerUrl": "https://basescan.org",
        "faucetUrl": "",
        "isTestnet": false,
        "enabled": true
      }
    ],
    "testnets": [
      {
        "chainId": 11155111,
        "name": "Sepolia",
        "nativeSymbol": "ETH",
        "rpcUrl": "https://rpc.sepolia.org",
        "explorerUrl": "https://sepolia.etherscan.io",
        "faucetUrl": "https://faucet.quicknode.com/ethereum/sepolia",
        "isTestnet": true,
        "enabled": true
      }
    ]
  }
}

​
GET /api/v1/tokens

​
用途

查询 Token 目录，用于资产搜索、转账币种选择和收款币种展示。

​
Query 参数

参数类型必填说明示例
chainIdString否单链过滤8453
chainIdsString否多链过滤，逗号分隔1,8453,42161
qString否搜索关键字USDC
keywordString否搜索关键字，语义与 q 等价eth
addressString否合约地址精确查询，通常配合 chainId 使用0x833589f...
verifiedOnlyBoolean String否是否只返回已验证资产true

​
请求示例

GET /api/v1/tokens?chainId=8453&keyword=USDC&verifiedOnly=true

​
响应字段

字段路径类型说明示例
data.itemsArrayToken 结果集[]
data.items[].chainIdInteger链 ID8453
data.items[].addressString合约地址0x833589f...
data.items[].symbolStringToken 符号USDC
data.items[].nameStringToken 名称USD Coin
data.items[].decimalsInteger精度6
data.items[].logoUrlStringLogo 地址https://...
data.items[].isVerifiedBoolean是否已验证true

​
响应示例

{
  "code": 0,
  "msg": "ok",
  "data": {
    "items": [
      {
        "chainId": 8453,
        "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
        "symbol": "USDC",
        "name": "USD Coin",
        "decimals": 6,
        "logoUrl": "https://assets.example.com/usdc.png",
        "isVerified": true
      }
    ]
  }
}

​
业务说明

  • q 与 keyword 建议保留兼容，客户端优先统一用一个字段。
  • verifiedOnly=true 适合默认资产列表，降低假币风险。
  • address 命中时通常只返回单条记录。

​
GET /api/v1/balances/{address}

​
用途

获取地址在指定链范围内的原生币与 Token 余额，是资产首页核心接口。

​
Path / Query 参数

参数类型必填说明示例
addressString是钱包地址0xabc...
chainIdsString否指定链 ID，逗号分隔8453,1
includeTokensBoolean String否是否包含 ERC20 等代币true
includeNativeBoolean String否是否包含原生币true

​
请求示例

GET /api/v1/balances/0xabc...?chainIds=8453&includeTokens=true&includeNative=true

​
响应字段

字段路径类型说明示例
data.addressString钱包地址0xabc...
data.updatedAtString聚合更新时间2026-05-11T10:00:00.000Z
data.chainsArray本次实际查询链摘要[]
data.chains[].chainIdInteger链 ID8453
data.chains[].nameString链名称Base
data.chains[].isTestnetBoolean是否测试网false
data.balancesArray余额列表[]
data.balances[].chainIdInteger余额所属链 ID8453
data.balances[].tokenAddressStringnative 或合约地址native
data.balances[].symbolString资产符号ETH
data.balances[].nameString资产名称ETH
data.balances[].decimalsInteger精度18
data.balances[].balanceString最小单位原始余额1000000000000000000
data.balances[].formattedBalanceString格式化后的可展示余额1
data.balances[].isNativeBoolean是否原生币true

​
响应示例

{
  "code": 0,
  "msg": "ok",
  "data": {
    "address": "0xabc...",
    "updatedAt": "2026-05-11T10:00:00.000Z",
    "chains": [
      {
        "chainId": 8453,
        "name": "Base",
        "isTestnet": false
      }
    ],
    "balances": [
      {
        "chainId": 8453,
        "tokenAddress": "native",
        "symbol": "ETH",
        "name": "ETH",
        "decimals": 18,
        "balance": "1000000000000000000",
        "formattedBalance": "1",
        "isNative": true
      }
    ]
  }
}

​
业务说明

  • 该接口返回链上余额，不直接附带法币估值。
  • 建议客户端再调用 /api/v1/prices 合并价格展示。
  • 部分链查询失败时可采用部分成功策略，不必整体失败。

​
GET /api/v1/prices

​
用途

返回资产价格，供资产总值、单币估值和涨跌幅展示使用。

​
Query 参数

参数类型必填说明示例
symbolsString否资产符号列表，逗号分隔ETH,USDC
assetsString否资产标识列表，可扩展为链+地址键8453:0x8335...
currencyEnum否展示币种，支持 USD、CNYUSD

​
请求示例

GET /api/v1/prices?symbols=ETH,USDC&currency=USD

​
响应字段

字段路径类型说明示例
data.currencyString价格展示币种USD
data.updatedAtString价格更新时间2026-05-11T10:00:00.000Z
data.itemsArray价格列表[]
data.items[].symbolString资产符号ETH
data.items[].usdPriceNumber | Null当前价格3500.12
data.items[].usdChange24hNumber | Null24 小时涨跌幅-1.24

​
响应示例

{
  "code": 0,
  "msg": "ok",
  "data": {
    "currency": "USD",
    "updatedAt": "2026-05-11T10:00:00.000Z",
    "items": [
      {
        "symbol": "ETH",
        "usdPrice": 3500.12,
        "usdChange24h": -1.24
      },
      {
        "symbol": "USDC",
        "usdPrice": 1,
        "usdChange24h": 0
      }
    ]
  }
}

​
GET /api/v1/receive/options/{address}

​
用途

返回收款可选资产及其可接收网络，用于“收款”页与二维码分享页。

​
Path / Query 参数

参数类型必填说明示例
addressString是钱包地址0xabc...
chainIdsString否链过滤8453,1
includeZeroBoolean String否是否包含零余额资产false

​
响应字段

字段路径类型说明示例
data.addressString钱包地址0xabc...
data.updatedAtString聚合更新时间2026-05-11T10:00:00.000Z
data.assetsArray可收款资产列表[]
data.assets[].symbolString资产符号USDC
data.assets[].nameString资产名称USD Coin
data.assets[].tokenAddressStringToken 地址0x8335...
data.assets[].networksArray可收款网络列表[]
data.assets[].networks[].chainIdInteger网络链 ID8453
data.assets[].networks[].nameString网络名称Base
data.assets[].networks[].nativeSymbolString该网络 Gas 币符号ETH
data.assets[].networks[].explorerUrlString区块浏览器地址https://basescan.org
data.assets[].networks[].faucetUrlString测试网水龙头地址“

​
响应示例

{
  "code": 0,
  "msg": "ok",
  "data": {
    "address": "0xabc...",
    "updatedAt": "2026-05-11T10:00:00.000Z",
    "assets": [
      {
        "symbol": "USDC",
        "name": "USD Coin",
        "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
        "networks": [
          {
            "chainId": 8453,
            "name": "Base",
            "nativeSymbol": "ETH",
            "explorerUrl": "https://basescan.org",
            "faucetUrl": ""
          }
        ]
      }
    ]
  }
}

​
业务说明

  • includeZero=false 时更适合默认 UI 展示。
  • 收款网络清单基于配置与资产目录聚合，不代表链上一定已有余额。
  • 若同一资产跨多链可收款，应在客户端明确展示网络差异。