# Statik Cüzdanlar

> Belirli bir siparişe veya kullanıcıya bağlı kalıcı yatırma adresleri; tekrarlayan ve uzun vadeli ödemeler için ideal.

Statik cüzdanlar, kripto para ödemeleri almak için kalıcı adreslerdir. Belirli bir `order_id`'ye bağlıdırlar ve `project_id + order_id + currency + network` kombinasyonuyla benzersizdirler.

Statik cüzdanları şunlar için kullanın:

- Aynı kullanıcıdan tekrarlayan yatırımlar
- Bir kullanıcı profilinde gösterilen uzun vadeli ödeme adresleri
- Kullanıcı başına stabil bir adres istediğiniz yüksek hacimli yatırım akışları

## Statik cüzdan oluştur

`POST /v1/static-wallet`

### İstek parametreleri

| Alan | Tip | Gerekli | Açıklama |
|------|-----|---------|----------|
| `currency` | string | evet | Kripto para (USDT, BTC, ETH vb.) |
| `network` | string | evet | Ağ kodu |
| `order_id` | string | evet | Sipariş/kullanıcı ID'niz (en fazla 255 karakter) |
| `label` | string | hayır | Cüzdan etiketi (en fazla 255 karakter) |
| `url_callback` | string | evet | Webhook bildirimleri için URL |
| `invite_code` | string | hayır | Yönlendiren kodu |

### İstek örneği

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

### Yanıt örneği

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

## Cüzdan bilgisi

Statik cüzdan bilgisini `uuid` veya `address` ile alın.

`POST /v1/static-wallet/info`

### İstek parametreleri

| Alan | Tip | Gerekli | Açıklama |
|------|-----|---------|----------|
| `uuid` | string | evet* | Statik cüzdan UUID'si |
| `address` | string | evet* | Blockchain cüzdan adresi |

> **INFO:** `uuid` veya `address`'ten en az biri gereklidir.

### Yanıt örneği

```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` — bu cüzdan tarafından alınan tüm yatırımların toplamı, `currency` cinsinden.
- `transactions_count` — şu ana kadar alınan yatırım sayısı.
- `qr` — yatırma adresinin Base64 ile encode edilmiş QR data URI'si (statik cüzdanlar için her zaman mevcuttur, adres oluşturma sırasında atanır).

## Cüzdan listesi

`POST /v1/static-wallet/list`

### İstek parametreleri

| Alan | Tip | Gerekli | Açıklama |
|------|-----|---------|----------|
| `status` | string | hayır | Duruma göre filtre (`active`, `inactive`) |
| `currency` | string | hayır | Para birimine göre filtre |
| `network` | string | hayır | Ağa göre filtre |
| `order_id` | string | hayır | order_id'ye göre filtre |
| `page` | int | hayır | Sayfa numarası (varsayılan: 1) |
| `per_page` | int | hayır | Sayfa başına öğe (varsayılan: 20, en fazla: 100) |

### Yanıt örneği

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

## Cüzdanı etkinleştir / devre dışı bırak

Bir statik cüzdanın yeni ödemeleri kabul edip etmeyeceğini değiştirin.

`POST /v1/static-wallet/disable`

`POST /v1/static-wallet/enable`

### İstek

Her iki endpoint de tek bir parametre alır:

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

### Yanıt örneği

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

`enable` için `status` `"active"`'tir ve `message` `"Static wallet enabled successfully"` olarak okunur.

## Cüzdan işlemleri

Bir statik cüzdan tarafından alınan tüm yatırımların listesini alın.

`POST /v1/static-wallet/transactions`

### İstek parametreleri

| Alan | Tip | Gerekli | Açıklama |
|------|-----|---------|----------|
| `uuid` | string | evet | Statik cüzdan UUID'si |
| `date_from` | date | hayır | Başlangıç tarihi (YYYY-MM-DD) |
| `date_to` | date | hayır | Bitiş tarihi (YYYY-MM-DD) |
| `page` | int | hayır | Sayfa numarası (varsayılan: 1) |
| `per_page` | int | hayır | Sayfa başına öğe (varsayılan: 15, en fazla: 5000) |

### Yanıt örneği

```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` — bu yatırımdan düşülen platform ücreti, `currency` cinsinden.
- `net_amount` — ücret düşüldükten sonra merchant bakiyesine yansıtılan tutar.

## Statik cüzdan webhook'ları

Bir statik cüzdana ödeme alındığında, sistem `url_callback` adresine bir webhook gönderir.

> **WARNING:** Statik cüzdanlar için webhook formatı, normal ödeme webhook'larından farklıdır. Özellikle, statik cüzdan webhook'ları alacaklandırma için kullanmanız gereken bir `merchant_amount` alanı içerir.

### Webhook payload'u

```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:** Statik cüzdan webhook'ları `url` veya `expires_at` **içermez** (çünkü adres kalıcıdır, bir oturum değil). `exchange_rate` ve `created_at` **içerir**.

### Alan referansı

| Alan | Tip | Açıklama |
|------|-----|----------|
| `uuid` | string | Bu yatırım için işlem (fatura) UUID'si |
| `order_id` | string | Statik cüzdanınızın `order_id`'si |
| `amount` | decimal (8 dp) | Alınan kripto tutarı |
| `currency` | string | Alınan kripto (cüzdanın `currency`'si ile eşleşir) |
| `amount_usd` | decimal (8 dp) | Alındığı andaki USD değeri |
| `exchange_rate` | decimal | Kullanılan kripto / USD kuru |
| `payer_currency` | string | Statik cüzdanlarda `currency` ile aynı |
| `payer_amount` | decimal (8 dp) | Statik cüzdanlarda `amount` ile aynı |
| `network` | string | Blockchain ağı |
| `address` | string | Statik cüzdan adresi |
| `payment_status` | string | Statikler için her zaman `paid` |
| `txid` | string | Blockchain işlem hash'i |
| `payment_amount` | decimal (8 dp) | `amount` ile aynı |
| `merchant_amount` | decimal (18 dp) | **Ücret düşümünden sonraki tutar** — alacaklandırma için bunu kullanın |
| `created_at` | string (ISO 8601) | Yatırımın alındığı zaman |
| `sign` | string (hex) | Payload'un HMAC-SHA256 imzası |

## En iyi uygulamalar

- **Benzersiz `order_id`** — Her kullanıcı veya sipariş için benzersiz bir `order_id` kullanın
- **Idempotency** — Yinelenen alacaklandırmaları önlemek için işlemden önce `txid`'yi kontrol edin
- **İmzaları doğrulayın** — Fonları alacaklandırmadan önce HER ZAMAN `sign` imzasını doğrulayın
- **`merchant_amount` kullanın** — Kullanıcıları `payment_amount`'a değil, `merchant_amount`'a göre alacaklandırın