Orders API - رفرنس کامل¶

توضیحات کلی¶

این API برای مدیریت سفارشات معاملاتی استفاده می‌شود. سفارشات خرید و فروش در دفتر سفارشات قرار می‌گیرند و توسط Matching Engine پردازش می‌شوند.

ساختار داده Order¶

{
  "uid": "ord_123abc",
  "user_id": "user_123",
  "wallet_id": "wallet_456",
  "symbol": "BTC-IRR",
  "side": "buy",
  "type": "limit",
  "price": "1000000000",
  "quantity": "0.5",
  "filled": "0.2",
  "time_in_force": "good-till-canceled",
  "status": "partial",
  "stop_price": null,
  "expire_at": null,
  "rejection_reasons": [],
  "broker_id": null,
  "session_id": "sess_123",
  "hold_id": "hold_789",
  "trades": [
    {
      "trade_id": "trade_456",
      "quantity": "0.2",
      "price": "999000000",
      "created_at": "2025-12-30T10:05:00Z",
      "status": "executed"
    }
  ],
  "created_at": "2025-12-30T10:00:00Z",
  "updated_at": "2025-12-30T10:05:00Z"
}

فیلدها¶

uid: شناسه منحصر به فرد سفارش
user_id: شناسه کاربر
wallet_id: شناسه کیف پول
symbol: نماد معاملاتی
side: جهت (buy, sell)
type: نوع سفارش (limit, market, stop-limit, stop-market)
price: قیمت (برای سفارشات لیمیت)
quantity: حجم کل
filled: حجم پر شده
time_in_force: زمان اعتبار (good-till-canceled, fill-or-kill, immediate-or-cancel, all-or-none)
status: وضعیت (new, queued, rejected, active, partial, filled, cancelled, expired)
stop_price: قیمت فعال‌سازی (برای سفارشات شرطی)
expire_at: زمان انقضا
rejection_reasons: دلایل رد
broker_id: شناسه بروکر (اختیاری)
session_id: شناسه جلسه معاملاتی
hold_id: شناسه hold
trades: لیست معاملات انجام شده
created_at: تاریخ ایجاد
updated_at: تاریخ به‌روزرسانی

اندپوینت‌ها¶

1. List Orders (لیست سفارشات)¶

GET /api/exchange/v1/orders

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

پارامترهای Query: - offset (integer, optional, default: 0) - limit (integer, optional, default: 10, max: 100) - user_id (string, optional): فیلتر بر اساس کاربر - symbol (string, optional): فیلتر بر اساس نماد - side (string, optional): buy یا sell - status (string, optional): new, queued, rejected, active, partial, filled, cancelled, expired - created_at_from (string, optional): ISO 8601 - created_at_to (string, optional): ISO 8601

دسترسی: کاربر خودش یا admin

نمونه موفق¶

درخواست:

curl -X GET "{{ API_BASE_URL }}/api/exchange/v1/orders?\
symbol=BTC-IRR&\
status=active&\
offset=0&\
limit=10" \
  -H "Authorization: Bearer <user_token>"

پاسخ (200 OK):

href="#__codelineno-2-1">{ "heads": { "uid": "شناسه", "symbol": "نماد", "side": "جهت", "type": "نوع", "price": "قیمت", "quantity": "حجم کل", "filled": "حجم پر شده", "status": "وضعیت" }, "items": [ { "uid": "ord_123", "user_id": "user_123", "wallet_id": "wallet_456", "symbol": "BTC-IRR", "side": "buy", "type": "limit", "price": "1000000000", "quantity": "0.5", "filled": "0.2", "time_in_force": "good-till-canceled", "status": "partial", "created_at": "2025-12-30T10:00:00Z" }, { "uid": "ord_456", "user_id": "user_123", "wallet_id": "wallet_456", "symbol": "BTC-IRR", "side": "sell", "type": "limit", "price": "1050000000", "quantity": "0.3", "filled": "0.0", "time_in_force": "good-till-canceled", "status": "active", "created_at": "2025-12-30T11:00:00Z" } ], "total": 25, "offset": 0, "limit": 10 }

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

درخواست:

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

پاسخ (401 Unauthorized):

{
  "detail": "Not authenticated"
}

نمونه ناموفق 2: دسترسی غیرمجاز¶

درخواست:

# کاربر A سعی می‌کند سفارشات کاربر B را ببیند
curl -X GET "{{ API_BASE_URL }}/api/exchange/v1/orders?user_id=user_456" \
  -H "Authorization: Bearer <user_123_token>"

پاسخ (403 Forbidden):

{
  "detail": "Access denied"
}

2. Create Order (ایجاد سفارش)¶

POST /api/exchange/v1/orders

توضیحات: - ایجاد سفارش جدید - بررسی موجودی و اعتبار - ارسال به Matching Engine

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

{
  "symbol": "string",
  "side": "string",
  "type": "string",
  "price": "string (اختیاری)",
  "quantity": "string",
  "time_in_force": "string (اختیاری)",
  "stop_price": "string (اختیاری)",
  "expire_at": "string (اختیاری)",
  "user_id": "string (اختیاری)",
  "wallet_id": "string (اختیاری)",
  "user_national_code": "string (اختیاری)"
}

فیلدهای اجباری: - symbol - side (buy/sell) - type (limit/market/stop-limit/stop-market) - quantity

فیلدهای اختیاری برای نوع‌ها: - limit: نیاز به price - market: نیازی به price ندارد - stop-limit: نیاز به stop_price و price - stop-market: نیاز به stop_price

دسترسی: کاربر خودش یا admin

نمونه موفق 1: سفارش لیمیت خرید¶

درخواست:

curl -X POST "{{ API_BASE_URL }}/api/exchange/v1/orders" \
  -H "Authorization: Bearer <user_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "BTC-IRR",
    "side": "buy",
    "type": "limit",
    "price": "1000000000",
    "quantity": "0.5",
    "time_in_force": "good-till-canceled"
  }'

پاسخ (201 Created):

{
  "uid": "ord_789xyz",
  "user_id": "user_123",
  "wallet_id": "wallet_456",
  "symbol": "BTC-IRR",
  "side": "buy",
  "type": "limit",
  "price": "1000000000",
  "quantity": "0.5",
  "filled": "0.0",
  "time_in_force": "good-till-canceled",
  "status": "active",
  "stop_price": null,
  "expire_at": null,
  "rejection_reasons": [],
  "broker_id": null,
  "session_id": "sess_123",
  "hold_id": "hold_789",
  "trades": [],
  "created_at": "2025-12-30T12:00:00Z",
  "updated_at": "2025-12-30T12:00:00Z"
}

نمونه موفق 2: سفارش مارکت فروش¶

درخواست:

curl -X POST "{{ API_BASE_URL }}/api/exchange/v1/orders" \
  -H "Authorization: Bearer <user_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "BTC-IRR",
    "side": "sell",
    "type": "market",
    "quantity": "0.2"
  }'

پاسخ (201 Created):

{
  "uid": "ord_790abc",
  "user_id": "user_123",
  "wallet_id": "wallet_456",
  "symbol": "BTC-IRR",
  "side": "sell",
  "type": "market",
  "price": null,
  "quantity": "0.2",
  "filled": "0.2",
  "time_in_force": "immediate-or-cancel",
  "status": "filled",
  "stop_price": null,
  "expire_at": null,
  "rejection_reasons": [],
  "broker_id": null,
  "session_id": "sess_123",
  "hold_id": "hold_790",
  "trades": [
    {
      "trade_id": "trade_791",
      "quantity": "0.2",
      "price": "999000000",
      "created_at": "2025-12-30T12:00:05Z",
      "status": "executed"
    }
  ],
  "created_at": "2025-12-30T12:00:00Z",
  "updated_at": "2025-12-30T12:00:05Z"
}

نمونه موفق 3: سفارش شرطی (Stop-Loss)¶

درخواست:

curl -X POST "{{ API_BASE_URL }}/api/exchange/v1/orders" \
  -H "Authorization: Bearer <user_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "BTC-IRR",
    "side": "sell",
    "type": "stop-limit",
    "stop_price": "950000000",
    "price": "940000000",
    "quantity": "0.5"
  }'

پاسخ (201 Created):

{
  "uid": "ord_791def",
  "user_id": "user_123",
  "wallet_id": "wallet_456",
  "symbol": "BTC-IRR",
  "side": "sell",
  "type": "stop-limit",
  "price": "940000000",
  "quantity": "0.5",
  "filled": "0.0",
  "time_in_force": "good-till-canceled",
  "status": "queued",
  "stop_price": "950000000",
  "expire_at": null,
  "rejection_reasons": [],
  "broker_id": null,
  "session_id": "sess_123",
  "hold_id": "hold_791",
  "trades": [],
  "created_at": "2025-12-30T12:00:00Z",
  "updated_at": "2025-12-30T12:00:00Z"
}

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

درخواست:

curl -X POST "{{ API_BASE_URL }}/api/exchange/v1/orders" \
  -H "Authorization: Bearer <user_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "BTC-IRR",
    "side": "buy",
    "type": "limit",
    "price": "1000000000",
    "quantity": "100"
  }'

پاسخ (422 Unprocessable Entity):

{
  "detail": [
    {
      "loc": ["body"],
      "msg": "insufficient balance",
      "type": "value_error"
    }
  ]
}

نمونه ناموفق 2: حجم کمتر از حداقل¶

درخواست:

curl -X POST "{{ API_BASE_URL }}/api/exchange/v1/orders" \
  -H "Authorization: Bearer <user_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "BTC-IRR",
    "side": "buy",
    "type": "limit",
    "price": "1000000000",
    "quantity": "0.00001"
  }'

پاسخ (422 Unprocessable Entity):

{
  "detail": [
    {
      "loc": ["body", "quantity"],
      "msg": "value is less than minimum",
      "type": "value_error.number.not_ge",
      "ctx": {"limit_value": 0.0001}
    }
  ]
}

نمونه ناموفق 3: نماد غیرفعال¶

درخواست:

curl -X POST "{{ API_BASE_URL }}/api/exchange/v1/orders" \
  -H "Authorization: Bearer <user_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "OLD-IRR",
    "side": "buy",
    "type": "limit",
    "price": "1000000000",
    "quantity": "0.5"
  }'

پاسخ (422 Unprocessable Entity):

{
  "detail": [
    {
      "loc": ["body", "symbol"],
      "msg": "symbol is not active",
      "type": "value_error"
    }
  ]
}

نمونه ناموفق 4: خارج از زمان جلسه¶

درخواست:

# زمان خارج از جلسه معاملاتی
curl -X POST "{{ API_BASE_URL }}/api/exchange/v1/orders" \
  -H "Authorization: Bearer <user_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "BTC-IRR",
    "side": "buy",
    "type": "limit",
    "price": "1000000000",
    "quantity": "0.5"
  }'

پاسخ (422 Unprocessable Entity):

{
  "detail": [
    {
      "loc": ["body"],
      "msg": "outside trading session",
      "type": "value_error"
    }
  ]
}

3. Retrieve Order (دریافت سفارش خاص)¶

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

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

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

دسترسی: مالک سفارش یا admin

نمونه موفق¶

درخواست:

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

پاسخ (200 OK):

{
  "uid": "ord_123",
  "user_id": "user_123",
  "wallet_id": "wallet_456",
  "symbol": "BTC-IRR",
  "side": "buy",
  "type": "limit",
  "price": "1000000000",
  "quantity": "0.5",
  "filled": "0.2",
  "time_in_force": "good-till-canceled",
  "status": "partial",
  "stop_price": null,
  "expire_at": null,
  "rejection_reasons": [],
  "broker_id": null,
  "session_id": "sess_123",
  "hold_id": "hold_789",
  "trades": [
    {
      "trade_id": "trade_456",
      "quantity": "0.2",
      "price": "999000000",
      "created_at": "2025-12-30T10:05:00Z",
      "status": "executed"
    }
  ],
  "created_at": "2025-12-30T10:00:00Z",
  "updated_at": "2025-12-30T10:05:00Z"
}

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

درخواست:

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

پاسخ (404 Not Found):

{
  "detail": "Order not found"
}

4. Cancel Order (لغو سفارش)¶

POST /api/exchange/v1/orders/{uid}/cancel

توضیحات: - لغو سفارش فعال یا جزئی - آزادسازی موجودی در حال استفاده

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

دسترسی: مالک سفارش یا admin

نمونه موفق¶

درخواست:

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

پاسخ (200 OK):

{
  "uid": "ord_123",
  "user_id": "user_123",
  "wallet_id": "wallet_456",
  "symbol": "BTC-IRR",
  "side": "buy",
  "type": "limit",
  "price": "1000000000",
  "quantity": "0.5",
  "filled": "0.2",
  "time_in_force": "good-till-canceled",
  "status": "cancelled",
  "stop_price": null,
  "expire_at": null,
  "rejection_reasons": [],
  "broker_id": null,
  "session_id": "sess_123",
  "hold_id": "hold_789",
  "trades": [
    {
      "trade_id": "trade_456",
      "quantity": "0.2",
      "price": "999000000",
      "created_at": "2025-12-30T10:05:00Z",
      "status": "executed"
    }
  ],
  "created_at": "2025-12-30T10:00:00Z",
  "updated_at": "2025-12-30T12:30:00Z"
}

نمونه ناموفق 1: سفارش یافت نشد¶

درخواست:

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

پاسخ (404 Not Found):

{
  "detail": "Order not found"
}

نمونه ناموفق 2: سفارش قابل لغو نیست¶

درخواست:

# سفارشی که قبلاً پر شده یا لغو شده
curl -X POST "{{ API_BASE_URL }}/api/exchange/v1/orders/ord_123/cancel" \
  -H "Authorization: Bearer <user_token>"

پاسخ (422 Unprocessable Entity):

{
  "detail": [
    {
      "loc": ["body"],
      "msg": "order cannot be cancelled",
      "type": "value_error"
    }
  ]
}

نمونه ناموفق 3: دسترسی غیرمجاز¶

درخواست:

# کاربر A سعی می‌کند سفارش کاربر B را لغو کند
curl -X POST "{{ API_BASE_URL }}/api/exchange/v1/orders/ord_456/cancel" \
  -H "Authorization: Bearer <user_123_token>"

پاسخ (403 Forbidden):

{
  "detail": "Access denied"
}

انواع سفارشات¶

1. سفارش لیمیت (Limit Order)¶

User: می‌خواهم 0.5 BTC با قیمت 100M بخرم

ویژگی‌ها: - قیمت مشخص - در دفتر سفارشات می‌ماند - منتظر جفت مناسب

استفاده: - کنترل قیمت دقیق - استراتژی‌های معاملاتی

2. سفارش مارکت (Market Order)¶

User: می‌خواهم 0.5 BTC با قیمت بازار بخرم

ویژگی‌ها: - اجرای فوری - قیمت تضمین نمی‌شود - از بهترین قیمت موجود

استفاده: - نیاز فوری - حجم کم

3. سفارش استاپ لیمیت (Stop-Limit)¶

User: اگر قیمت به 95M رسید، 0.5 BTC با قیمت 94M بفروش

ویژگی‌ها: - شرط فعال‌سازی (stop_price) - قیمت اجرا (price) - برای استاپ لاس

استفاده: - مدیریت ریسک - حفظ سود

4. سفارش استاپ مارکت (Stop-Market)¶

User: اگر قیمت به 95M رسید، 0.5 BTC با قیمت بازار بفروش

ویژگی‌ها: - شرط فعال‌سازی (stop_price) - اجرای مارکت

استفاده: - استاپ لاس ساده - حفظ سرمایه

Time in Force (زمان اعتبار)¶

1. Good Till Canceled (GTC)¶

پیش‌فرض: تا زمانی که لغو نشود

ویژگی: - در دفتر می‌ماند - تا لغو یا پر شدن کامل

2. Fill or Kill (FOK)¶

پر شدن کامل یا لغو

ویژگی: - یا کامل پر می‌شود - یا فوراً لغو می‌شود

3. Immediate or Cancel (IOC)¶

پر شدن فوری یا لغو بقیه

ویژگی: - هر چه پر شد، پر شد - بقیه لغو می‌شود

4. All or None (AON)¶

همه یا هیچ

ویژگی: - باید کامل پر شود - جزئی پر شدن مجاز نیست

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

نمونه 1: سفارش خرید لیمیت¶

{
  "symbol": "BTC-IRR",
  "side": "buy",
  "type": "limit",
  "price": "1000000000",
  "quantity": "0.5",
  "time_in_force": "good-till-canceled"
}

توضیح: - می‌خواهم 0.5 BTC بخرم - حداکثر قیمت: 1,000,000,000 IRR - تا زمانی که لغو نکنم در دفتر می‌ماند

نمونه 2: سفارش فروش مارکت¶

{
  "symbol": "BTC-IRR",
  "side": "sell",
  "type": "market",
  "quantity": "0.3"
}

توضیح: - می‌خواهم 0.3 BTC بفروشم - با بهترین قیمت موجود - فوراً اجرا می‌شود

نمونه 3: سفارش استاپ لاس¶

{
  "symbol": "BTC-IRR",
  "side": "sell",
  "type": "stop-limit",
  "stop_price": "950000000",
  "price": "940000000",
  "quantity": "0.5",
  "time_in_force": "good-till-canceled"
}

توضیح: - اگر قیمت به 95M رسید - سفارش فروش 0.5 BTC با قیمت 94M فعال شود - برای جلوگیری از ضرر بیشتر

مدیریت موجودی¶

Hold (قفل موجودی)¶

هنگام ایجاد سفارش خرید:

موجودی IRR: 100M
سفارش: خرید 0.5 BTC @ 100M
مبلغ: 50M IRR

موجودی کل: 100M
Hold: 50M
Available: 50M

هنگام لغو سفارش:

موجودی کل: 100M
Hold: 0
Available: 100M

تسویه معامله¶

سفارش خرید 0.5 BTC @ 100M:

کاربر خریدار:
- کیف پول IRR: -50M (قیمت)
- کیف پول IRR: -50K (کارمزد 0.1%)
- کیف پول BTC: +0.5

کاربر فروشنده:
- کیف پول BTC: -0.5
- کیف پول IRR: +49.95M (قیمت - کارمزد)

چک‌لیست ایجاد سفارش¶

قبل از ایجاد سفارش: - [ ] نماد فعال است - [ ] زمان در جلسه معاملاتی - [ ] موجودی کافی - [ ] حجم معتبر (>= min) - [ ] قیمت معتبر (ضریب tick_size) - [ ] نوع سفارش صحیح - [ ] پارامترهای نوع انتخاب شده

نکات امنیتی¶

بررسی موجودی قبل از ایجاد
موجودی کافی برای قیمت * حجم
موجودی برای کارمزد
محدودیت‌ها
حداکثر حجم سفارش
محدودیت نوسان قیمت
محدودیت تعداد سفارش
لغو خودکار
منقضی شدن زمان
غیرفعال شدن نماد
توقف معاملات

خلاصه¶

اندپوینت	متد	توضیحات	دسترسی
`/orders`	GET	لیست سفارشات	خودش یا admin
`/orders`	POST	ایجاد سفارش	خودش
`/orders/{uid}`	POST	دریافت سفارش	خودش یا admin
`/orders/{uid}/cancel`	POST	لغو سفارش	خودش یا admin

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