Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/bullish-exchange/api-docs/llms.txt

Use this file to discover all available pages before exploring further.

The Derivatives API provides authenticated access to perpetual and options position data, historical settlement records, funding rate history, and borrow interest — alongside public endpoints for the option ladder and funding rate history. For information about liquidation and borrower status events, see the Private WebSocket Data for Borrowers PDF.

​
GET /trading-api/v1/derivatives-positions

Returns the current open derivatives positions for the authenticated trading account. The openInterest for a market equals the total quantity of open long plus open short positions across all accounts.
Authentication: Required.

​
Query Parameters

​
tradingAccountId
string
ID of the trading account. Mandatory for users with multiple trading accounts.
​
symbol
string
Filter by market symbol. E.g. BTC-USDC-PERP.
​
marketType
string
Filter by market type. E.g. DATED_FUTURE, PERPETUAL, OPTION.
​
optionType
string
Filter by option type: CALL or PUT.
​
sort
string
Sort results by market type or option type.

​
Response Fields (array of DerivativesPositionResponse)

​
tradingAccountId
string
ID of the trading account.
​
symbol
string
Derivatives market symbol. E.g. BTC-USDC-PERP.
​
side
string
Position side: BUY (long) or SELL (short).
​
quantity
string
Current position size in base asset units.
​
notional
string
Notional value of the current position, calculated using the mark price.
​
entryNotional
string
Notional value using the average entry price.
​
mtmPnl
string
Sum of all mark-to-market profits and losses plus realized trading P&L since the last settlement.
​
reportedMtmPnl
string
P&L from net price change since the last time the absolute quantity decreased. Updated with every mark-to-market; not updated during settlement or position size increases.
​
reportedFundingPnl
string
Sum of all funding payments received since the position was opened. Updated every time funding is paid.
​
realizedPnl
string
Total profits realized since the trading account first opened this position. Updated only when the position’s absolute size is reduced.
​
settlementAssetSymbol
string
Settlement asset symbol. E.g. USDC.
​
createdAtDatetime
string
ISO 8601 datetime when the position was created.
​
createdAtTimestamp
string
Millisecond EPOCH timestamp when the position was created.
​
updatedAtDatetime
string
ISO 8601 datetime when the position was last updated.
​
updatedAtTimestamp
string
Millisecond EPOCH timestamp when the position was last updated.

​
Example Request

curl -X GET "https://api.exchange.bullish.com/trading-api/v1/derivatives-positions?tradingAccountId=111000000000001" \
  -H "Authorization: Bearer <JWT>"

​
Example Response

[
  {
    "tradingAccountId": "111000000000001",
    "symbol": "BTC-USDC-PERP",
    "side": "BUY",
    "quantity": "1.50000000",
    "notional": "75300.0000",
    "entryNotional": "74000.0000",
    "mtmPnl": "1300.0000",
    "reportedMtmPnl": "1300.0000",
    "reportedFundingPnl": "-15.0000",
    "realizedPnl": "0.0000",
    "settlementAssetSymbol": "USDC",
    "createdAtDatetime": "2024-10-01T08:00:00.000Z",
    "createdAtTimestamp": "1727769600000",
    "updatedAtDatetime": "2024-10-04T08:00:00.000Z",
    "updatedAtTimestamp": "1728028800000"
  }
]

​
GET /trading-api/v1/history/derivatives-settlement

Returns paginated historical derivatives settlement records. Each entry represents a periodic settlement event (typically hourly). Only the last 90 days of data are available.
Authentication: Required.

​
Query Parameters

​
tradingAccountId
string
ID of the trading account. Mandatory for users with multiple trading accounts.
​
symbol
string
Filter by market symbol. E.g. BTC-USDC-PERP.
​
settlementDatetime[gte]
string
required
Start of the settlement datetime window (ISO 8601 with millisecond).
​
settlementDatetime[lte]
string
required
End of the settlement datetime window (ISO 8601 with millisecond).
​
_pageSize
integer
Page size. One of: 5, 25, 50, 100. Defaults to 25.

​
Response Fields (array of DerivativesSettlementResponse)

​
tradingAccountId
string
ID of the trading account.
​
symbol
string
Market symbol. E.g. BTC-USDC-PERP.
​
side
string
Position side at settlement: BUY or SELL.
​
settlementQuantity
string
Position size at the time of settlement.
​
deltaTradingQuantity
string
Change in position size due to trading activity since the last settlement.
​
mtmPnl
string
Mark-to-market profit/loss accumulated since the last settlement.
​
fundingPnl
string
Funding profit/loss accumulated since the last settlement (perpetuals only).
​
eventType
string
Settlement event type. E.g. "settlementUpdate".
​
settlementMarkPrice
string
Mark price at which the position was settled for this cycle.
​
settlementIndexPrice
string
Index price at which the position was settled for this cycle.
​
settlementFundingRate
string
Funding rate applied at this settlement cycle (perpetuals only). E.g. "10.0".
​
settlementDatetime
string
ISO 8601 datetime of the settlement event.
​
settlementTimestamp
string
Millisecond EPOCH timestamp of the settlement event.

​
Example Request

curl -X GET "https://api.exchange.bullish.com/trading-api/v1/history/derivatives-settlement?tradingAccountId=111000000000001&settlementDatetime%5Bgte%5D=2024-10-01T00%3A00%3A00.000Z&settlementDatetime%5Blte%5D=2024-10-04T23%3A59%3A59.000Z" \
  -H "Authorization: Bearer <JWT>"

​
Example Response

[
  {
    "tradingAccountId": "111000000000001",
    "symbol": "BTC-USDC-PERP",
    "side": "BUY",
    "settlementQuantity": "1.50000000",
    "deltaTradingQuantity": "0.00000000",
    "mtmPnl": "125.0000",
    "fundingPnl": "-5.0000",
    "eventType": "settlementUpdate",
    "settlementMarkPrice": "50200.0000",
    "settlementIndexPrice": "50100.0000",
    "settlementFundingRate": "0.01",
    "settlementDatetime": "2024-10-04T08:00:00.000Z",
    "settlementTimestamp": "1728028800000"
  }
]

​
GET /trading-api/v1/history/markets//funding-rate

Returns the historical hourly funding rate for a perpetual market. Only the last 90 days of data are available.
Authentication: Not required.

​
Path Parameters

​
symbol
string
required
Perpetual market symbol. E.g. BTC-USDC-PERP.

​
Query Parameters

​
updatedAtDatetime[gte]
string
Start of the datetime range (ISO 8601 with millisecond).
​
updatedAtDatetime[lte]
string
End of the datetime range (ISO 8601 with millisecond).
​
_pageSize
integer
Page size. One of: 5, 25, 50, 100. Defaults to 25.

​
Response Fields (array)

​
fundingRate
string
The funding rate for this hour. E.g. "0.0001".
​
updatedAtDatetime
string
ISO 8601 datetime of the last funding rate update for the hour. E.g. "2024-09-16T12:59:59.000Z".

​
Example Request

curl -X GET "https://api.exchange.bullish.com/trading-api/v1/history/markets/BTC-USDC-PERP/funding-rate?updatedAtDatetime%5Bgte%5D=2024-10-01T00%3A00%3A00.000Z&updatedAtDatetime%5Blte%5D=2024-10-04T00%3A00%3A00.000Z"

​
Example Response

[
  {
    "fundingRate": "0.0001",
    "updatedAtDatetime": "2024-10-03T23:59:59.000Z"
  },
  {
    "fundingRate": "-0.0002",
    "updatedAtDatetime": "2024-10-04T00:59:59.000Z"
  }
]

​
GET /trading-api/v1/history/borrow-interest

Returns paginated historical hourly borrow interest records for a specific asset. Each entry represents the hourly borrow quantities. The interest charged can be derived as: interest = totalBorrowedQuantity - borrowedQuantity. Only the last 90 days of data are available.
Authentication: Required. Rate limited: Yes.

​
Query Parameters

​
assetSymbol
string
required
Asset symbol to query borrow interest for. E.g. BTC.
​
createdAtDatetime[gte]
string
required
Start of the datetime range (ISO 8601 with millisecond).
​
createdAtDatetime[lte]
string
required
End of the datetime range (ISO 8601 with millisecond).
​
tradingAccountId
string
ID of the trading account. Mandatory for users with multiple trading accounts.
​
_pageSize
integer
Page size. One of: 5, 25, 50, 100. Defaults to 25.

​
Response Fields (array of BorrowInterest)

​
assetId
string
Unique asset ID.
​
assetSymbol
string
Asset symbol. E.g. BTC.
​
borrowedQuantity
string
The principal borrowed quantity during the hour.
​
totalBorrowedQuantity
string
Sum of the principal borrowed quantity plus interest charged during the hour. interest = totalBorrowedQuantity - borrowedQuantity.
​
createdAtDatetime
string
ISO 8601 datetime for the hour in which borrowing occurred or interest was charged. E.g. "2020-08-21T08:00:00.000Z".
​
createdAtTimestamp
string
Millisecond EPOCH timestamp for the hour. E.g. "1621490985000".

​
Example Request

curl -X GET "https://api.exchange.bullish.com/trading-api/v1/history/borrow-interest?assetSymbol=BTC&tradingAccountId=111000000000001&createdAtDatetime%5Bgte%5D=2024-10-01T00%3A00%3A00.000Z&createdAtDatetime%5Blte%5D=2024-10-04T23%3A59%3A59.000Z" \
  -H "Authorization: Bearer <JWT>"

​
Example Response

[
  {
    "assetId": "1",
    "assetSymbol": "BTC",
    "borrowedQuantity": "1.00000000",
    "totalBorrowedQuantity": "1.00003425",
    "createdAtDatetime": "2024-10-04T08:00:00.000Z",
    "createdAtTimestamp": "1728028800000"
  }
]

​
GET /trading-api/v1/option-ladder

Returns available options contracts with pricing, implied volatilities, and Greeks (delta, gamma, theta, vega). Useful for scanning the full option surface for a given underlying asset.
Authentication: Not required.

​
Query Parameters

​
baseSymbol
string
required
Base asset symbol. E.g. BTC.
​
expiry
string
Filter by option expiry date.
​
type
string
Filter by option type: CALL or PUT.
​
sort
string
Sort results by option type or expiry datetime.

​
Example Request

curl -X GET "https://api.exchange.bullish.com/trading-api/v1/option-ladder?baseSymbol=BTC&type=CALL"

​
GET /trading-api/v1/option-ladder/

Returns the option ladder entry for a specific option market, including pricing metrics and Greeks.
Authentication: Not required.

​
Path Parameters

​
symbol
string
required
Option market symbol. Only option markets are supported. E.g. BTC-USDC-20241004-70000-C.

​
Example Request

curl -X GET "https://api.exchange.bullish.com/trading-api/v1/option-ladder/BTC-USDC-20241004-70000-C"

​
Example Response

{
  "symbol": "BTC-USDC-20241004-70000-C",
  "baseSymbol": "BTC",
  "settlementAssetSymbol": "USDC",
  "bid": "90000.0000",
  "ask": "91000.0000",
  "bidQuantity": "0.5",
  "askQuantity": "0.3",
  "bidIVPercentage": "72.5",
  "askIVPercentage": "73.1",
  "underlyingPrice": "100000.0000",
  "optionStrikePrice": "70000",
  "markPrice": "30200.0000",
  "quantity": "1000",
  "openInterest": "0.11442400",
  "openInterestUSD": "1144240.0000",
  "optionType": "CALL",
  "expiryDatetime": "2024-10-04T08:00:00.000Z",
  "greeks": {
    "delta": "0.98",
    "gamma": "0.01",
    "theta": "-0.17",
    "vega": "0.05"
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us