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

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

توضیحات کلی

این API برای مشاهده معاملات انجام شده استفاده می‌شود. هر معامله نتیجه تطبیق دو سفارش (خرید و فروش) است.

ساختار داده Trade

{
  "uid": "trade_123abc",
  "tenant_id": "tenant_001",
  "symbol": "BTC-IRR",
  "price": "999000000",
  "quantity": "0.2",
  "session_id": "sess_123",
  "maker_order": {
    "order_id": "ord_456",
    "wallet_id": "wallet_789",
    "user_id": "user_456",
    "hold_id": "hold_789",
    "side": "sell",
    "broker_id": null
  },
  "maker_fee": "199800",
  "taker_order": {
    "order_id": "ord_123",
    "wallet_id": "wallet_456",
    "user_id": "user_123",
    "hold_id": "hold_789",
    "side": "buy",
    "broker_id": null
  },
  "taker_fee": "399600",
  "buy_proposal_id": null,
  "sell_proposal_id": null,
  "status": "executed",
  "created_at": "2025-12-30T10:05:00Z"
}

فیلدها

  • uid: شناسه منحصر به فرد معامله
  • tenant_id: شناسه تانانت
  • symbol: نماد معاملاتی
  • price: قیمت معامله
  • quantity: حجم معامله
  • session_id: شناسه جلسه معاملاتی
  • maker_order: اطلاعات سفارش Maker
  • maker_fee: کارمزد Maker
  • taker_order: اطلاعات سفارش Taker
  • taker_fee: کارمزد Taker
  • buy_proposal_id: شناسه پیشنهاد خرید (اختیاری)
  • sell_proposal_id: شناسه پیشنهاد فروش (اختیاری)
  • status: وضعیت (pending, executed, failed)
  • created_at: تاریخ انجام معامله

اندپوینت‌ها

1. List Trades (لیست معاملات)

GET /api/exchange/v1/trades

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

پارامترهای Query: - offset (integer, optional, default: 0) - limit (integer, optional, default: 10, max: 100) - symbol (string, optional): فیلتر بر اساس نماد - user_id (string, optional): فیلتر بر اساس کاربر - wallet_id (string, optional): فیلتر بر اساس کیف پول - order_id (string, optional): فیلتر بر اساس سفارش - order_side (string, optional): buy یا sell - created_at_from (string, optional): ISO 8601 - created_at_to (string, optional): ISO 8601

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

نمونه موفق

درخواست: 

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

پاسخ (200 OK): 

{
  "heads": {
    "uid": "شناسه",
    "symbol": "نماد",
    "price": "قیمت",
    "quantity": "حجم",
    "maker_fee": "کارمزد Maker",
    "taker_fee": "کارمزد Taker",
    "status": "وضعیت",
    "created_at": "تاریخ"
  },
  "items": [
    {
      "uid": "trade_123",
      "tenant_id": "tenant_001",
      "symbol": "BTC-IRR",
      "price": "999000000",
      "quantity": "0.2",
      "session_id": "sess_123",
      "maker_order": {
        "order_id": "ord_456",
        "wallet_id": "wallet_789",
        "user_id": "user_456",
        "side": "sell"
      },
      "maker_fee": "199800",
      "taker_order": {
        "order_id": "ord_123",
        "wallet_id": "wallet_456",
        "user_id": "user_123",
        "side": "buy"
      },
      "taker_fee": "399600",
      "status": "executed",
      "created_at": "2025-12-30T10:05:00Z"
    },
    {
      "uid": "trade_456",
      "tenant_id": "tenant_001",
      "symbol": "BTC-IRR",
      "price": "1000000000",
      "quantity": "0.3",
      "session_id": "sess_123",
      "maker_order": {
        "order_id": "ord_789",
        "wallet_id": "wallet_101",
        "user_id": "user_789",
        "side": "sell"
      },
      "maker_fee": "300000",
      "taker_order": {
        "order_id": "ord_124",
        "wallet_id": "wallet_456",
        "user_id": "user_123",
        "side": "buy"
      },
      "taker_fee": "600000",
      "status": "executed",
      "created_at": "2025-12-30T10:10:00Z"
    }
  ],
  "total": 50,
  "offset": 0,
  "limit": 10
}

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

درخواست: 

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

پاسخ (401 Unauthorized): 

{
  "detail": "Not authenticated"
}

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

درخواست: 

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

پاسخ (403 Forbidden): 

{
  "detail": "Access denied"
}

2. Retrieve Trade (دریافت معامله خاص)

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

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

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

دسترسی: مالک یکی از طرفین معامله یا admin

نمونه موفق

درخواست: 

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

پاسخ (200 OK): 

{
  "uid": "trade_123",
  "tenant_id": "tenant_001",
  "symbol": "BTC-IRR",
  "price": "999000000",
  "quantity": "0.2",
  "session_id": "sess_123",
  "maker_order": {
    "order_id": "ord_456",
    "wallet_id": "wallet_789",
    "user_id": "user_456",
    "hold_id": "hold_789",
    "side": "sell",
    "broker_id": null
  },
  "maker_fee": "199800",
  "taker_order": {
    "order_id": "ord_123",
    "wallet_id": "wallet_456",
    "user_id": "user_123",
    "hold_id": "hold_789",
    "side": "buy",
    "broker_id": null
  },
  "taker_fee": "399600",
  "buy_proposal_id": null,
  "sell_proposal_id": null,
  "status": "executed",
  "created_at": "2025-12-30T10:05:00Z"
}

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

درخواست: 

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

پاسخ (404 Not Found): 

{
  "detail": "Trade not found"
}

جزئیات معامله

Maker vs Taker

Maker (تولیدکننده نقدینگی)

سفارش: فروش 0.5 BTC @ 100M
وضعیت: در دفتر سفارشات
کارمزد: 0.1% (کمتر)

ویژگی‌ها: - سفارش در دفتر موجود - منتظر خریدار - کارمزد کمتر (تشویق نقدینگی)

Taker (بردارنده نقدینگی)

سفارش: خرید 0.5 BTC @ 100M
وضعیت: وارد شده و اجرا شده
کارمزد: 0.2% (بیشتر)

ویژگی‌ها: - سفارش وارد شده - با سفارش موجود تطبیق - کارمزد بیشتر

محاسبه کارمزد

مثال: معامله 0.2 BTC @ 999M

# اعداد
quantity = 0.2
price = 999000000
total = quantity * price  # = 199,800,000 IRR

# Maker: 0.1%
maker_fee = 199,800,000 * 0.001 = 199,800 IRR

# Taker: 0.2%
taker_fee = 199,800,000 * 0.002 = 399,600 IRR

# نتیجه
# فروشنده (Maker): دریافت 199,800,000 - 199,800 = 199,600,200 IRR
# خریدار (Taker): پرداخت 199,800,000 + 399,600 = 200,199,600 IRR
# صندوق کارمزد: 199,800 + 399,600 = 599,400 IRR

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

نمونه 1: معامله کامل

درخواست: 

curl -X GET "{{ API_BASE_URL }}/api/exchange/v1/trades?\
symbol=BTC-IRR&\
created_at_from=2025-12-30T00:00:00Z&\
created_at_to=2025-12-30T23:59:59Z" \
  -H "Authorization: Bearer <user_token>"

پاسخ: 

{
  "heads": {
    "uid": "شناسه",
    "symbol": "نماد",
    "price": "قیمت",
    "quantity": "حجم",
    "maker_fee": "کارمزد Maker",
    "taker_fee": "کارمزد Taker"
  },
  "items": [
    {
      "uid": "trade_123",
      "symbol": "BTC-IRR",
      "price": "999000000",
      "quantity": "0.2",
      "maker_fee": "199800",
      "taker_fee": "399600",
      "created_at": "2025-12-30T10:05:00Z"
    },
    {
      "uid": "trade_456",
      "symbol": "BTC-IRR",
      "price": "1000000000",
      "quantity": "0.3",
      "maker_fee": "300000",
      "taker_fee": "600000",
      "created_at": "2025-12-30T10:10:00Z"
    }
  ],
  "total": 2,
  "offset": 0,
  "limit": 10
}

نمونه 2: معاملات یک سفارش خاص

درخواست: 

curl -X GET "{{ API_BASE_URL }}/api/exchange/v1/trades?order_id=ord_123" \
  -H "Authorization: Bearer <user_token>"

پاسخ: 

{
  "heads": {
    "uid": "شناسه",
    "symbol": "نماد",
    "price": "قیمت",
    "quantity": "حجم"
  },
  "items": [
    {
      "uid": "trade_123",
      "symbol": "BTC-IRR",
      "price": "999000000",
      "quantity": "0.2",
      "maker_fee": "199800",
      "taker_fee": "399600",
      "created_at": "2025-12-30T10:05:00Z"
    },
    {
      "uid": "trade_789",
      "symbol": "BTC-IRR",
      "price": "1000000000",
      "quantity": "0.3",
      "maker_fee": "300000",
      "taker_fee": "600000",
      "created_at": "2025-12-30T10:15:00Z"
    }
  ],
  "total": 2,
  "offset": 0,
  "limit": 10
}

نمونه 3: معاملات امروز

درخواست: 

# تاریخ امروز
TODAY=$(date -u +%Y-%m-%d)

curl -X GET "{{ API_BASE_URL }}/api/exchange/v1/trades?\
created_at_from=${TODAY}T00:00:00Z&\
created_at_to=${TODAY}T23:59:59Z" \
  -H "Authorization: Bearer <user_token>"

پاسخ: 

{
  "heads": {
    "uid": "شناسه",
    "symbol": "نماد",
    "price": "قیمت",
    "quantity": "حجم",
    "created_at": "تاریخ"
  },
  "items": [
    {
      "uid": "trade_123",
      "symbol": "BTC-IRR",
      "price": "999000000",
      "quantity": "0.2",
      "created_at": "2025-12-30T10:05:00Z"
    }
  ],
  "total": 1,
  "offset": 0,
  "limit": 10
}

تحلیل معاملات

محاسبه P&L (Profit & Loss)

# معاملات کاربر
trades = [
    {
        "side": "buy",
        "price": "1000000000",
        "quantity": "0.5",
        "fee": "500000"
    },
    {
        "side": "sell",
        "price": "1050000000",
        "quantity": "0.5",
        "fee": "525000"
    }
]

# محاسبه
buy_cost = 1000000000 * 0.5 + 500000  # = 500,500,000
sell_revenue = 1050000000 * 0.5 - 525000  # = 524,475,000
profit = sell_revenue - buy_cost  # = 23,975,000 IRR

میانگین قیمت خرید

# معاملات خرید
buy_trades = [
    {"price": 1000000000, "quantity": 0.3},
    {"price": 1010000000, "quantity": 0.2}
]

# میانگین وزنی
total_quantity = 0.3 + 0.2  # = 0.5
total_value = (1000000000 * 0.3) + (1010000000 * 0.2)  # = 502,000,000
avg_price = total_value / total_quantity  # = 1,004,000,000 IRR

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

برای کاربران

  1. ✅ مشاهده معاملات خود: GET /trades?user_id=me
  2. ✅ معاملات یک نماد: GET /trades?symbol=BTC-IRR
  3. ✅ معاملات امروز: GET /trades?created_at_from=...

برای بانک‌ها

  1. ✅ گزارش‌گیری کامل
  2. ✅ محاسبه کارمزد
  3. ✅ تحلیل معاملات

نکات امنیتی

  1. دسترسی محدود
  2. کاربران فقط معاملات خود را می‌بینند

  3. ادمین به همه دسترسی دارد

  4. داده‌های حساس

  5. اطلاعات کیف پول حذف شده

  6. فقط شناسه‌ها نمایش داده می‌شود

  7. لاگ‌گیری

  8. تمام معاملات ثبت می‌شود
  9. قابل ردیابی و بازرسی

خلاصه

اندپوینت متد توضیحات دسترسی
/trades GET لیست معاملات خودش یا admin
/trades/{uid} POST دریافت معامله خودش یا admin

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