Market Symbols API - رفرنس کامل

توضیحات کلی

این API برای مدیریت نمادهای معاملاتی (Trading Pairs) استفاده می‌شود. نمادها مشخص می‌کنند که کدام دارایی‌ها قابل معامله هستند.

ساختار داده Symbol

{
  "uid": "01995196-ef5e-7239-87b9-e93d61004317",
  "created_at": "2025-09-16T08:14:53.306000",
  "updated_at": "2025-09-16T08:14:53.306000",
  "is_deleted": false,
  "meta_data": null,
  "user_id": "admin",
  "symbol": "EUR-IRR",
  "price_precision": 0,
  "quantity_precision": -2,
  "min_order_quantity": "100",
  "tick_size": "100",
  "description": "Euro to Iranian Rial",
  "is_active": true,
  "properties": {
    "EUR": {
      "name": {
        "fa": "یورو",
        "en": "Euro"
      },
      "symbol": "EUR",
      "precision": 2,
      "icon": "https://flagcdn.com/w40/eu.png",
      "is_crypto": false,
      "color": "#26a17b",
      "unit_value_irr": 1000000
    },
    "IRR": {
      "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
    }
  }
}

فیلدها

• uid: شناسه منحصر به فرد نماد
• user_id: کاربر ایجاد کننده
• symbol: نام نماد (مثلاً BTC-IRR)
• price_precision: دقت قیمت (تعداد اعشار)
• quantity_precision: دقت حجم (تعداد اعشار)
• min_order_quantity: حداقل حجم سفارش
• tick_size: اندازه تیک (ضریب قیمت)
• daily_fluctuation_price_limit_percent: محدودیت نوسان روزانه (%)
• description: توضیحات
• is_active: وضعیت فعال/غیرفعال
• properties: ویژگی‌های نماد (base, quote)
• created_at: تاریخ ایجاد
• updated_at: تاریخ به‌روزرسانی

اندپوینت‌ها

1. List Symbols (لیست نمادها)

GET /api/exchange/v1/symbols

توضیحات: - دریافت لیست تمام نمادهای معاملاتی فعال - شامل فیلترهای مختلف

پارامترهای Query: - offset (integer, optional, default: 0) - limit (integer, optional, default: 10, max: 100) - is_active (boolean, optional): true, false - search (string, optional): جستجو در نام نماد - created_at_from (string, optional): ISO 8601 - created_at_to (string, optional): ISO 8601

دسترسی: همه کاربران

نمونه موفق

درخواست:

curl -X GET "{{ API_BASE_URL }}/api/exchange/v1/symbols?\
is_active=true&\
offset=0&\
limit=10" \
  -H "Authorization: Bearer <user_token>"

پاسخ (200 OK):

{
  "heads": {
    "uid": "شناسه",
    "symbol": "نماد",
    "price_precision": "دقت قیمت",
    "quantity_precision": "دقت حجم",
    "min_order_quantity": "حداقل حجم",
    "is_active": "فعال"
  },
  "items": [
    {
      "uid": "sym_123",
      "user_id": "user_admin",
      "symbol": "BTC-IRR",
      "price_precision": 2,
      "quantity_precision": 8,
      "min_order_quantity": "0.0001",
      "tick_size": "1000",
      "daily_fluctuation_price_limit_percent": "5",
      "is_active": true,
      "properties": {
        "base": "BTC",
        "quote": "IRR"
      }
    },
    {
      "uid": "sym_456",
      "user_id": "user_admin",
      "symbol": "ETH-IRR",
      "price_precision": 2,
      "quantity_precision": 8,
      "min_order_quantity": "0.01",
      "tick_size": "1000",
      "daily_fluctuation_price_limit_percent": "5",
      "is_active": true,
      "properties": {
        "base": "ETH",
        "quote": "IRR"
      }
    },
    {
      "uid": "sym_789",
      "user_id": "user_admin",
      "symbol": "USDT-IRR",
      "price_precision": 2,
      "quantity_precision": 2,
      "min_order_quantity": "1",
      "tick_size": "100",
      "daily_fluctuation_price_limit_percent": "1",
      "is_active": true,
      "properties": {
        "base": "USDT",
        "quote": "IRR"
      }
    }
  ],
  "total": 3,
  "offset": 0,
  "limit": 10
}

نمونه ناموفق 1: عدم احراز هویت

درخواست:

curl -X GET "{{ API_BASE_URL }}/api/exchange/v1/symbols"

پاسخ (401 Unauthorized):

{
  "detail": "Not authenticated"
}

نمونه ناموفق 2: لیست خالی

درخواست:

curl -X GET "{{ API_BASE_URL }}/api/exchange/v1/symbols?is_active=false" \
  -H "Authorization: Bearer <user_token>"

پاسخ (200 OK):

{
  "heads": {
    "uid": "شناسه",
    "symbol": "نماد",
    "is_active": "فعال"
  },
  "items": [],
  "total": 0,
  "offset": 0,
  "limit": 10
}

---

2. Create Symbol (ایجاد نماد)

POST /api/exchange/v1/symbols

توضیحات: - ایجاد نماد معاملاتی جدید - تنظیم پارامترهای معاملاتی

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

{
  "symbol": "string",
  "price_precision": "integer",
  "quantity_precision": "integer",
  "min_order_quantity": "string",
  "tick_size": "string",
  "daily_fluctuation_price_limit_percent": "string",
  "description": "string"
}

فیلدهای اجباری: - symbol - price_precision - quantity_precision

دسترسی: admin

نمونه موفق

درخواست:

curl -X POST "{{ API_BASE_URL }}/api/exchange/v1/symbols" \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "SOL-IRR",
    "price_precision": 2,
    "quantity_precision": 6,
    "min_order_quantity": "0.1",
    "tick_size": "1000",
    "daily_fluctuation_price_limit_percent": "10",
    "description": "Solana to IRR"
  }'

پاسخ (201 Created):

{
  "uid": "sym_101",
  "user_id": "user_admin",
  "symbol": "SOL-IRR",
  "price_precision": 2,
  "quantity_precision": 6,
  "min_order_quantity": "0.1",
  "tick_size": "1000",
  "daily_fluctuation_price_limit_percent": "10",
  "description": "Solana to IRR",
  "is_active": true,
  "properties": {
    "base": "SOL",
    "quote": "IRR",
    "base_precision": 6,
    "quote_precision": 2
  },
  "created_at": "2025-12-30T14:00:00Z",
  "updated_at": "2025-12-30T14:00:00Z"
}

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

درخواست:

curl -X POST "{{ API_BASE_URL }}/api/exchange/v1/symbols" \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "BTC-IRR",  # از قبل وجود دارد
    "price_precision": 2,
    "quantity_precision": 8
  }'

پاسخ (409 Conflict):

{
  "detail": "Symbol already exists"
}

نمونه ناموفق 2: داده ناقص

درخواست:

curl -X POST "{{ API_BASE_URL }}/api/exchange/v1/symbols" \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "NEW-IRR",
    "price_precision": 2
  }'

پاسخ (422 Unprocessable Entity):

{
  "detail": [
    {
      "loc": ["body", "quantity_precision"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

---

3. Retrieve Symbol (دریافت نماد خاص)

POST /api/exchange/v1/symbols/{uid}

توضیحات: - دریافت اطلاعات کامل یک نماد

پارامترهای Path: - uid (string, required): شناسه نماد

دسترسی: همه کاربران

نمونه موفق

درخواست:

curl -X POST "{{ API_BASE_URL }}/api/exchange/v1/symbols/sym_123" \
  -H "Authorization: Bearer <user_token>"

پاسخ (200 OK):

{
  "uid": "sym_123",
  "user_id": "user_admin",
  "symbol": "BTC-IRR",
  "price_precision": 2,
  "quantity_precision": 8,
  "min_order_quantity": "0.0001",
  "tick_size": "1000",
  "daily_fluctuation_price_limit_percent": "5",
  "description": "Bitcoin to IRR",
  "is_active": true,
  "properties": {
    "base": "BTC",
    "quote": "IRR",
    "base_precision": 8,
    "quote_precision": 2
  },
  "created_at": "2025-12-30T10:00:00Z",
  "updated_at": "2025-12-30T10:00:00Z"
}

نمونه ناموفق: نماد یافت نشد

درخواست:

curl -X POST "{{ API_BASE_URL }}/api/exchange/v1/symbols/sym_999" \
  -H "Authorization: Bearer <user_token>"

پاسخ (404 Not Found):

{
  "detail": "Symbol not found"
}

---

4. Update Symbol (به‌روزرسانی نماد)

PATCH /api/exchange/v1/symbols/{uid}

توضیحات: - به‌روزرسانی پارامترهای نماد - می‌تواند فعال/غیرفعال شود

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

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

{
  "price_precision": "integer (اختیاری)",
  "quantity_precision": "integer (اختیاری)",
  "min_order_quantity": "string (اختیاری)",
  "tick_size": "string (اختیاری)",
  "daily_fluctuation_price_limit_percent": "string (اختیاری)",
  "is_active": "boolean (اختیاری)",
  "description": "string (اختیاری)"
}

دسترسی: admin

نمونه موفق

درخواست:

curl -X PATCH "{{ API_BASE_URL }}/api/exchange/v1/symbols/sym_123" \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "is_active": false,
    "description": "Bitcoin to IRR - Paused"
  }'

پاسخ (200 OK):

{
  "uid": "sym_123",
  "user_id": "user_admin",
  "symbol": "BTC-IRR",
  "price_precision": 2,
  "quantity_precision": 8,
  "min_order_quantity": "0.0001",
  "tick_size": "1000",
  "daily_fluctuation_price_limit_percent": "5",
  "description": "Bitcoin to IRR - Paused",
  "is_active": false,
  "properties": {
    "base": "BTC",
    "quote": "IRR"
  },
  "created_at": "2025-12-30T10:00:00Z",
  "updated_at": "2025-12-30T14:30:00Z"
}

نمونه ناموفق: نماد یافت نشد

درخواست:

curl -X PATCH "{{ API_BASE_URL }}/api/exchange/v1/symbols/sym_999" \
  -H "Authorization: Bearer <admin_token>" \
  -H "Content-Type: application/json" \
  -d '{"is_active": false}'

پاسخ (404 Not Found):

{
  "detail": "Symbol not found"
}

---

5. Delete Symbol (حذف نماد)

DELETE /api/exchange/v1/symbols/{uid}

توضیحات: - حذف نرم نماد (soft delete) - تغییر is_active به false

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

دسترسی: admin

نمونه موفق

درخواست:

curl -X DELETE "{{ API_BASE_URL }}/api/exchange/v1/symbols/sym_123" \
  -H "Authorization: Bearer <admin_token>"

پاسخ (204 No Content):

بدون بدنه پاسخ

نمونه ناموفق: نماد یافت نشد

درخواست:

curl -X DELETE "{{ API_BASE_URL }}/api/exchange/v1/symbols/sym_999" \
  -H "Authorization: Bearer <admin_token>"

پاسخ (404 Not Found):

{
  "detail": "Symbol not found"
}

---

پارامترهای معاملاتی

1. Price Precision (دقت قیمت)

مثال:

price_precision = 2
قیمت: 100,000,000.00 IRR

کاربرد: - تعیین تعداد اعشار برای قیمت - مثال: 2 یعنی 2 رقم اعشار

2. Quantity Precision (دقت حجم)

مثال:

quantity_precision = 8
حجم: 0.12345678 BTC

کاربرد: - تعیین تعداد اعشار برای حجم - مثال: 8 یعنی 8 رقم اعشار

3. Min Order Quantity (حداقل حجم)

مثال:

min_order_quantity = "0.0001"

کاربرد: - جلوگیری از سفارشات بی‌ارزش - حداقل حجم مجاز

4. Tick Size (اندازه تیک)

مثال:

tick_size = "1000"

کاربرد: - قیمت‌ها باید مضربی از tick_size باشند - مثال: 100,000,000 ✅ / 100,000,001 ❌

5. Daily Fluctuation Limit (محدودیت نوسان)

مثال:

daily_fluctuation_price_limit_percent = "5"

کاربرد: - حداکثر نوسان قیمت در یک روز - جلوگیری از دستکاری بازار

مثال‌های کامل

نمونه 1: نماد ارز دیجیتال

{
  "symbol": "BTC-IRR",
  "price_precision": 2,
  "quantity_precision": 8,
  "min_order_quantity": "0.0001",
  "tick_size": "1000",
  "daily_fluctuation_price_limit_percent": "5",
  "description": "Bitcoin to Iranian Rial"
}

توضیح: - قیمت: 1,000,000,000.00 IRR (2 رقم اعشار) - حجم: 0.12345678 BTC (8 رقم اعشار) - حداقل: 0.0001 BTC - قیمت‌ها: 1,000,000,000, 1,000,001,000, ... (ضریب 1000) - نوسان: حداکثر ±5%

نمونه 2: نماد استیبل کوین

{
  "symbol": "USDT-IRR",
  "price_precision": 2,
  "quantity_precision": 2,
  "min_order_quantity": "1",
  "tick_size": "100",
  "daily_fluctuation_price_limit_percent": "1",
  "description": "USDT to Iranian Rial"
}

توضیح: - قیمت: 50,000.00 IRR (2 رقم اعشار) - حجم: 100.50 USDT (2 رقم اعشار) - حداقل: 1 USDT - قیمت‌ها: 50,000, 50,100, 50,200, ... (ضریب 100) - نوسان: حداکثر ±1%

نمونه 3: نماد آلت کوین

{
  "symbol": "ETH-IRR",
  "price_precision": 2,
  "quantity_precision": 6,
  "min_order_quantity": "0.01",
  "tick_size": "1000",
  "daily_fluctuation_price_limit_percent": "10",
  "description": "Ethereum to Iranian Rial"
}

توضیح: - قیمت: 35,000,000.00 IRR (2 رقم اعشار) - حجم: 0.123456 ETH (6 رقم اعشار) - حداقل: 0.01 ETH - قیمت‌ها: 35,000,000, 35,001,000, ... (ضریب 1000) - نوسان: حداکثر ±10%

چک‌لیست ایجاد نماد

قبل از ایجاد نماد: - [ ] نام نماد استاندارد (BASE-QUOTE) - [ ] دقت قیمت مناسب - [ ] دقت حجم مناسب - [ ] حداقل حجم معقول - [ ] اندازه تیک منطقی - [ ] محدودیت نوسان مناسب - [ ] توضیحات کامل

نکات امنیتی

1. غیرفعال کردن نماد
2. قبل از تغییرات بزرگ
3. هنگام نگهداری سیستم

4. در صورت مشکل امنیتی

5. محدودیت دسترسی

6. فقط ادمین می‌تواند ایجاد/ویرایش کند

7. کاربران فقط می‌توانند ببینند

8. لاگ‌گیری

9. تمام تغییرات ثبت شود
10. تغییرات قیمت و حجم حتماً لاگ شود

خلاصه

اندپوینت	متد	توضیحات	دسترسی
/symbols	GET	لیست نمادها	همه

---

بعدی: مطالعه Sessions API