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

توضیحات کلی

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

ساختار داده Ticker

{
  "symbol": "BTC-IRR",
  "last_price": "1000000000",
  "daily_volume": "50000000000",
  "bid": "999000000",
  "bid_size": "10000000000",
  "ask": "1001000000",
  "ask_size": "15000000000",
  "daily_change": "50000000",
  "daily_change_relative": "0.05",
  "high": "1020000000",
  "low": "980000000",
  "timestamp": 1735555200,
  "properties": {
    "base": "BTC",
    "quote": "IRR"
  }
}

فیلدها

• symbol: نماد معاملاتی
• last_price: قیمت آخرین معامله
• daily_volume: حجم معاملات امروز
• bid: بهترین قیمت خرید
• bid_size: حجم بهترین قیمت خرید
• ask: بهترین قیمت فروش
• ask_size: حجم بهترین قیمت فروش
• daily_change: تغییر قیمت نسبت به دیروز
• daily_change_relative: تغییر نسبی (درصد)
• high: بالاترین قیمت امروز
• low: پایین‌ترین قیمت امروز
• timestamp: زمان (Unix timestamp)
• properties: ویژگی‌های نماد

اندپوینت‌ها

1. List Tickers (لیست تیکرها)

GET /api/exchange/v1/tickers

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

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

دسترسی: همه کاربران (نیازی به احراز هویت ندارد)

نمونه موفق

درخواست:

curl -X GET "{{ API_BASE_URL }}/api/exchange/v1/tickers?offset=0&limit=10"

پاسخ (200 OK):

{
  "heads": {
    "symbol": "نماد",
    "last_price": "قیمت آخر",
    "daily_volume": "حجم روزانه",
    "bid": "بهترین خرید",
    "ask": "بهترین فروش",
    "daily_change": "تغییر قیمت"
  },
  "items": [
    {
      "symbol": "BTC-IRR",
      "last_price": "1000000000",
      "daily_volume": "50000000000",
      "bid": "999000000",
      "bid_size": "10000000000",
      "ask": "1001000000",
      "ask_size": "15000000000",
      "daily_change": "50000000",
      "daily_change_relative": "0.05",
      "high": "1020000000",
      "low": "980000000",
      "timestamp": 1735555200,
      "properties": {
        "base": "BTC",
        "quote": "IRR"
      }
    },
    {
      "symbol": "ETH-IRR",
      "last_price": "35000000",
      "daily_volume": "30000000000",
      "bid": "34900000",
      "bid_size": "5000000000",
      "ask": "35100000",
      "ask_size": "7000000000",
      "daily_change": "500000",
      "daily_change_relative": "0.014",
      "high": "35500000",
      "low": "34500000",
      "timestamp": 1735555200,
      "properties": {
        "base": "ETH",
        "quote": "IRR"
      }
    },
    {
      "symbol": "USDT-IRR",
      "last_price": "50000",
      "daily_volume": "100000000000",
      "bid": "49990",
      "bid_size": "50000000000",
      "ask": "50010",
      "ask_size": "60000000000",
      "daily_change": "10",
      "daily_change_relative": "0.0002",
      "high": "50100",
      "low": "49900",
      "timestamp": 1735555200,
      "properties": {
        "base": "USDT",
        "quote": "IRR"
      }
    }
  ],
  "total": 3,
  "offset": 0,
  "limit": 10
}

---

2. Get Ticker (تیکر نماد خاص)

GET /api/exchange/v1/tickers/{symbol}

توضیحات: - دریافت داده‌های بازار برای یک نماد خاص

پارامترهای Path: - symbol (string, required): نام نماد (مثلاً BTC-IRR)

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

نمونه موفق

درخواست:

curl -X GET "{{ API_BASE_URL }}/api/exchange/v1/tickers/BTC-IRR"

پاسخ (200 OK):

{
  "symbol": "BTC-IRR",
  "last_price": "1000000000",
  "daily_volume": "50000000000",
  "bid": "999000000",
  "bid_size": "10000000000",
  "ask": "1001000000",
  "ask_size": "15000000000",
  "daily_change": "50000000",
  "daily_change_relative": "0.05",
  "high": "1020000000",
  "low": "980000000",
  "timestamp": 1735555200,
  "properties": {
    "base": "BTC",
    "quote": "IRR"
  }
}

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

درخواست:

curl -X GET "{{ API_BASE_URL }}/api/exchange/v1/tickers/INVALID-IRR"

پاسخ (404 Not Found):

{
  "detail": "Symbol not found"
}

---

3. Get Depth (عمق بازار)

GET /api/exchange/v1/depth/{symbol}

توضیحات: - دریافت دفتر سفارشات (Order Book) - شامل لیست خریداران و فروشندگان

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

پارامترهای Query: - limit (integer, optional, default: 20, max: 100): تعداد سطوح

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

نمونه موفق

درخواست:

curl -X GET "{{ API_BASE_URL }}/api/exchange/v1/depth/BTC-IRR?limit=10"

پاسخ (200 OK):

{
  "symbol": "BTC-IRR",
  "tenant_id": "tenant_001",
  "last_updated": "2025-12-30T10:00:00Z",
  "last_price": "1000000000",
  "bids": [
    {
      "price": "999000000",
      "quantity": "0.5"
    },
    {
      "price": "998000000",
      "quantity": "1.2"
    },
    {
      "price": "997000000",
      "quantity": "2.0"
    },
    {
      "price": "996000000",
      "quantity": "0.8"
    },
    {
      "price": "995000000",
      "quantity": "1.5"
    }
  ],
  "asks": [
    {
      "price": "1001000000",
      "quantity": "0.3"
    },
    {
      "price": "1002000000",
      "quantity": "0.7"
    },
    {
      "price": "1003000000",
      "quantity": "1.0"
    },
    {
      "price": "1004000000",
      "quantity": "0.5"
    },
    {
      "price": "1005000000",
      "quantity": "2.0"
    }
  ]
}

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

درخواست:

curl -X GET "{{ API_BASE_URL }}/api/exchange/v1/depth/INVALID-IRR"

پاسخ (404 Not Found):

{
  "detail": "Symbol not found"
}

---

توضیحات داده‌های بازار

1. Ticker (تیکر)

تیکر خلاصه‌ای از وضعیت بازار یک نماد است.

اجزای کلیدی: - last_price: قیمت آخرین معامله - bid/ask: بهترین قیمت‌های خرید/فروش - spread: تفاوت bid و ask - volume: حجم معاملات - change: تغییرات قیمت

مثال:

BTC-IRR:
- قیمت آخر: 1,000,000,000 IRR
- بهترین خرید: 999,000,000 IRR
- بهترین فروش: 1,001,000,000 IRR
- اسپرد: 2,000,000 IRR (0.2%)
- حجم: 50 BTC
- تغییر: +50,000,000 IRR (+5%)

2. Depth (عمق بازار)

دفتر سفارشات کامل شامل تمام سفارشات فعال.

اجزای کلیدی: - bids: لیست سفارشات خرید (از بالاترین قیمت) - asks: لیست سفارشات فروش (از پایین‌ترین قیمت) - last_updated: زمان آخرین به‌روزرسانی

مثال:

Bids (خرید):
1. 999,000,000 IRR - 0.5 BTC
2. 998,000,000 IRR - 1.2 BTC
3. 997,000,000 IRR - 2.0 BTC

Asks (فروش):
1. 1,001,000,000 IRR - 0.3 BTC
2. 1,002,000,000 IRR - 0.7 BTC
3. 1,003,000,000 IRR - 1.0 BTC

مثال‌های کاربردی

نمونه 1: دریافت قیمت لحظه‌ای

کاربرد: نمایش قیمت در اپلیکیشن

درخواست:

curl -X GET "{{ API_BASE_URL }}/api/exchange/v1/tickers/BTC-IRR"

پاسخ:

{
  "symbol": "BTC-IRR",
  "last_price": "1000000000",
  "daily_change": "50000000",
  "daily_change_relative": "0.05",
  "timestamp": 1735555200
}

نمایش به کاربر:

BTC/IRR: 1,000,000,000
تغییر: +50,000,000 (+5%)

نمونه 2: تحلیل عمق بازار

کاربرد: تصمیم‌گیری برای ثبت سفارش

درخواست:

curl -X GET "{{ API_BASE_URL }}/api/exchange/v1/depth/BTC-IRR?limit=20"

تحلیل:

data = response.json()

# حجم کل خرید در ۵ سطح اول
total_bid = sum(bid['quantity'] for bid in data['bids'][:5])
# = 0.5 + 1.2 + 2.0 + 0.8 + 1.5 = 6.0 BTC

# حجم کل فروش در ۵ سطح اول
total_ask = sum(ask['quantity'] for ask in data['asks'][:5])
# = 0.3 + 0.7 + 1.0 + 0.5 + 2.0 = 4.5 BTC

# نتیجه: خرید بیشتر از فروش = احتمال رشد قیمت

نمونه 3: نمایش چارت

کاربرد: داده‌های چارت قیمت

درخواست:

# دریافت تیکرها برای چند نماد
curl -X GET "{{ API_BASE_URL }}/api/exchange/v1/tickers?limit=5"

پردازش:

// برای هر نماد
tickers.forEach(ticker => {
  const price = parseFloat(ticker.last_price);
  const change = parseFloat(ticker.daily_change_relative) * 100;

  // نمایش در چارت
  updateChart(ticker.symbol, price, change);
});

محاسبات بازار

1. اسپرد (Spread)

spread = ask - bid
spread_percent = (spread / bid) * 100

# مثال:
# bid = 999,000,000
# ask = 1,001,000,000
# spread = 2,000,000
# spread% = 0.2%

2. میانگین وزنی قیمت (VWAP)

# فرض کنیم معاملات امروز:
trades = [
    {"price": 1000000000, "quantity": 0.5},
    {"price": 1001000000, "quantity": 0.3},
    {"price": 999000000, "quantity": 0.2}
]

total_value = sum(t['price'] * t['quantity'] for t in trades)
total_quantity = sum(t['quantity'] for t in trades)
vwap = total_value / total_quantity

# = (500M + 300.3M + 199.8M) / 1.0 = 1,000,100,000 IRR

3. حجم معاملات انباشته

# محاسبه حجم انباشته در عمق بازار
bids = [
    {"price": 999000000, "quantity": 0.5},
    {"price": 998000000, "quantity": 1.2},
    {"price": 997000000, "quantity": 2.0}
]

cumulative = 0
for bid in bids:
    cumulative += bid['quantity']
    bid['cumulative'] = cumulative

# نتیجه:
# 999M: 0.5 BTC (cum: 0.5)
# 998M: 1.2 BTC (cum: 1.7)
# 997M: 2.0 BTC (cum: 3.7)

بهترین روش‌ها

1. کش‌ینگ

# تیکرها را کش کنید (به‌روزرسانی هر ۵ ثانیه)
import time

cache = {}
cache_time = 0

def get_ticker(symbol):
    global cache_time, cache

    if time.time() - cache_time > 5:
        response = requests.get(f"{BASE_URL}/api/exchange/v1/tickers/{symbol}")
        cache = response.json()
        cache_time = time.time()

    return cache

2. پولینگ (Polling)

// به‌روزرسانی خودکار هر ۲ ثانیه
setInterval(async () => {
  const ticker = await fetch(`${BASE_URL}/api/exchange/v1/tickers/BTC-IRR`);
  updateUI(ticker);
}, 2000);

3. مدیریت خطاها

def get_market_data(symbol):
    try:
        ticker = get_ticker(symbol)
        depth = get_depth(symbol, limit=10)
        return {
            "ticker": ticker,
            "depth": depth
        }
    except requests.exceptions.RequestException as e:
        print(f"Error fetching market data: {e}")
        return None

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

برای نمایش قیمت

• [ ] استفاده از GET /tickers/{symbol}
• [ ] نمایش last_price
• [ ] نمایش تغییرات روزانه

برای تحلیل بازار

• [ ] استفاده از GET /depth/{symbol}
• [ ] بررسی حجم‌های خرید/فروش
• [ ] محاسبه اسپرد

برای لیست نمادها

• [ ] استفاده از GET /tickers
• [ ] نمایش لیست کامل

نکات امنیتی

1. نرخ محدودیت (Rate Limit)
2. این اندپوینت‌ها عمومی هستند

3. ممکن است محدودیت نرخ داشته باشند

4. داده‌های زنده

5. داده‌ها ممکن است با تاخیر باشند

6. برای معاملات دقیق، از API اصلی استفاده کنید

7. تاخیر داده‌ها

8. داده‌ها ممکن است چند ثانیه تاخیر داشته باشند
9. برای معاملات فوری، از WebSocket استفاده کنید

خلاصه

اندپوینت	متد	توضیحات	نیاز به احراز
/tickers	GET	لیست تیکرها	خیر
/tickers/{symbol}	GET	تیکر نماد	خیر
/depth/{symbol}	GET	عمق بازار	خیر

---

بعدی: مطالعه مثال‌های کاربردی