支付与提现/静态钱包

静态钱包

与特定订单或用户绑定的永久存款地址，适合周期性和长期支付场景。

查看 Markdown·llms.txt

静态钱包是用于接收加密货币付款的永久地址，与特定的 order_id 关联，按 project_id + order_id + currency + network 组合保持唯一。

适用场景：

来自同一用户的周期性存款
显示在用户资料页的长期收款地址
希望为每位用户保留稳定地址的高频充值场景

创建静态钱包

POST/v1/static-wallet

请求参数

字段	类型	必需	描述
`currency`	string	是	加密货币（USDT、BTC、ETH 等）
`network`	string	是	网络代码
`order_id`	string	是	您的订单 / 用户 ID（最多 255 个字符）
`label`	string	否	钱包标签（最多 255 个字符）
`url_callback`	string	是	webhook 通知 URL
`invite_code`	string	否	推荐人代码

请求示例

JSON

{
  "currency": "USDT",
  "network": "TRX-TRC20",
  "order_id": "USER-123",
  "label": "User deposit #123",
  "url_callback": "https://your-site.com/webhook/static"
}

响应示例

JSON

{
  "state": 0,
  "result": {
    "uuid": "019b2265-34d8-7001-a230-8f97de90d481",
    "address": "TXYZabc123...",
    "currency": "USDT",
    "network": "TRX-TRC20",
    "label": "User deposit #123",
    "order_id": "USER-123",
    "status": "active",
    "url": "https://go.2328.io/static/019b2265-34d8-7001-a230-8f97de90d481",
    "created_at": "2026-01-20T12:00:00Z",
    "qr": "data:image/png;base64,iVBORw0..."
  }
}

钱包信息

通过 uuid 或 address 获取静态钱包信息。

POST/v1/static-wallet/info

字段	类型	必需	描述
`uuid`	string	是*	静态钱包 UUID
`address`	string	是*	区块链钱包地址

uuid 或 address 至少需要提供一个。

钱包列表

POST/v1/static-wallet/list

字段	类型	必需	描述
`status`	string	否	按状态过滤（`active`、`inactive`）
`currency`	string	否	按币种过滤
`network`	string	否	按网络过滤
`order_id`	string	否	按 order_id 过滤
`page`	int	否	页码（默认：1）
`per_page`	int	否	每页条数（默认：20，最大：100）

启用 / 禁用钱包

切换静态钱包是否接受新的支付。

POST/v1/static-wallet/disable

POST/v1/static-wallet/enable

两个端点都只接受单一参数：

JSON

{
  "uuid": "019b2265-34d8-7001-a230-8f97de90d481"
}

钱包交易记录

获取静态钱包收到的所有充值。

POST/v1/static-wallet/transactions

字段	类型	必需	描述
`uuid`	string	是	静态钱包 UUID
`date_from`	date	否	起始日期（YYYY-MM-DD）
`date_to`	date	否	结束日期（YYYY-MM-DD）
`page`	int	否	页码（默认：1）
`per_page`	int	否	每页条数（默认：15，最大：5000）

静态钱包 webhook

当静态钱包收到付款时，系统会向 url_callback 发送 webhook。

静态钱包 webhook 与常规支付 webhook 格式不同。特别是，静态钱包 webhook 包含 merchant_amount 字段，应使用该字段进行入账。

Webhook 载荷

JSON

{
  "uuid": "a28b293f-5c76-4053-8062-ae9ca4ab784b",
  "order_id": "USER-7666308594",
  "amount": "10.00000000",
  "currency": "USDT",
  "amount_usd": "10.00000000",
  "exchange_rate": "1.00000000",
  "payer_currency": "USDT",
  "payer_amount": "10.00000000",
  "network": "TRX-TRC20",
  "address": "TMU9Tgpchvgbywkbj5SdC8KJS73t5m3M7G",
  "payment_status": "paid",
  "txid": "8369ede26a0da05b1bae154b4bb4072eb2453db30ba86b21831902670929454f",
  "payment_amount": "10.00000000",
  "merchant_amount": "9.920000000000000000",
  "created_at": "2026-05-09T16:13:04+03:00",
  "sign": "dd958d1405febce670a9a196e9141784b9f2a5f39cd6d1832d6f3f68d0de1e10"
}

静态钱包 webhook 不包含 url 与 expires_at（地址是永久的，不存在会话概念），但包含 exchange_rate 与 created_at。

字段说明

字段	类型	说明
`uuid`	string	本次充值的交易（账单）UUID
`order_id`	string	您配置的静态钱包 `order_id`
`amount`	decimal (8 位小数)	收到的加密货币金额
`currency`	string	收到的加密货币（与钱包 `currency` 一致）
`amount_usd`	decimal (8 位小数)	收款时的美元等值
`exchange_rate`	decimal	加密货币 / 美元的汇率
`payer_currency`	string	静态钱包场景下与 `currency` 一致
`payer_amount`	decimal (8 位小数)	静态钱包场景下与 `amount` 一致
`network`	string	区块链网络
`address`	string	静态钱包地址
`payment_status`	string	静态钱包始终为 `paid`
`txid`	string	链上交易哈希
`payment_amount`	decimal (8 位小数)	与 `amount` 一致
`merchant_amount`	decimal (18 位小数)	扣除手续费后的入账金额 — 应使用此字段为用户入账
`created_at`	string (ISO 8601)	收到充值的时间
`sign`	string (hex)	载荷的 HMAC-SHA256 签名

最佳实践

唯一的 order_id — 为每个用户或订单使用唯一的 order_id
幂等性 — 入账前先按 txid 去重，避免重复入账
校验签名 — 入账资金前务必校验 sign 签名
使用 merchant_amount — 按 merchant_amount（而非 payment_amount）为用户入账