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

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",
    "quantityTick": 1e-05,
    "priceTick": 0.1,
    "minNotional": 10,
    "maxNotional": 600000000,
    "isTrade": true,
    "isReduceOnly": false,
    "isCancelOrder": true,
    "adjustedFundingRateCap": 0.003,
    "adjustedFundingRateFloor": -0.003,
    "fundingIntervalHours": 8
  }
]

فیلدهای پاسخ

فیلد	توضیحات
symbol	نام نماد
baseAsset	ارز پایه
quoteAsset	ارز مظنه
quantityTick	گام مقدار سفارش؛ مقدار qt باید مضربی از این عدد باشد
priceTick	گام قیمت؛ مقادیر price و stopPrice باید مضربی از این عدد باشند
minNotional	حداقل ارزش سفارش به USDT (قیمت × مقدار)
maxNotional	حداکثر ارزش سفارش به USDT (قیمت × مقدار)
isTrade	امکان ثبت سفارش جدید در این نماد
isReduceOnly	در صورت true فقط سفارش های reduceOnly (کاهش پوزیشن) در این نماد پذیرفته می شوند
isCancelOrder	امکان لغو سفارش در این نماد
adjustedFundingRateCap	سقف نرخ تامین مالی
adjustedFundingRateFloor	کف نرخ تامین مالی
fundingIntervalHours	فاصله زمانی پرداخت تامین مالی به ساعت

یادداشت

فیلدهای عددی این پاسخ به صورت عدد JSON ارسال می شوند و مقادیر خیلی کوچک ممکن است به شکل نماد علمی باشند (مثلاً 1e-05 یعنی 0.00001).

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

برای دریافت آمار تغییرات قیمت 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",
  "reduceOnly": false,
  "postOnly": false
}

پارامترها

نام	نوع	اجباری	توضیحات
symbol	string	بله	نماد، مثلاً BTC-USDT
side	string	بله	BUY یا SELL
type	string	بله	LIMIT، MARKET، STOP_LIMIT، STOP_MARKET، TAKE_PROFIT_LIMIT، TAKE_PROFIT_MARKET
qt	decimal	بله*	مقدار سفارش بر حسب ارز پایه (مثلاً BTC در BTC-USDT). باید بزرگ تر از صفر و مضربی از quantityTick نماد باشد. *وقتی closePosition برابر true است باید ارسال نشود یا صفر باشد
price	decimal	شرطی	قیمت سفارش؛ برای LIMIT، STOP_LIMIT و TAKE_PROFIT_LIMIT اجباری است و باید مضربی از priceTick باشد. برای سفارش های Market ارسال نشود
stopPrice	decimal	شرطی	قیمت فعال سازی؛ برای انواع STOP_* و TAKE_PROFIT_* اجباری است و باید مضربی از priceTick باشد
workingType	string	شرطی	مبنای قیمت فعال سازی سفارش های شرطی: MARK_PRICE (قیمت مارک) یا CONTRACT_PRICE (آخرین قیمت معامله). برای انواع STOP_* و TAKE_PROFIT_* اجباری است
reduceOnly	boolean	خیر	سفارش فقط پوزیشن باز را کاهش می دهد و پوزیشن جدید باز نمی کند (پیش فرض false)
closePosition	boolean	خیر	سفارش شرطی برای بستن کل پوزیشن باز نماد؛ فقط با STOP_MARKET و TAKE_PROFIT_MARKET (پیش فرض false)
postOnly	boolean	خیر	فقط برای LIMIT؛ اگر سفارش در لحظه ثبت با دفتر سفارشات تطبیق پیدا کند، به جای اجرا رد (REJECTED) می شود (پیش فرض false)
client_order_id	string	خیر	شناسه دلخواه شما برای سفارش که در پاسخ ها برگردانده می شود

اطلاع

• مقادیر decimal را می توانید به صورت رشته ("0.001") یا عدد ارسال کنید؛ ارسال به صورت رشته توصیه می شود.
• سفارش های LIMIT تا زمان اجرا یا لغو در دفتر سفارشات باقی می مانند (GTC). پارامتر timeInForce پشتیبانی نمی شود و در صورت ارسال نادیده گرفته می شود.
• ارزش سفارش (قیمت × qt) باید بین minNotional و maxNotional نماد باشد. برای سفارش Market قیمت لحظه ای بازار مبنا قرار می گیرد.
• مارجین مورد نیاز بر اساس ارزش سفارش و اهرم تنظیم شده برای نماد (سرویس تغییر اهرم) محاسبه می شود.
• reduceOnly و closePosition نمی توانند همزمان true باشند.

باز کردن پوزیشن LONG و SHORT

برای هر نماد فقط یک پوزیشن باز (LONG یا SHORT) وجود دارد. سفارش BUY پوزیشن LONG و سفارش SELL پوزیشن SHORT باز می کند.

// باز کردن LONG با سفارش Market
{
  "symbol": "BTC-USDT",
  "side": "BUY",
  "type": "MARKET",
  "qt": "0.001"
}

// باز کردن SHORT با سفارش Limit
{
  "symbol": "BTC-USDT",
  "side": "SELL",
  "type": "LIMIT",
  "qt": "0.001",
  "price": "120000"
}

بستن پوزیشن (reduceOnly)

برای بستن کامل یا بخشی از پوزیشن، سفارشی در جهت مخالف پوزیشن با reduceOnly: true ثبت کنید:

• برای پوزیشن LONG باید side برابر SELL و برای پوزیشن SHORT باید side برابر BUY باشد.
• مقدار qt نباید از مقدار باقیمانده پوزیشن (remainingQty در پوزیشن های باز) بیشتر باشد. مجموع qt همه سفارش های reduceOnly باز همان پوزیشن نیز نباید از این مقدار بیشتر شود.
• اگر پوزیشن بازی برای نماد وجود نداشته باشد، سفارش رد می شود.
• بستن کامل پوزیشن با سفارش Market (qt برابر کل remainingQty) سفارش های reduceOnly و حد سود/ضرر باز همان پوزیشن را نیز لغو می کند.

// بستن بخشی از پوزیشن LONG با سفارش Market
{
  "symbol": "BTC-USDT",
  "side": "SELL",
  "type": "MARKET",
  "qt": "0.0005",
  "reduceOnly": true
}

// بستن پوزیشن SHORT با سفارش Limit
{
  "symbol": "BTC-USDT",
  "side": "BUY",
  "type": "LIMIT",
  "qt": "0.001",
  "price": "100000",
  "reduceOnly": true
}

حد سود و حد ضرر (TP/SL)

حد سود و حد ضرر با همین سرویس و انواع سفارش شرطی ثبت می شوند. سفارش شرطی تا رسیدن قیمت مبنا (workingType) به stopPrice با وضعیت NEW منتظر می ماند و پس از فعال شدن به صورت Market یا Limit (با price) ارسال می شود.

نوع	کاربرد
STOP_MARKET	حد ضرر؛ پس از فعال سازی به صورت Market اجرا می شود
STOP_LIMIT	حد ضرر؛ پس از فعال سازی با قیمت price ثبت می شود
TAKE_PROFIT_MARKET	حد سود؛ پس از فعال سازی به صورت Market اجرا می شود
TAKE_PROFIT_LIMIT	حد سود؛ پس از فعال سازی با قیمت price ثبت می شود

برای حد سود/ضرری که کل پوزیشن را می بندد، از closePosition: true استفاده کنید:

• فقط با STOP_MARKET یا TAKE_PROFIT_MARKET مجاز است و qt نباید ارسال شود (یا صفر باشد).
• باید پوزیشن باز وجود داشته باشد و side مخالف پوزیشن باشد (SELL برای LONG و BUY برای SHORT).
• برای هر نماد از هر نوع (STOP_MARKET و TAKE_PROFIT_MARKET) فقط یک سفارش closePosition فعال مجاز است.
• محدوده stopPrice نسبت به قیمت فعلی (مارک یا آخرین قیمت، بسته به workingType):

پوزیشن	side	حد ضرر (STOP_MARKET)	حد سود (TAKE_PROFIT_MARKET)
LONG	SELL	stopPrice کمتر از قیمت فعلی	stopPrice بیشتر از قیمت فعلی
SHORT	BUY	stopPrice بیشتر از قیمت فعلی	stopPrice کمتر از قیمت فعلی

// حد ضرر برای کل پوزیشن LONG
{
  "symbol": "BTC-USDT",
  "side": "SELL",
  "type": "STOP_MARKET",
  "stopPrice": "95000",
  "workingType": "MARK_PRICE",
  "closePosition": true
}

// حد سود برای کل پوزیشن LONG
{
  "symbol": "BTC-USDT",
  "side": "SELL",
  "type": "TAKE_PROFIT_MARKET",
  "stopPrice": "130000",
  "workingType": "MARK_PRICE",
  "closePosition": true
}

برای بستن بخشی از پوزیشن با سفارش شرطی، به جای closePosition مقدار qt را همراه با reduceOnly: true ارسال کنید:

// حد ضرر Limit برای بخشی از پوزیشن SHORT
{
  "symbol": "BTC-USDT",
  "side": "BUY",
  "type": "STOP_LIMIT",
  "qt": "0.0005",
  "stopPrice": "125000",
  "price": "125100",
  "workingType": "CONTRACT_PRICE",
  "reduceOnly": true
}

یادداشت

در سفارش های شرطی بدون closePosition، نوع حد ضرر یا حد سود بر اساس جهت سفارش و موقعیت stopPrice نسبت به قیمت فعلی توسط سیستم تعیین می شود (مثلاً یک SELL با stopPrice بالاتر از قیمت فعلی به TAKE_PROFIT_* تبدیل می شود). اجرای Market یا Limit همان چیزی است که ارسال کرده اید. نوع نهایی در فیلد type پاسخ برگردانده می شود.

برای مشاهده سفارش های شرطی فعال از دریافت سفارشات باز و برای حذف آن ها از لغو سفارش استفاده کنید.

پاسخ نمونه

کد وضعیت HTTP در صورت موفقیت 201 است.

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

فیلد	توضیحات
id	شناسه سفارش (برای دریافت سفارش و لغو سفارش)
quantity	مقدار سفارش بر حسب ارز پایه (برای سفارش closePosition صفر است)
filled	مقدار اجرا شده
status	وضعیت سفارش؛ CREATED برای سفارش Limit/Market تازه ثبت شده و NEW برای سفارش شرطی در انتظار فعال سازی
closePositionId	شناسه پوزیشنی که سفارش reduceOnly یا closePosition به آن مربوط است
createdAt	زمان ثبت به ثانیه

هشدار

ثبت سفارش به صورت غیرهمزمان پردازش می شود. پاسخ این سرویس فقط تایید ثبت درخواست است و وضعیت اجرا (OPEN، FILLED، CANCELED، REJECTED و ...) را باید با دریافت سفارش یا دریافت پوزیشن های باز پیگیری کنید.

دریافت سفارش

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

درخواست

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,
  "postOnly": false
}

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

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

درخواست

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,
    "postOnly": false
  }
]

لغو سفارش

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

درخواست

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,
  "postOnly": false
}

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

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

درخواست

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,
    "postOnly": false
  }
]

هشدار

درصورتی که هیچ سفارشی وجود نداشته باشد پاسخ بصورت 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 و مجوزها