پرش به محتویات

Wallet API - رفرنس کامل

توضیحات کلی

این API برای مدیریت کیف پول‌های کاربران، واریز، برداشت و مشاهده تراکنش‌ها استفاده می‌شود.

ساختار داده Wallet

{
  "uid": "01998a00-329e-7352-a857-349ca796d4be",
  "created_at": "2025-09-27T07:08:12.830000",
  "updated_at": "2025-09-27T07:08:12.830000",
  "is_deleted": false,
  "meta_data": null,
  "user_id": "0197f464-46e0-7392-a54f-b08f07be6926",
  "tenant_id": "0197f464-46c8-72a1-8b23-0819b8622a0c",
  "wallet_purpose": "regular",
  "owner_type": "user",
  "balance_type": "positive",
  "status": "active",
  "main_currency": "IRR",
  "is_default": true,
  "balance": {
    "IRR": {
      "currency": "IRR",
      "total": "1078056999.995",
      "held": "106000000.0",
      "available": "972056999.995",
      "stats": {
        "IRR": "1078056999.995",
        "USD": "1197.841111105555555555555556",
        "EUR": "1078.056999995"
      },
      "meta_data": {
        "name": {
          "fa": "ریال",
          "en": "Iranian Rial"
        },
        "symbol": "IRR",
        "precision": 0,
        "icon": "https://flagcdn.com/w40/ir.png",
        "is_crypto": false,
        "color": "#1976d2",
        "unit_value_irr": 1
      },
      "value_stats": {
        "IRR": "1078056999.995",
        "USD": "1197.841111105555555555555556",
        "EUR": "1078.056999995"
      },
      "properties": null
    },
    "USD": {
      "currency": "USD",
      "total": "54467.74545455",
      "held": "1770.34545455",
      "available": "52697.40000000",
      "stats": {
        "IRR": "49020970909.09500000",
        "USD": "54467.74545455",
        "EUR": "49020.970909095"
      },
      "meta_data": {
        "name": {
          "fa": "دلار",
          "en": "Dollar"
        },
        "symbol": "USD",
        "precision": 2,
        "icon": "https://flagcdn.com/w40/us.png",
        "is_crypto": false,
        "color": "#f7931a",
        "unit_value_irr": 900000
      },
      "value_stats": {
        "IRR": "49020970909.09500000",
        "USD": "54467.74545455",
        "EUR": "49020.970909095"
      },
      "properties": null
    }
  }
}

فیلدها

اطلاعات پایه کیف پول

  • uid: شناسه منحصر به فرد کیف پول (string)

  • user_id: شناسه کاربر مالک کیف پول (string)

  • tenant_id: شناسه تنانت/سازمان (string)

  • wallet_purpose: هدف کیف پول (string، مقدار: "regular")

  • owner_type: نوع مالک (string، مقدار: "user")

  • balance_type: نوع موجودی (string، مقدار: "positive")

  • status: وضعیت کیف پول (string، مقدار: "active")

  • main_currency: ارز اصلی کیف پول (string، مثال: "IRR")

  • is_default: آیا کیف پول پیش‌فرض است (boolean)

  • created_at: تاریخ ایجاد کیف پول (ISO 8601 datetime)

  • updated_at: تاریخ آخرین به‌روزرسانی کیف پول (ISO 8601 datetime)

  • is_deleted: آیا کیف پول حذف شده (boolean)

  • meta_data: اطلاعات اضافی کیف پول (object | null)

موجودی ارزی (balance)

کیف پول از چندین ارز پشتیبانی می‌کند. هر ارز شامل اطلاعات زیر است:

ساختار هر ارز

  • currency: کد ارز (string، مثال: "IRR", "USD")

  • total: موجودی کل (string decimal)

  • held: مبلغ قفل شده (string decimal)

  • available: موجودی قابل استفاده (string decimal، برابر با: total - held)

آمار ارزی (stats)

آمار ارزش موجودی در واحدهای مختلف: - IRR: ارزش به ریال ایران (string decimal)

  • USD: ارزش به دلار آمریکا (string decimal)

  • EUR: ارزش به یورو (string decimal)

اطلاعات ارز (meta_data)

  • name: نام ارز به زبان‌های مختلف (object)

  • fa: نام فارسی (string)

  • en: نام انگلیسی (string)

  • symbol: نماد ارز (string)

  • precision: تعداد رقم اعشار (integer)

  • icon: آدرس آیکون ارز (string URL)

  • is_crypto: آیا ارز دیجیتال است (boolean)

  • color: رنگ نمایش ارز (string hex)

  • unit_value_irr: ارزش واحد به ریال (integer)

آمار ارزش (value_stats)

ارزش موجودی در واحدهای مختلف:

  • IRR: ارزش کل به ریال (string decimal)

  • USD: ارزش کل به دلار (string decimal)

  • EUR: ارزش کل به یورو (string decimal)

ویژگی‌های خاص (properties)
  • ویژگی‌های اضافی مخصوص ارز (object | null، اختیاری)

اندپوینت‌ها

1. List Wallets (لیست کیف پول‌های کاربر)

GET /api/accounting/v1/wallets?user_id=$user_id

توضیحات: - دریافت لیست کیف پول‌های کاربر user_id

  • فقط کیف پول‌های خود کاربر نمایش داده می‌شود

پارامترهای Query: - offset (integer, optional, default: 0)

  • limit (integer, optional, default: 10, max: 100)

  • user_id (strin): Id of target user

نمونه موفق

درخواست: 

curl -X GET "$BASE_URL/api/accounting/v1/wallets?\
user_id=user_id&\
offset=0&\
limit=10" \
  -H "Authorization: Bearer <access_token>"

پاسخ (200 OK): 

{
  "heads": {
    "uid": {
      "en": "Uid"
    },
    "created_at": {
      "en": "Created At"
    },
    "updated_at": {
      "en": "Updated At"
    },
    "is_deleted": {
      "en": "Is Deleted"
    },
    "meta_data": {
      "en": "Meta Data"
    },
    "user_id": {
      "en": "User Id"
    },
    "tenant_id": {
      "en": "Tenant Id"
    },
    "wallet_purpose": {
      "en": "Wallet Purpose"
    },
    "owner_type": {
      "en": "Owner Type"
    },
    "balance_type": {
      "en": "Balance Type"
    },
    "status": {
      "en": "Status"
    },
    "main_currency": {
      "en": "Main Currency"
    },
    "is_default": {
      "en": "Is Default"
    },
    "balance": {
      "en": "Balance"
    }
  },
  "items": [
    {
      "uid": "01998a00-329e-7352-a857-349ca796d4be",
      "created_at": "2025-09-27T07:08:12.830000",
      "updated_at": "2025-09-27T07:08:12.830000",
      "is_deleted": false,
      "meta_data": null,
      "user_id": "0197f464-46e0-7392-a54f-b08f07be6926",
      "tenant_id": "0197f464-46c8-72a1-8b23-0819b8622a0c",
      "wallet_purpose": "regular",
      "owner_type": "user",
      "balance_type": "positive",
      "status": "active",
      "main_currency": "IRR",
      "is_default": true,
      "balance": {
        "IRR": {
          "currency": "IRR",
          "total": "1078056999.995",
          "held": "106000000.0",
          "available": "972056999.995",
          "stats": {
            "IRR": "1078056999.995",
            "USD": "1197.841111105555555555555556",
            "EUR": "1078.056999995"
          },
          "meta_data": {
            "name": {
              "fa": "ریال",
              "en": "Iranian Rial"
            },
            "symbol": "IRR",
            "precision": 0,
            "icon": "https://flagcdn.com/w40/ir.png",
            "is_crypto": false,
            "color": "#1976d2",
            "unit_value_irr": 1
          },
          "value_stats": {
            "IRR": "1078056999.995",
            "USD": "1197.841111105555555555555556",
            "EUR": "1078.056999995"
          },
          "properties": null
        },
        "USD": {
          "currency": "USD",
          "total": "54467.74545455",
          "held": "1770.34545455",
          "available": "52697.40000000",
          "stats": {
            "IRR": "49020970909.09500000",
            "USD": "54467.74545455",
            "EUR": "49020.970909095"
          },
          "meta_data": {
            "name": {
              "fa": "دلار",
              "en": "Dollar"
            },
            "symbol": "USD",
            "precision": 2,
            "icon": "https://flagcdn.com/w40/us.png",
            "is_crypto": false,
            "color": "#f7931a",
            "unit_value_irr": 900000
          },
          "value_stats": {
            "IRR": "49020970909.09500000",
            "USD": "54467.74545455",
            "EUR": "49020.970909095"
          },
          "properties": null
        }
      }
    }
  ],
  "total": 2,
  "offset": 0,
  "limit": 10
}

2. Get Wallet (دریافت کیف پول خاص)

POST /api/accounting/v1/wallets/{wallet_id}

توضیحات:

  • دریافت اطلاعات یک کیف پول خاص

  • بررسی موجودی و وضعیت

پارامترهای Path: - wallet_id (string, required): شناسه کیف پول

دسترسی: مالک کیف پول

نمونه موفق

درخواست: 

curl -X POST "$BASE_URL/api/accounting/v1/wallets/wallet_456def" \
  -H "Authorization: Bearer <access_token>"

پاسخ (200 OK): 

{
  "uid": "01998a00-329e-7352-a857-349ca796d4be",
  "created_at": "2025-09-27T07:08:12.830000",
  "updated_at": "2025-09-27T07:08:12.830000",
  "is_deleted": false,
  "meta_data": null,
  "user_id": "0197f464-46e0-7392-a54f-b08f07be6926",
  "tenant_id": "0197f464-46c8-72a1-8b23-0819b8622a0c",
  "wallet_purpose": "regular",
  "owner_type": "user",
  "balance_type": "positive",
  "status": "active",
  "main_currency": "IRR",
  "is_default": true,
  "balance": {
    "IRR": {
      "currency": "IRR",
      "total": "1078056999.995",
      "held": "106000000.0",
      "available": "972056999.995",
      "stats": {
        "IRR": "1078056999.995",
        "USD": "1197.841111105555555555555556",
        "EUR": "1078.056999995"
      },
      "meta_data": {
        "name": {
          "fa": "ریال",
          "en": "Iranian Rial"
        },
        "symbol": "IRR",
        "precision": 0,
        "icon": "https://flagcdn.com/w40/ir.png",
        "is_crypto": false,
        "color": "#1976d2",
        "unit_value_irr": 1
      },
      "value_stats": {
        "IRR": "1078056999.995",
        "USD": "1197.841111105555555555555556",
        "EUR": "1078.056999995"
      },
      "properties": null
    },
    "USD": {
      "currency": "USD",
      "total": "54467.74545455",
      "held": "1770.34545455",
      "available": "52697.40000000",
      "stats": {
        "IRR": "49020970909.09500000",
        "USD": "54467.74545455",
        "EUR": "49020.970909095"
      },
      "meta_data": {
        "name": {
          "fa": "دلار",
          "en": "Dollar"
        },
        "symbol": "USD",
        "precision": 2,
        "icon": "https://flagcdn.com/w40/us.png",
        "is_crypto": false,
        "color": "#f7931a",
        "unit_value_irr": 900000
      },
      "value_stats": {
        "IRR": "49020970909.09500000",
        "USD": "54467.74545455",
        "EUR": "49020.970909095"
      },
      "properties": null
    }
  }
}

نمونه ناموفق 1: کیف پول یافت نشد

درخواست: 

curl -X POST "{{ API_BASE_URL }}/api/accounting/v1/wallets/wallet_999" \
  -H "Authorization: Bearer <access_token>"

پاسخ (404 Not Found): 

{
  "error": "not_found",
  "detail": "Wallet not found"
}

3. Get Wallet Holds (لیست holdهای کیف پول)

GEt /api/accounting/v1/wallets/{wallet_id}/holds

نمونه موفق

درخواست: 

curl "$BASE_URL/api/accounting/v1/wallets/wallet_123/holds" \
  -H "Authorization: Bearer <access_token>"

پاسخ (200 OK): 

{
  "uid": "019b6088-c2f5-7527-95ff-45f48a63a862",
  "created_at": "2025-12-27T15:58:54.197000",
  "updated_at": "2025-12-27T15:58:55.067000",
  "is_deleted": false,
  "meta_data": null,
  "user_id": "test_exchange_seller_user",
  "tenant_id": "0197f464-46c8-72a1-8b23-0819b8622a0c",
  "currency": "USD",
  "amount": "100",
  "expires_at": null,
  "status": "released",
  "description": null,
  "wallet_id": "019b6088-be9b-73cf-9719-c0cb7b868a7d"
}

توضیحات:

  • مشاهده موجودی‌های قفل شده (hold)

  • نمایش سفارشات فعال

پارامترهای Path:

  • wallet_id (string, required)

پارامترهای Query:

  • offset (integer, optional, default: 0)

  • limit (integer, optional, default: 10, max: 100)

4. Get Wallet Transactions (لیست تراکنش‌ها)

POST /api/accounting/v1/wallets/{wallet_id}/transactions

توضیحات:

  • تاریخچه کامل تراکنش‌های کیف پول

  • شامل واریز، برداشت، معاملات

پارامترهای Path:

  • wallet_id (string, required)

پارامترهای Query:

  • offset (integer, optional, default: 0)

  • limit (integer, optional, default: 10, max: 100)

  • created_at_from (string, optional): ISO 8601

  • created_at_to (string, optional): ISO 8601

دسترسی: مالک کیف پول

نمونه موفق

درخواست: 

curl -X POST "{{ API_BASE_URL }}/api/accounting/v1/wallets/wallet_456def/transactions?\
type=deposit&\
offset=0&\
limit=10" \
  -H "Authorization: Bearer <access_token>"

پاسخ (200 OK): 

{
  "heads": {...},
  "items": [
    {
      "uid": "019b6088-d942-74f4-9c78-a8e82e98e119",
      "created_at": "2025-12-27T15:58:59.981688",
      "updated_at": "2025-12-27T15:58:59.981699",
      "is_deleted": false,
      "meta_data": {},
      "user_id": "0197f464-46c8-72a1-8b23-0819b8622a0c",
      "tenant_id": "0197f464-46c8-72a1-8b23-0819b8622a0c",
      "proposal_id": "019b6088-d807-7ba6-a457-f27c3d90c8b3",
      "wallet_id": "019976a8-d574-7585-a848-e3b9aa0c8160",
      "amount": "8.000E+7",
      "currency": "IRR",
      "balance": "-9.9786600E+11",
      "description": null,
      "note": null,
      "tx_sig": "4f7c0655d61cf9b87e1faf631e6a29ec5ccdcf62460ebe44183a24920f085127",
      "chain_sig": "d26bd93be8a337626c73d241f951e82059264f4b8522b47c72e8334cd6a39756"
    }
  ],
  "total": 50,
  "offset": 0,
  "limit": 10
}

5. Deposit (واریز)

⚠️ !!!!!بعدا تغییر خواهد کرد!!!!!

POST /api/accounting/v1/wallets/{wallet_id}/deposit

توضیحات: - واریز وجه به کیف پول

  • ایجاد تراکنش واریز

  • به‌روزرسانی موجودی

پارامترهای Path:

  • wallet_id (string, required)

بدنه درخواست: 

{
  "amount": 0,
  "currency": "IRR",
  "treasury_wallet_id": "string"
}

نمونه موفق

درخواست: 

curl -X POST "$BASE_URL/api/accounting/v1/wallets/wallet_456def/deposit" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "100000000",
    "currency": "IRR",
    "treasury_wallet_id": "wallet_treasury"
  }'

پاسخ (201 Created): 

{
  "uid": "01998a00-329e-7352-a857-349ca796d4be",
  "created_at": "2025-09-27T07:08:12.830000",
  "updated_at": "2025-09-27T07:08:12.830000",
  "is_deleted": false,
  "meta_data": null,
  "user_id": "0197f464-46e0-7392-a54f-b08f07be6926",
  "tenant_id": "0197f464-46c8-72a1-8b23-0819b8622a0c",
  "wallet_purpose": "regular",
  "owner_type": "user",
  "balance_type": "positive",
  "status": "active",
  "main_currency": "IRR",
  "is_default": true,
  "balance": {
    "IRR": {
      "currency": "IRR",
      "total": "1078066999.995",
      "held": "106000000.0",
      "available": "972066999.995",
      "stats": {
        "IRR": "1078066999.995",
        "USD": "1197.852222216666666666666667",
        "EUR": "1078.066999995"
      },
      "meta_data": {
        "name": {
          "fa": "ریال",
          "en": "Iranian Rial"
        },
        "symbol": "IRR",
        "precision": 0,
        "icon": "https://flagcdn.com/w40/ir.png",
        "is_crypto": false,
        "color": "#1976d2",
        "unit_value_irr": 1
      },
      "value_stats": {
        "IRR": "1078066999.995",
        "USD": "1197.852222216666666666666667",
        "EUR": "1078.066999995"
      },
      "properties": null
    },
    "USD": {
      "currency": "USD",
      "total": "54467.74545455",
      "held": "1770.34545455",
      "available": "52697.40000000",
      "stats": {
        "IRR": "49020970909.09500000",
        "USD": "54467.74545455",
        "EUR": "49020.970909095"
      },
      "meta_data": {
        "name": {
          "fa": "دلار",
          "en": "Dollar"
        },
        "symbol": "USD",
        "precision": 2,
        "icon": "https://flagcdn.com/w40/us.png",
        "is_crypto": false,
        "color": "#f7931a",
        "unit_value_irr": 900000
      },
      "value_stats": {
        "IRR": "49020970909.09500000",
        "USD": "54467.74545455",
        "EUR": "49020.970909095"
      },
      "properties": null
    }
  }
}

6. Withdraw (برداشت)

!!!! در حال توسعه !!!!

POST /api/accounting/v1/wallets/{wallet_id}/withdraw

توضیحات: - درخواست برداشت از کیف پول

  • کاهش موجودی و ایجاد تراکنش برداشت

پارامترهای Path: - wallet_id (string, required)

بدنه درخواست: 

{
  "amount": 1000,
  "currency": "IRR",
  "treasury_wallet_id": "string",
  "meta_data": {}
}

فیلدهای اجباری: - amount: مبلغ

  • currency: ارز

  • treasury_wallet_id: مقصد (bank, card, wallet)

نمونه موفق

درخواست: 

curl -X POST "{{ API_BASE_URL }}/api/accounting/v1/wallets/wallet_456def/withdraw" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000,
    "currency": "IRR",
    "treasury_wallet_id": "string",
    "meta_data": {}
  }'

پاسخ (201 Created): 

{
  "uid": "01998a00-329e-7352-a857-349ca796d4be",
  "created_at": "2025-09-27T07:08:12.830000",
  "updated_at": "2025-09-27T07:08:12.830000",
  "is_deleted": false,
  "meta_data": null,
  "user_id": "0197f464-46e0-7392-a54f-b08f07be6926",
  "tenant_id": "0197f464-46c8-72a1-8b23-0819b8622a0c",
  "wallet_purpose": "regular",
  "owner_type": "user",
  "balance_type": "positive",
  "status": "active",
  "main_currency": "IRR",
  "is_default": true,
  "balance": {
    "IRR": {
      "currency": "IRR",
      "total": "1078065999.995",
      "held": "106000000.0",
      "available": "972065999.995",
      "stats": {
        "IRR": "1078065999.995",
        "USD": "1197.851111105555555555555556",
        "EUR": "1078.065999995"
      },
      "meta_data": {
        "name": {
          "fa": "ریال",
          "en": "Iranian Rial"
        },
        "symbol": "IRR",
        "precision": 0,
        "icon": "https://flagcdn.com/w40/ir.png",
        "is_crypto": false,
        "color": "#1976d2",
        "unit_value_irr": 1
      },
      "value_stats": {
        "IRR": "1078065999.995",
        "USD": "1197.851111105555555555555556",
        "EUR": "1078.065999995"
      },
      "properties": null
    },
    "USD": {
      "currency": "USD",
      "total": "54467.74545455",
      "held": "1770.34545455",
      "available": "52697.40000000",
      "stats": {
        "IRR": "49020970909.09500000",
        "USD": "54467.74545455",
        "EUR": "49020.970909095"
      },
      "meta_data": {
        "name": {
          "fa": "دلار",
          "en": "Dollar"
        },
        "symbol": "USD",
        "precision": 2,
        "icon": "https://flagcdn.com/w40/us.png",
        "is_crypto": false,
        "color": "#f7931a",
        "unit_value_irr": 900000
      },
      "value_stats": {
        "IRR": "49020970909.09500000",
        "USD": "54467.74545455",
        "EUR": "49020.970909095"
      },
      "properties": null
    }
  }
}

نمونه ناموفق 1: موجودی ناکافی

درخواست: 

curl -X POST "{{ API_BASE_URL }}/api/accounting/v1/wallets/wallet_456def/withdraw" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "200000000",
    "currency": "IRR",
    "destination": "bank",
    "destination_address": "IR123456789012345678901234"
  }'

پاسخ (400 Unprocessable Entity): 

{
  "error": "proposal_failed",
  "detail": "...."
}

7. Get Withdrawals (لیست برداشت‌ها)

!!!! در حال توسعه !!!!

POST /api/accounting/v1/wallets/{wallet_id}/withdrawals

توضیحات: - تاریخچه برداشت‌های کیف پول

پارامترهای Path: - wallet_id (string, required)

پارامترهای Query: - offset (integer, optional, default: 0)

  • limit (integer, optional, default: 10, max: 100)

  • created_at_from (string, optional): ISO 8601

  • created_at_to (string, optional): ISO 8601

چک‌لیست استفاده

  1. ✅ مشاهده موجودی: POST /wallets/{id}

  2. ✅ واریز وجه: POST /wallets/{id}/deposit

  3. ✅ برداشت وجه: POST /wallets/{id}/withdraw

  4. ✅ تاریخچه تراکنش: POST /wallets/{id}/transactions

نکات امنیتی

  1. همیشه موجودی کافی بررسی شود

  2. موجودی در حال استفاده (hold) جداگانه مدیریت شود

  3. تراکنش‌ها لاگ کامل داشته باشند

  4. برداشت نیاز به تایید دو مرحله‌ای داشته باشد

  5. محدودیت‌های روزانه اعمال شود

خلاصه

اندپوینت متد توضیحات
/wallets GET لیست کیف پول‌ها
/wallets/{id} POST دریافت کیف پول
/wallets/{id}/holds POST لیست holdها
/wallets/{id}/transactions POST لیست تراکنش‌ها
/wallets/{id}/deposit POST واریز
/wallets/{id}/withdraw POST برداشت

بعدی: مطالعه Market Symbols API