# स्टैटिक वॉलेट

> किसी विशिष्ट order या user से जुड़े स्थायी deposit address, recurring और लंबी अवधि के भुगतानों के लिए perfect।

स्टैटिक वॉलेट क्रिप्टोकरेंसी भुगतान प्राप्त करने के लिए स्थायी address हैं। ये एक विशिष्ट `order_id` से linked होते हैं और `project_id + order_id + currency + network` के संयोजन से unique होते हैं।

स्टैटिक वॉलेट का उपयोग करें इन कामों के लिए:

- एक ही user से recurring deposit
- User profile पर दिखाए गए लंबी अवधि के payment address
- High-volume deposit flows जहाँ आप प्रति user एक स्थिर address चाहते हैं

## स्टैटिक वॉलेट बनाएँ

`POST /v1/static-wallet`

### Request parameters

| Field | Type | आवश्यक | Description |
|-------|------|----------|-------------|
| `currency` | string | हाँ | क्रिप्टोकरेंसी (USDT, BTC, ETH, इत्यादि) |
| `network` | string | हाँ | Network code |
| `order_id` | string | हाँ | आपका order/user ID (अधिकतम 255 chars) |
| `label` | string | नहीं | वॉलेट label (अधिकतम 255 chars) |
| `url_callback` | string | हाँ | webhook notifications के लिए URL |
| `invite_code` | string | नहीं | Referrer code |

### Request example

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

### Response example

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

### Request parameters

| Field | Type | आवश्यक | Description |
|-------|------|----------|-------------|
| `uuid` | string | हाँ* | स्टैटिक वॉलेट UUID |
| `address` | string | हाँ* | Blockchain वॉलेट address |

> **INFO:** `uuid` या `address` में से कम से कम एक आवश्यक है।

### Response example

```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` में, इस वॉलेट द्वारा प्राप्त सभी deposits का योग।
- `transactions_count` — अब तक प्राप्त deposits की संख्या।
- `qr` — deposit address का Base64-encoded QR data URI (स्टैटिक वॉलेट के लिए हमेशा उपस्थित, address creation पर assigned होता है)।

## वॉलेट सूची

`POST /v1/static-wallet/list`

### Request parameters

| Field | Type | आवश्यक | Description |
|-------|------|----------|-------------|
| `status` | string | नहीं | status के अनुसार filter (`active`, `inactive`) |
| `currency` | string | नहीं | currency के अनुसार filter |
| `network` | string | नहीं | network के अनुसार filter |
| `order_id` | string | नहीं | order_id के अनुसार filter |
| `page` | int | नहीं | Page संख्या (default: 1) |
| `per_page` | int | नहीं | प्रति page items (default: 20, अधिकतम: 100) |

### Response example

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

## वॉलेट enable / disable करें

टॉगल करें कि स्टैटिक वॉलेट नए भुगतान स्वीकार करता है या नहीं।

`POST /v1/static-wallet/disable`

`POST /v1/static-wallet/enable`

### Request

दोनों endpoints एक single parameter लेते हैं:

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

### Response example

```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"` पढ़ता है।

## वॉलेट transactions

स्टैटिक वॉलेट द्वारा प्राप्त सभी deposits की सूची प्राप्त करें।

`POST /v1/static-wallet/transactions`

### Request parameters

| Field | Type | आवश्यक | Description |
|-------|------|----------|-------------|
| `uuid` | string | हाँ | स्टैटिक वॉलेट UUID |
| `date_from` | date | नहीं | प्रारंभ तिथि (YYYY-MM-DD) |
| `date_to` | date | नहीं | अंतिम तिथि (YYYY-MM-DD) |
| `page` | int | नहीं | Page संख्या (default: 1) |
| `per_page` | int | नहीं | प्रति page items (default: 15, अधिकतम: 5000) |

### Response example

```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` — इस deposit से कटी हुई platform fee, `currency` में।
- `net_amount` — fee के बाद merchant बैलेंस में जमा की गई राशि।

## स्टैटिक वॉलेट webhooks

जब किसी स्टैटिक वॉलेट पर भुगतान प्राप्त होता है, तो सिस्टम `url_callback` पर एक webhook भेजता है।

> **WARNING:** स्टैटिक वॉलेट के लिए webhook format सामान्य payment webhooks से भिन्न है। विशेष रूप से, स्टैटिक वॉलेट webhooks में एक `merchant_amount` field होता है जिसका उपयोग आपको crediting के लिए करना चाहिए।

### Webhook payload

```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:** स्टैटिक वॉलेट webhooks में `url` या `expires_at` **शामिल नहीं** होते (क्योंकि address स्थायी है, session नहीं)। इनमें `exchange_rate` और `created_at` **शामिल** होते हैं।

### Field reference

| Field | Type | Description |
|-------|------|-------------|
| `uuid` | string | इस deposit के लिए Transaction (invoice) UUID |
| `order_id` | string | आपका स्टैटिक वॉलेट `order_id` |
| `amount` | decimal (8 dp) | प्राप्त crypto राशि |
| `currency` | string | प्राप्त crypto (वॉलेट के `currency` से मेल खाता है) |
| `amount_usd` | decimal (8 dp) | प्राप्ति के समय USD value |
| `exchange_rate` | decimal | उपयोग की गई Crypto / USD दर |
| `payer_currency` | string | स्टैटिक वॉलेट के लिए `currency` के समान |
| `payer_amount` | decimal (8 dp) | स्टैटिक वॉलेट के लिए `amount` के समान |
| `network` | string | Blockchain network |
| `address` | string | स्टैटिक वॉलेट address |
| `payment_status` | string | स्टैटिक के लिए हमेशा `paid` |
| `txid` | string | Blockchain transaction hash |
| `payment_amount` | decimal (8 dp) | `amount` के समान |
| `merchant_amount` | decimal (18 dp) | **Fee deduction के बाद की राशि** — crediting के लिए इसका उपयोग करें |
| `created_at` | string (ISO 8601) | Deposit कब प्राप्त हुआ |
| `sign` | string (hex) | Payload का HMAC-SHA256 सिग्नेचर |

## Best practices

- **Unique `order_id`** — प्रत्येक user या order के लिए एक unique `order_id` का उपयोग करें
- **Idempotency** — डुप्लीकेट credit से बचने के लिए processing से पहले `txid` जाँचें
- **सिग्नेचर verify करें** — फंड credit करने से पहले हमेशा `sign` सिग्नेचर verify करें
- **`merchant_amount` का उपयोग करें** — `payment_amount` के बजाय `merchant_amount` के आधार पर users को credit करें