# 静态钱包

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

静态钱包是用于接收加密货币付款的永久地址，与特定的 `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 | 是* | 区块链钱包地址 |

> **INFO:** `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。

> **WARNING:** 静态钱包 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"
}
```

> **INFO:** 静态钱包 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`）为用户入账