Account Management API Endpoints for Bullish Exchange

The Accounts API provides authenticated access to your trading account structure, asset balances, and inter-account transfer functionality. Most endpoints require a bearer JWT. The tradingAccountId returned from the trading accounts endpoint is used as a required parameter throughout the rest of the API.

GET /trading-api/v1/accounts/trading-accounts

Returns details for all trading accounts accessible by the API key used in the request.

Authentication: Required. Rate limited: Yes.

Response Fields (array of TradingAccountResponse)

tradingAccountId

string

Unique ID for the trading account. Used as a required parameter throughout the REST API.

tradingAccountName

string

Name of the trading account. E.g. "algo trading account".

tradingAccountDescription

string

Description of the trading account.

rateLimitToken

string

Unique token for this account. Provide in the BX-RATELIMIT-TOKEN request header to access higher rate limit tiers. E.g. "97d98951b12fb11f330dd9cb1b807d888c702679ee602edcf1ebc6bac17ad63d".

isPrimaryAccount

string

Whether this is the primary account. String representation of boolean.

isBorrowing

string

Whether the account is currently borrowing.

isLending

string

Whether the account is currently lending.

isDefaulted

string

Whether the account is in a defaulted state.

maxInitialLeverage

string

Maximum initial leverage allowed for this account. E.g. "1".

riskLimitUSD

string

Maximum allowed borrowing for this account in USD. E.g. "10000.0000".

totalCollateralUSD

string

Total collateral across all assets in USD. E.g. "13000.0000".

totalBorrowedUSD

string

Total borrowed across all assets in USD. E.g. "12000.0000".

totalLiabilitiesUSD

string

Total liabilities for this account in USD. E.g. "14000.0000".

initialMarginUSD

string

Minimum margin required to purposefully increase risk.

warningMarginUSD

string

Margin level at which the account receives warning notifications.

liquidationMarginUSD

string

Minimum margin required to avoid liquidation.

fullLiquidationMarginUSD

string

Margin level at which full liquidation occurs.

defaultedMarginUSD

string

Margin level at which the account enters defaulted state.

liquidityAddonUSD

string

Expected market impact of unwinding the portfolio during a liquidation event.

marketRiskUSD

string

Worst possible portfolio loss based on scenario analysis.

isConcentrationRiskEnabled

string

Whether concentration risk checks are enforced for new orders.

endCustomerId

string

End customer ID used for self-trade prevention. Defaults to the institution ID. Max 32 characters.

tradeFeeRate

array

Trade fee rates per feeGroupId for this trading account.

marginProfile

object

Market risk multipliers applied to derive the five individual margin requirement values.

Example Request

curl -X GET "https://api.exchange.bullish.com/trading-api/v1/accounts/trading-accounts" \
  -H "Authorization: Bearer <JWT>"

Example Response

[
  {
    "tradingAccountId": "111000000000001",
    "tradingAccountName": "Primary Account",
    "tradingAccountDescription": "Main algo trading account",
    "rateLimitToken": "97d98951b12fb11f330dd9cb1b807d888c702679ee602edcf1ebc6bac17ad63d",
    "isPrimaryAccount": "true",
    "isBorrowing": "false",
    "isLending": "false",
    "isDefaulted": "false",
    "maxInitialLeverage": "3",
    "riskLimitUSD": "500000.0000",
    "totalCollateralUSD": "100000.0000",
    "totalBorrowedUSD": "0.0000",
    "totalLiabilitiesUSD": "0.0000",
    "initialMarginUSD": "0.0000",
    "warningMarginUSD": "0.0000",
    "liquidationMarginUSD": "0.0000",
    "fullLiquidationMarginUSD": "0.0000",
    "defaultedMarginUSD": "0.0000",
    "liquidityAddonUSD": "0.0000",
    "marketRiskUSD": "0.0000",
    "isConcentrationRiskEnabled": "true"
  }
]

GET /trading-api/v1/accounts/trading-accounts/

Returns details for a specific trading account by its ID.

Authentication: Required. Rate limited: Yes.

Path Parameters

tradingAccountId

string

required

ID of the trading account.

Example Request

curl -X GET "https://api.exchange.bullish.com/trading-api/v1/accounts/trading-accounts/111000000000001" \
  -H "Authorization: Bearer <JWT>"

GET /trading-api/v1/accounts/asset

Returns asset account balances for all assets held in the specified trading account.

Authentication: Required. Rate limited: Yes.

Query Parameters

tradingAccountId

string

required

ID of the trading account.

Response Fields (array of AssetAccount objects)

tradingAccountId

string

ID of the trading account.

assetId

string

Unique asset ID.

assetSymbol

string

Asset symbol. E.g. BTC, USD.

availableQuantity

string

The assets that are available to use on the account.

borrowedQuantity

string

Assets that are currently borrowed.

lockedQuantity

string

Assets locked in open orders, active loans, or AMM instructions.

loanedQuantity

string

Assets that are currently being loaned to other accounts.

updatedAtDatetime

string

ISO 8601 datetime of the last balance update.

updatedAtTimestamp

string

Millisecond EPOCH timestamp of the last balance update.

Example Request

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

Example Response

[
  {
    "tradingAccountId": "111000000000001",
    "assetId": "1",
    "assetSymbol": "BTC",
    "availableQuantity": "5.00000000",
    "borrowedQuantity": "0.00000000",
    "lockedQuantity": "1.00000000",
    "loanedQuantity": "0.00000000",
    "updatedAtDatetime": "2024-10-04T08:00:00.000Z",
    "updatedAtTimestamp": "1728028800000"
  },
  {
    "tradingAccountId": "111000000000001",
    "assetId": "2",
    "assetSymbol": "USD",
    "availableQuantity": "100000.0000",
    "borrowedQuantity": "0.0000",
    "lockedQuantity": "50000.0000",
    "loanedQuantity": "0.0000",
    "updatedAtDatetime": "2024-10-04T08:00:00.000Z",
    "updatedAtTimestamp": "1728028800000"
  }
]

GET /trading-api/v1/accounts/asset/

Returns the asset account balance for a specific asset symbol.

Authentication: Required. Rate limited: Yes.

Path Parameters

symbol

string

required

Asset symbol, e.g. BTC.

Query Parameters

tradingAccountId

string

required

ID of the trading account.

Example Request

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

POST /trading-api/v1/command

Transfers assets between two trading accounts. The command must be acknowledged before the transfer takes effect.

Authentication: Required.

Query Parameters

commandType

string

required

Must be "V1TransferAsset".

Request Headers

Authorization

string

required

Bearer <JWT>

BX-SIGNATURE

string

required

Request signature.

BX-TIMESTAMP

string

required

Milliseconds since EPOCH.

BX-NONCE

string

required

Client-side incremented unsigned 64-bit integer as a string.

Example Request Body

{
  "timestamp": "<TIMESTAMP>",
  "nonce": "<NONCE>",
  "authorizer": "<AUTHORIZER>",
  "command": {
    "commandType": "V1TransferAsset",
    "assetSymbol": "BTC",
    "quantity": "0.50000000",
    "fromTradingAccountId": "111000000000001",
    "toTradingAccountId": "111000000000002"
  }
}

Example Request

curl -X POST "https://api.exchange.bullish.com/trading-api/v1/command?commandType=V1TransferAsset" \
  -H "Authorization: Bearer <JWT>" \
  -H "BX-SIGNATURE: <SIGNATURE>" \
  -H "BX-TIMESTAMP: 1728028800000" \
  -H "BX-NONCE: 1728028800000001" \
  -H "Content-Type: application/json" \
  -d '{
    "timestamp": "1728028800000",
    "nonce": "1728028800000001",
    "authorizer": "<AUTHORIZER>",
    "command": {
      "commandType": "V1TransferAsset",
      "assetSymbol": "BTC",
      "quantity": "0.50000000",
      "fromTradingAccountId": "111000000000001",
      "toTradingAccountId": "111000000000002"
    }
  }'

GET /trading-api/v1/history/transfer

Returns paginated historical transfer records for the authenticated trading account. Only the last 90 days of data are available.

Authentication: Required.

Query Parameters

tradingAccountId

string

ID of the trading account. Mandatory for accounts with multiple trading accounts.

status

string

Transfer status: CLOSED, OPEN, or REJECTED. Defaults to CLOSED.

requestId

string

Unique identifier of the transfer request. E.g. "561287547935260672".

assetSymbol

string

Asset symbol to filter by. E.g. BTC.

createdAtDatetime[gte]

string

required

Start of the datetime window (ISO 8601 with millisecond).

createdAtDatetime[lte]

string

required

End of the datetime window (ISO 8601 with millisecond).

Example Request

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

POST /trading-api/v1/simulate-portfolio-margin

Simulates portfolio margin requirements based on your current portfolio balances. Optionally append hypothetical position details to see simulated results.

Authentication: Required.

Query Parameters

includeExisting

boolean

Whether to include existing portfolio positions in the simulation.

Response Fields

collateralUSD

string

Total collateral in USD. E.g. "13000.0000".

borrowedUSD

string

Total borrowed amount in USD.

initialMarginUSD

string

Minimum margin required to purposefully increase risk.

warningMarginUSD

string

Margin level triggering warning notifications.

liquidationMarginUSD

string

Minimum margin required to avoid liquidation.

fullLiquidationMarginUSD

string

Margin level at which full liquidation occurs.

defaultedMarginUSD

string

Margin level at which the account enters defaulted state.

liquidityAddonUSD

string

Expected market impact of unwinding the portfolio.

marketRiskUSD

string

Worst-case portfolio loss from scenario analysis.

Example Request

curl -X POST "https://api.exchange.bullish.com/trading-api/v1/simulate-portfolio-margin?includeExisting=true" \
  -H "Authorization: Bearer <JWT>" \
  -H "Content-Type: application/json"

GET /trading-api/v1/assets

Returns the list of all supported assets on the exchange. Public endpoint.

Authentication: Not required.

Example Request

curl -X GET "https://api.exchange.bullish.com/trading-api/v1/assets"

GET /trading-api/v1/assets/

Returns details for a specific asset by its symbol.

Authentication: Not required.

Path Parameters

symbol

string

required

Asset symbol, e.g. BTC.

Example Request

curl -X GET "https://api.exchange.bullish.com/trading-api/v1/assets/BTC"

GET /trading-api/v1/nonce

Returns the current nonce range. The lower bound is the EPOCH start of the current day in microseconds; the upper bound is the EPOCH end of the current day in microseconds. Used to generate valid BX-NONCE values for signed requests.

Authentication: Required. Rate limited: No.

Response Fields

lowerBound

integer

Lower bound of the valid nonce range (microseconds). E.g. 8455.

upperBound

integer

Upper bound of the valid nonce range (microseconds). E.g. 9455.

Example Request

curl -X GET "https://api.exchange.bullish.com/trading-api/v1/nonce" \
  -H "Authorization: Bearer <JWT>"

Example Response

{
  "lowerBound": 1728000000000000,
  "upperBound": 1728086399999999
}

Trading API

Custody API

Aggregator API

Documentation Index

​GET /trading-api/v1/accounts/trading-accounts

​Response Fields (array of TradingAccountResponse)

​Example Request

​Example Response

​GET /trading-api/v1/accounts/trading-accounts/

​Path Parameters

​Example Request

​GET /trading-api/v1/accounts/asset

​Query Parameters

​Response Fields (array of AssetAccount objects)

​Example Request

​Example Response

​GET /trading-api/v1/accounts/asset/

​Path Parameters

​Query Parameters

​Example Request

​POST /trading-api/v1/command

​Query Parameters

​Request Headers

​Example Request Body

​Example Request

​GET /trading-api/v1/history/transfer

​Query Parameters

​Example Request

​POST /trading-api/v1/simulate-portfolio-margin

​Query Parameters

​Response Fields

​Example Request

​GET /trading-api/v1/assets

​Example Request

​GET /trading-api/v1/assets/

​Path Parameters

​Example Request

​GET /trading-api/v1/nonce

​Response Fields

​Example Request

​Example Response

Build docs developers (and LLMs) love

GET /trading-api/v1/accounts/trading-accounts

Response Fields (array of TradingAccountResponse)

Example Request

Example Response

GET /trading-api/v1/accounts/trading-accounts/

Path Parameters

Example Request

GET /trading-api/v1/accounts/asset

Query Parameters

Response Fields (array of AssetAccount objects)

Example Request

Example Response

GET /trading-api/v1/accounts/asset/

Path Parameters

Query Parameters

Example Request

POST /trading-api/v1/command

Query Parameters

Request Headers

Example Request Body

Example Request

GET /trading-api/v1/history/transfer

Query Parameters

Example Request

POST /trading-api/v1/simulate-portfolio-margin

Query Parameters

Response Fields

Example Request

GET /trading-api/v1/assets

Example Request

GET /trading-api/v1/assets/

Path Parameters

Example Request

GET /trading-api/v1/nonce

Response Fields

Example Request

Example Response