Wallet Manager API
第三方对接文档 · API Reference
v1.0REST / JSON

认证方式

所有受保护接口需要通过以下任意一种方式传递 API Key：

方式一：请求头 X-Api-Key
X-Api-Key: your_api_key_here
方式二：Authorization Bearer
Authorization: Bearer your_api_key_here
API Key 在管理后台 设置页面 生成和管理。

获取授权配置 公开

获取前端授权页所需的合约地址、代币地址及网络信息。无需认证。

GET/api/public/authorize-config

请求参数

无

响应示例

{
  "contractAddress": "0xCf7Ed3AccA5a467e9e704C703E8D87F634fB0Fc9",
  "tokens": [
    {
      "symbol": "USDT",
      "address": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
      "decimals": 6
    },
    {
      "symbol": "USDC",
      "address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
      "decimals": 6
    }
  ],
  "network": {
    "chainId": 1,
    "name": "Ethereum Mainnet",
    "rpcUrl": "https://eth-mainnet.g.alchemy.com/v2/..."
  }
}

字段说明

字段类型说明
contractAddressstringWalletManager 合约地址
tokensarray代币配置数组，每项含 symbol / address / decimals
tokens[].symbolstring代币符号，如 USDT
tokens[].addressstring代币合约地址
tokens[].decimalsnumber代币精度，如 6
network.chainIdnumber链 ID（主网 1，本地测试 31337）
network.namestring网络名称
network.rpcUrlstringRPC 节点地址

获取账户列表 需认证

返回所有已授权的钱包地址及其 USDT / USDC / ETH 余额与授权额度。

GET/api/wallets/list

请求参数

无

请求示例

cURL
curl -X GET https://your-domain.com/api/wallets/list \
  -H "X-Api-Key: your_api_key_here"

响应示例

{
  "wallets": [
    {
      "address": "0xUserWalletAddress...",
      "owner": "0xDeployerAddress...",
      "addedAt": "2025-01-01T00:00:00.000Z",
      "ethBalance": "0.5",
      "usdtBalance": "1000.000000",
      "usdtAllowance": "115792089237316195423570985008687907853269984665640564039457.584007913129639935",
      "usdcBalance": "500.000000",
      "usdcAllowance": "0.000000"
    }
  ]
}

字段说明（wallets 数组元素）

字段类型说明
addressstring钱包地址（已授权的用户）
ownerstring授权操作发起方
addedAtstring授权时间（ISO 8601）
ethBalancestringETH 余额（单位：ETH）
usdtBalancestringUSDT 余额（单位：USDT，6位小数）
usdtAllowancestringUSDT 对合约的授权额度
usdcBalancestringUSDC 余额（单位：USDC，6位小数）
usdcAllowancestringUSDC 对合约的授权额度

添加账户（管理员授权注册） 需认证

将一个钱包地址注册到 WalletManager 合约，使其出现在账户列表中。
注意： 该接口仅完成链上注册，用户还需要自行到授权页对 USDT/USDC 执行 approve， 合约才能代为转账。

POST/api/wallets/authorize

请求参数（JSON Body）

字段类型必填说明
addressstring是要注册的钱包地址（0x...）

请求示例

cURL
curl -X POST https://your-domain.com/api/wallets/authorize \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: your_api_key_here" \
  -d '{"address": "0xUserWalletAddress..."}'

响应示例

// 首次注册
{ "success": true, "message": "授权成功" }

// 已注册
{ "success": true, "message": "已注册" }

错误码

HTTP 状态message原因
400地址不能为空未传 address 参数
500（合约错误信息）链上调用失败

执行转账 需认证

从指定钱包地址将 USDT 或 USDC 转账到目标地址。
前提： 用户已完成链上 approve（授权额度 ≥ 转账金额）。

POST/api/wallets/withdraw

请求参数（JSON Body）

字段类型必填说明
tokenstring是代币合约地址（USDT 或 USDC）
fromstring是来源钱包地址（已授权用户）
tostring是目标收款地址
amountstring是转账金额（人类可读单位，如 "100.5"）

请求示例

cURL
curl -X POST https://your-domain.com/api/wallets/withdraw \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: your_api_key_here" \
  -d '{
    "token": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
    "from":  "0xUserWalletAddress...",
    "to":    "0xRecipientAddress...",
    "amount": "100"
  }'

响应示例

{
  "success": true,
  "txHash": "0xTransactionHash..."
}

错误码

HTTP 状态message原因
400参数不完整缺少必填字段
401请先登录或提供有效的 API Key未认证
500（合约错误信息）余额不足、未授权等链上错误

用户授权流程

完整对接需要以下步骤：

  1. 调用添加账户接口 — POST /api/wallets/authorize
    将用户钱包地址注册到合约。
  2. 引导用户完成链上 approve
    将用户引导至授权页： 
    // USDT 授权（无限额度）
https://your-domain.com/authorize/usdt

// USDC 授权（指定 100 USDC）
https://your-domain.com/authorize/usdc?amount=100
    • ?amount=100 — 授权固定金额（单位：代币）
    • 不传 amount — 默认无限授权
  3. 查询账户列表 — GET /api/wallets/list
    确认 usdtAllowance / usdcAllowance 大于 0。
  4. 执行转账 — POST /api/wallets/withdraw