بازار فیوچرز (تعهدی)

API های عمومی

بررسی سلامت سیستم

برای بررسی وضعیت سلامت سرور API:

درخواست

GET /fapi/v1/health

پاسخ نمونه

{
  "status": "OK"
}

تست اتصال

برای تست اتصال به API:

درخواست

GET /fapi/v1/ping

پاسخ نمونه

{
  "status": "OK"
}

زمان سرور

برای دریافت زمان فعلی سرور:

درخواست

GET /fapi/v1/time

پاسخ نمونه

{
  "serverTime": 1640995200000
}

لیست نمادهای معاملاتی

برای دریافت لیست تمام نمادهای معاملاتی آینده و تنظیمات آنها:

درخواست

GET /fapi/v1/symbols

پاسخ نمونه

[
  {
    "symbol": "BTC-USDT",
    "baseAsset": "BTC",
    "quoteAsset": "USDT",
    "status": "TRADING",
    "maintMarginPercent": "2.5000",
    "requiredMarginPercent": "5.0000",
    "baseAssetPrecision": 8,
    "quotePrecision": 8,
    "pricePrecision": 2,
    "quantityPrecision": 6,
    "minQty": "0.001000",
    "maxQty": "1000.000000",
    "minPrice": "0.01",
    "maxPrice": "1000000.00",
    "tickSize": "0.01",
    "minNotional": "10.00000000"
  }
]

تیکر تمام نمادها

برای دریافت آمار تغییرات قیمت 24 ساعته تمام نمادها:

درخواست

GET /fapi/v1/ticker

پاسخ نمونه

[
  {
    "symbol": "BTC-USDT",
    "priceChange": "1000.50",
    "priceChangePercent": "2.15",
    "lastPrice": "47500.25",
    "bidPrice": "47495.00",
    "askPrice": "47505.50",
    "openPrice": "46499.75",
    "highPrice": "48100.00",
    "lowPrice": "46200.00",
    "volume": "12547.85420000",
    "quoteVolume": "594875124.25",
    "openTime": 1640908800000,
    "closeTime": 1640995200000,
    "count": 125478
  }
]

تیکر یک نماد

برای دریافت آمار تغییرات قیمت 24 ساعته یک نماد مشخص:

درخواست

GET /fapi/v1/ticker/{symbol}

پارامترها

نام	نوع	اجباری	توضیحات
symbol	string	بله	نماد معاملاتی (مثال: BTC-USDT)

پاسخ نمونه

{
  "symbol": "BTC-USDT",
  "priceChange": "1000.50",
  "priceChangePercent": "2.15",
  "lastPrice": "47500.25",
  "bidPrice": "47495.00",
  "askPrice": "47505.50",
  "openPrice": "46499.75",
  "highPrice": "48100.00",
  "lowPrice": "46200.00",
  "volume": "12547.85420000",
  "quoteVolume": "594875124.25",
  "openTime": 1640908800000,
  "closeTime": 1640995200000,
  "count": 125478
}

دفتر سفارشات

برای دریافت عمق بازار (دفتر سفارشات):

درخواست

GET /fapi/v1/depth

پارامترها

نام	نوع	اجباری	توضیحات
symbol	string	بله	نماد معاملاتی
limit	integer	خیر	تعداد آیتم ها (پیش فرض: 100، حداکثر: 1000)

مثال درخواست

GET /fapi/v1/depth?symbol=BTC-USDT&limit=20

پاسخ نمونه

{
  "lastUpdateId": 1641024000000,
  "bids": [
    [
      "47495.00",
      "1.25000000"
    ],
    [
      "47490.00",
      "0.85000000"
    ],
    [
      "47485.00",
      "2.10000000"
    ]
  ],
  "asks": [
    [
      "47505.50",
      "0.95000000"
    ],
    [
      "47510.00",
      "1.75000000"
    ],
    [
      "47515.50",
      "1.30000000"
    ]
  ]
}

معاملات اخیر

برای دریافت معاملات اخیر یک نماد:

درخواست

GET /fapi/v1/trades

پارامترها

نام	نوع	اجباری	توضیحات
symbol	string	بله	نماد معاملاتی
limit	integer	خیر	تعداد معاملات (پیش فرض: 500، حداکثر: 1000)

مثال درخواست

GET /fapi/v1/trades?symbol=BTC-USDT&limit=100

پاسخ نمونه

[
  {
    "id": 123456789,
    "price": "47500.25",
    "qty": "0.15000000",
    "time": 1640995200000,
    "isBuyerMaker": false
  }
]

کندل (شمعی)

برای دریافت داده های تاریخی کندل استیک:

درخواست

GET /fapi/v1/candle

پارامترها

نام	نوع	اجباری	توضیحات
symbol	string	بله	نماد معاملاتی
interval	string	بله	بازه زمانی (1m, 5m, 15m, 30m, 1h, 4h, 1d, 1w)
startTime	long	خیر	زمان شروع به میلی ثانیه
endTime	long	خیر	زمان پایان به میلی ثانیه
limit	integer	خیر	تعداد کندل ها (پیش فرض: 500، حداکثر: 1500)

مثال درخواست

GET /fapi/v1/candle?symbol=BTC-USDT&interval=1h&limit=24

پاسخ نمونه

[
  [
    1640991600000,
    // زمان باز شدن
    "46500.00",
    // قیمت باز شدن
    "47200.00",
    // بالاترین قیمت
    "46400.00",
    // پایین ترین قیمت
    "47100.25",
    // قیمت بسته شدن
    "125.85420000",
    // حجم
    1640995199999,
    // زمان بسته شدن
    "5924751.24",
    // حجم نقل قول
    1547,
    // تعداد معاملات
    "62.85420000",
    // حجم خرید taker
    "2962375.62"
    // حجم نقل قول خرید taker
  ]
]

نرخ تامین مالی

برای دریافت اطلاعات نرخ تامین مالی قراردادهای دائمی:

درخواست

GET /fapi/v1/funding-rate/{symbol}

پارامترها

نام	نوع	اجباری	توضیحات
symbol	string	بله	نماد معاملاتی

مثال درخواست

GET /fapi/v1/funding-rate/BTC-USDT

پاسخ نمونه

{
  "symbol": "BTC-USDT",
  "fundingRate": "0.00010000",
  "fundingTime": 1640995200000,
  "nextFundingTime": 1641024000000
}

سطوح مارجین

برای دریافت براکت های سطح مارجین:

درخواست

GET /fapi/v1/margin-levels
GET /fapi/v1/margin-levels/{symbol}

مثال درخواست

# تمام نمادها
GET /fapi/v1/margin-levels

# نماد مشخص
GET /fapi/v1/margin-levels/BTC-USDT

پاسخ نمونه

[
  {
      "symbol": "BTC-USDT",
      "min": "0",
      "max": "5000",
      "marginRatio": "0.01",
      "marginAmount": "0",
      "maxLeverage": 25
  }
]

---

API های احراز هویت شده

احراز هویت

برای استفاده از API های خصوصی، باید درخواست ها را با HMAC-SHA256 امضا کنید.

هدرهای مورد نیاز

هدر	توضیحات	مثال
x-api-key	کلید API شما	abc123def456...
x-timestamp	زمان درخواست به میلی ثانیه	1640995200000
x-signature	امضای HMAC-SHA256	d4f67a92bc8f...

ثبت سفارش

برای ثبت سفارش معاملاتی جدید:

درخواست

POST /fhapi/v1/order

بدنه درخواست

{
  "symbol": "BTC-USDT",
  "side": "BUY",
  "type": "LIMIT",
  "qt": "0.001",
  "price": "50000.00",
  "timeInForce": "GTC",
  "reduceOnly": false,
  "postOnly": false
}

پاسخ نمونه

{
  "orderId": 123456,
  "symbol": "BTC-USDT",
  "status": "NEW",
  "side": "BUY",
  "type": "LIMIT",
  "quantity": "0.001",
  "price": "50000.00",
  "executedQty": "0.000",
  "cummulativeQuoteQty": "0.00",
  "timestamp": 1640995200000
}

دریافت سفارش

برای دریافت جزئیات سفارش بر اساس شناسه:

درخواست

GET /fhapi/v1/order?order_id=123456

پارامترها

نام	نوع	اجباری	توضیحات
order_id	long	بله	شناسه سفارش

پاسخ نمونه

{
  "id": 2861094228,
  "client_order_id": "",
  "symbol": "BTC-USDT",
  "side": "BUY",
  "type": "LIMIT",
  "price": "50000",
  "stopPrice": "0",
  "quantity": "0.001",
  "filled": "0",
  "status": "OPEN",
  "workingType": "",
  "closePosition": false,
  "closePositionId": 0,
  "createdAt": 1758098692
}

دریافت سفارشات باز

برای دریافت تمام سفارشات باز:

درخواست

POST /fhapi/v1/order/open

بدنه درخواست

{
  "symbol": "BTC-USDT"
}

پاسخ نمونه

[
  {
    "id": 2861149113,
    "client_order_id": "",
    "symbol": "BTC-USDT",
    "side": "BUY",
    "type": "LIMIT",
    "price": "50000",
    "stopPrice": "0",
    "quantity": "0.001",
    "filled": "0",
    "status": "OPEN",
    "workingType": "",
    "closePosition": false,
    "closePositionId": 0,
    "createdAt": 1758099163
  }
]

لغو سفارش

برای لغو یک سفارش مشخص:

درخواست

POST /fhapi/v1/order/cancel

بدنه درخواست

{
  "id": 123456
  // your order id
}

پاسخ نمونه

{
  "id": 2861149113,
  "client_order_id": "",
  "symbol": "BTC-USDT",
  "side": "BUY",
  "type": "LIMIT",
  "price": "50000",
  "stopPrice": "0",
  "quantity": "0.001",
  "filled": "0",
  "status": "PRE_CANCELED",
  "workingType": "",
  "closePosition": false,
  "closePositionId": 0,
  "createdAt": 1758099163
}

لغو تمام سفارشات

برای لغو تمام سفارشات باز:

درخواست

POST /fhapi/v1/order/cancel/all

بدنه درخواست

{}

پاسخ نمونه

[
  {
    "id": 2861415884,
    "client_order_id": "",
    "symbol": "BTC-USDT",
    "side": "BUY",
    "type": "LIMIT",
    "price": "50000",
    "stopPrice": "0",
    "quantity": "0.001",
    "filled": "0",
    "status": "OPEN",
    "workingType": "",
    "closePosition": false,
    "closePositionId": 0,
    "createdAt": 1758101873
  }
]

هشدار

درصورتی که هیچ سفارشی وجود نداشته باشد پاسخ بصورت NULL ارسال شده و فرمت جیسون ندارد

دریافت تنظیمات اهرم

برای دریافت تنظیمات اهرم فعلی:

درخواست

GET /fhapi/v1/leverage

پاسخ نمونه

[
  {
    "symbol": "BTC-USDT",
    "leverage": 10
  }
]

تغییر اهرم

برای تغییر اهرم نمادهای مشخص:

درخواست

POST /fhapi/v1/leverage

بدنه درخواست

{
  "symbol": "BTC-USDT",
  "leverage": 20
}

پاسخ نمونه

{
  "status": "done"
}

اطلاعات حساب

برای دریافت جزئیات حساب مارجین:

درخواست

GET /fhapi/v1/margin/account

پاسخ نمونه

{
  "accountStatus": "NORMAL",
  "totalMaintMargin": "0",
  "totalWalletBalance": "19.00340987",
  "totalMarginUsed": "0",
  "orderMarginUsd": "0",
  "positionMarginUsd": "0",
  "totalUnrealizedPnl": "0",
  "availableBalance": "19.00340987",
  "testStatus": true,
  "accountIsDemo": true,
  "totalBonus": "0",
  "positions": []
}

دریافت پوزیشن های باز

برای دریافت تمام پوزیشن های باز:

درخواست

POST /fhapi/v1/positions/open

بدنه درخواست

{}

پاسخ نمونه

[
  {
    "id": 74635001,
    "symbol": "BTC-USDT",
    "side": "SHORT",
    "entryPrice": "116560.9",
    "quantity": "0.00082",
    "remainingQty": "0.00082",
    "leverage": 20,
    "unrealizedPNL": "0",
    "realizedPNL": "0",
    "liqPrice": "0",
    "status": "OPEN",
    "lastUpdatePrice": "116560.9",
    "closePrice": "0",
    "createdAt": 1758102749,
    "updatedAt": 1758102749
  }
]

دریافت سابقه پوزیشن ها

برای دریافت سوابق پوزیشن ها:

درخواست

GET /fhapi/v1/positions/history

پارامترها

نام	نوع	اجباری	توضیحات
limit	number	خیر	تعداد در هر درخواست (مقدار پیش فرض:30)
offset	number	خیر	تعداد رد کردن از ابتدای رکورد ها (مقدار پیش فرض : 0)
symbol	string	خیر	نماد
side	string	خیر	مقدار های مجاز (LONG SHORT)
startTime	number	خیر	زمان به ثانیه
endTime	number	خیر	زمان به ثانیه

پاسخ نمونه

[
  {
    "id": 74635001,
    "symbol": "BTC-USDT",
    "side": "SHORT",
    "entryPrice": "116560.9",
    "quantity": "0.00082",
    "remainingQty": "0.00082",
    "leverage": 20,
    "unrealizedPNL": "0",
    "realizedPNL": "0",
    "liqPrice": "0",
    "status": "OPEN",
    "lastUpdatePrice": "116560.9",
    "closePrice": "0",
    "createdAt": 1758102749,
    "updatedAt": 1758102749
  }
]

کدهای خطا

کدهای وضعیت HTTP

کد	توضیحات	اقدام
200	موفقیت	ادامه عملیات عادی
400	درخواست نامعتبر	بررسی پارامترهای درخواست
401	غیر مجاز	بررسی اعتبارنامه های API و امضا
403	ممنوع	بررسی لیست سفید IP و مجوزها
429	محدودیت نرخ	پیاده سازی backoff نمایی
500	خطای سرور	تلاش مجدد پس از تاخیر
503	سرویس در دسترس نیست	بررسی وضعیت سرویس

کدهای خطای رایج

کد	پیام	راه حل
-1022	امضای نامعتبر	تولید مجدد امضا با پارامترهای صحیح
-1021	زمان نامعتبر	همگام سازی ساعت سیستم با زمان سرور
-2008	کلید API نامعتبر	بررسی تنظیمات کلید API
-2015	کلید API، IP یا مجوزهای نامعتبر	تأیید لیست سفید IP و مجوزها