# 固定ウォレット

> 特定の注文やユーザーに紐付く永続的な入金アドレス。継続的および長期の支払いに最適です。

固定ウォレットは、暗号資産の支払いを受け取るための永続的なアドレスです。特定の `order_id` にリンクされ、`project_id + order_id + currency + network` の組み合わせで一意になります。

固定ウォレットの用途：

- 同一ユーザーからの繰り返し入金
- ユーザープロフィールに表示される長期的な支払いアドレス
- ユーザーごとに安定したアドレスを必要とする大量入金フロー

## 固定ウォレットを作成する

`POST /v1/static-wallet`

### リクエストパラメータ

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `currency` | string | yes | 暗号資産（USDT、BTC、ETH など） |
| `network` | string | yes | ネットワークコード |
| `order_id` | string | yes | 注文／ユーザー ID（最大 255 文字） |
| `label` | string | no | ウォレットラベル（最大 255 文字） |
| `url_callback` | string | yes | Webhook 通知の URL |
| `invite_code` | string | no | 紹介コード |

### リクエスト例

```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`

### リクエストパラメータ

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `uuid` | string | yes* | 固定ウォレット UUID |
| `address` | string | yes* | ブロックチェーンウォレットアドレス |

> **INFO:** `uuid` または `address` のいずれかが必須です。

### レスポンス例

```json
{
  "state": 0,
  "result": {
    "uuid": "019b2265-34d8-7001-a230-8f97de90d481",
    "address": "TXYZabc123...",
    "currency": "USDT",
    "network": "TRX-TRC20",
    "status": "active",
    "total_received": "1250.50",
    "transactions_count": 3,
    "created_at": "2026-01-20T12:00:00Z",
    "qr": "data:image/png;base64,iVBORw0..."
  }
}
```

- `total_received` — このウォレットで受け取ったすべての入金の合計（`currency` 単位）。
- `transactions_count` — これまでに受け取った入金回数。
- `qr` — 入金アドレスの Base64 エンコード QR の data URI（固定ウォレットでは常に存在し、アドレスは作成時に割り当てられます）。

## ウォレット一覧

`POST /v1/static-wallet/list`

### リクエストパラメータ

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `status` | string | no | ステータスでフィルタ（`active`、`inactive`） |
| `currency` | string | no | 通貨でフィルタ |
| `network` | string | no | ネットワークでフィルタ |
| `order_id` | string | no | order_id でフィルタ |
| `page` | int | no | ページ番号（デフォルト：1） |
| `per_page` | int | no | 1 ページあたりの件数（デフォルト：20、最大：100） |

### レスポンス例

```json
{
  "state": 0,
  "result": {
    "items": [
      {
        "uuid": "019b2265-...",
        "address": "TXYZabc123...",
        "currency": "USDT",
        "network": "TRX-TRC20",
        "status": "active",
        "total_received": "1250.50",
        "transactions_count": 3
      }
    ],
    "paginate": {
      "count": 1,
      "current_page": 1,
      "per_page": 20,
      "total": 1,
      "total_pages": 1,
      "has_more": false
    }
  }
}
```

## ウォレットの有効化／無効化

固定ウォレットが新規支払いを受け付けるかどうかを切り替えます。

`POST /v1/static-wallet/disable`

`POST /v1/static-wallet/enable`

### リクエスト

両方のエンドポイントは単一のパラメータを受け取ります：

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

### レスポンス例

```json
{
  "state": 0,
  "result": {
    "uuid": "019b2265-34d8-7001-a230-8f97de90d481",
    "status": "inactive",
    "message": "Static wallet disabled successfully"
  }
}
```

`enable` の場合、`status` は `"active"` になり、`message` は `"Static wallet enabled successfully"` となります。

## ウォレットのトランザクション

固定ウォレットで受け取ったすべての入金の一覧を取得します。

`POST /v1/static-wallet/transactions`

### リクエストパラメータ

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `uuid` | string | yes | 固定ウォレット UUID |
| `date_from` | date | no | 開始日（YYYY-MM-DD） |
| `date_to` | date | no | 終了日（YYYY-MM-DD） |
| `page` | int | no | ページ番号（デフォルト：1） |
| `per_page` | int | no | 1 ページあたりの件数（デフォルト：15、最大：5000） |

### レスポンス例

```json
{
  "state": 0,
  "result": {
    "items": [
      {
        "uuid": "abc123-def456-...",
        "order_id": "USER-123",
        "amount": "100.00",
        "currency": "USDT",
        "payment_status": "paid",
        "txid": "0xabc123def456...",
        "fee_amount": "3.00",
        "net_amount": "97.00",
        "created_at": "2026-01-20T15:30:00Z"
      }
    ],
    "paginate": {
      "count": 1,
      "hasPages": true,
      "perPage": 15,
      "page": 1
    }
  }
}
```

- `fee_amount` — この入金から差し引かれたプラットフォーム手数料（`currency` 単位）。
- `net_amount` — 手数料控除後にマーチャント残高にクレジットされた金額。

## 固定ウォレットの 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` は **含まれます**。

### フィールドリファレンス

| Field | Type | Description |
|-------|------|-------------|
| `uuid` | string | この入金のトランザクション（インボイス）UUID |
| `order_id` | string | 固定ウォレットの `order_id` |
| `amount` | decimal (8 dp) | 受領した暗号資産の金額 |
| `currency` | string | 受領した暗号資産（ウォレットの `currency` と一致） |
| `amount_usd` | decimal (8 dp) | 受領時点の USD 換算額 |
| `exchange_rate` | decimal | 使用された 暗号資産 / USD レート |
| `payer_currency` | string | 固定ウォレットでは `currency` と同じ |
| `payer_amount` | decimal (8 dp) | 固定ウォレットでは `amount` と同じ |
| `network` | string | ブロックチェーンネットワーク |
| `address` | string | 固定ウォレットアドレス |
| `payment_status` | string | 固定ウォレットでは常に `paid` |
| `txid` | string | ブロックチェーントランザクションハッシュ |
| `payment_amount` | decimal (8 dp) | `amount` と同じ |
| `merchant_amount` | decimal (18 dp) | **手数料控除後の金額** — クレジット計算にはこれを使用 |
| `created_at` | string (ISO 8601) | 入金が受領された日時 |
| `sign` | string (hex) | ペイロードの HMAC-SHA256 署名 |

## ベストプラクティス

- **ユニークな `order_id`** — ユーザーや注文ごとにユニークな `order_id` を使用する
- **冪等性** — 重複クレジットを避けるため、処理前に `txid` をチェックする
- **署名の検証** — 資金をクレジットする前に必ず `sign` を検証する
- **`merchant_amount` を使用する** — クレジットには `payment_amount` ではなく `merchant_amount` を使用する