OTC Trade Endpoints — Create, Query, and Cancel OTC Trades

The OTC API allows institutional clients to submit, track, and cancel over-the-counter trades via the Bullish OTC Clearing Facility. OTC trades are bilaterally agreed off-book transactions where both counterparties submit matching legs with a shared sharedMatchKey. All OTC endpoints require a valid bearer JWT.

GET /trading-api/v2/otc-trades

Returns a paginated list of OTC trades for the authenticated trading account. Supports filtering on status, tradingAccountId, sharedMatchKey, clientOtcTradeId, createdAtDatetime, and createdAtTimestamp.

Authentication: Required.

Query Parameters

tradingAccountId

string

required

ID of the trading account.

status

string

Filter by OTC trade status. One of COUNTERPARTY_PENDING, COUNTERPARTY_PAIRED, RISK_PENDING, MATCHED, CANCELLED, REJECTED.

sharedMatchKey

string

Shared match key used to correlate counterparty legs.

clientOtcTradeId

string

Filter by unique client OTC trade ID.

createdAtDatetime[gte]

string

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

createdAtDatetime[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 of OtcTradeView objects)

otcTradeId

string

Unique Bullish OTC trade ID.

clientOtcTradeId

string

Client-side unique OTC trade ID.

sharedMatchKey

string

Shared key used to match the two counterparty legs. E.g. "cfBtcXrpMatch001".

status

string

Current OTC trade status. One of COUNTERPARTY_PENDING, COUNTERPARTY_PAIRED, RISK_PENDING, MATCHED, CANCELLED, REJECTED.

statusReason

string

Human-readable status description. E.g. "Ok".

statusReasonCode

string

Numeric status reason code. See Error & Rejection Codes.

createdAtDatetime

string

ISO 8601 datetime when the OTC trade was acknowledged by the exchange.

createdAtTimestamp

string

Millisecond EPOCH timestamp when the OTC trade was acknowledged.

expireDatetime

string

ISO 8601 datetime when this OTC trade expires if unmatched.

expireTimestamp

string

Millisecond EPOCH timestamp of OTC trade expiry.

remarks

string

Optional free-text remarks attached to the OTC trade.

trades

array

Individual trade legs included in this OTC trade.

Show Trade leg fields

tradeId

string

Unique trade ID assigned after matching.

symbol

string

Market symbol for this leg. E.g. BTC-USDC-PERP.

price

string

Agreed execution price.

quantity

string

Agreed quantity.

quoteAmount

string

Notional value in quote or settlement asset.

baseFee

string

Base asset fee for this leg.

quoteFee

string

Quote asset fee for this leg.

side

string

BUY or SELL.

isTaker

boolean

Whether this account is the taker on this leg.

Example Request

curl -X GET "https://api.exchange.bullish.com/trading-api/v2/otc-trades?tradingAccountId=111000000000001&status=MATCHED" \
  -H "Authorization: Bearer <JWT>"

Example Response

[
  {
    "otcTradeId": "720551234567890001",
    "clientOtcTradeId": "20050900225",
    "sharedMatchKey": "cfBtcXrpMatch001",
    "status": "MATCHED",
    "statusReason": "Ok",
    "statusReasonCode": "1002",
    "createdAtDatetime": "2024-10-04T08:00:00.000Z",
    "createdAtTimestamp": "1728028800000",
    "expireDatetime": "2024-10-04T08:01:00.000Z",
    "expireTimestamp": "1728028860000",
    "remarks": "first otc trade with xyz client",
    "trades": [
      {
        "tradeId": "720551234567890002",
        "symbol": "BTC-USDC-PERP",
        "price": "98213.00000",
        "quantity": "1.5000",
        "quoteAmount": "147319.5000",
        "baseFee": "0.00000000",
        "quoteFee": "14.7320",
        "side": "BUY",
        "isTaker": true
      }
    ]
  }
]

POST /trading-api/v2/otc-trades

Creates an OTC trade. A 200 response confirms the command was acknowledged. Use GET /trading-api/v2/otc-trades/ with the returned otcTradeId or clientOtcTradeId to check status. Both counterparties must submit matching legs using the same sharedMatchKey. One party must set isTaker: true and the other isTaker: false for the trade to match on the OTC Clearing Facility.

Authentication: Required.

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.

Request Body Fields

commandType

string

required

Must be "V1CreateOtcTrade".

tradingAccountId

string

required

ID of the trading account submitting this leg.

sharedMatchKey

string

required

Shared key agreed with the counterparty to correlate both legs. E.g. "cfBtcXrpMatch001".

isTaker

boolean

required

Whether this account is the taker on the trade. The counterparty must submit the inverse value.

trades

array

required

Array of trade legs to include in this OTC trade.

Show Trade leg fields

symbol

string

required

Market symbol. E.g. "BTC-USDC-PERP".

side

string

required

"BUY" or "SELL".

price

string

required

Agreed price. E.g. "98213.00000".

quantity

string

required

Agreed quantity. E.g. "1.5000".

clientOtcTradeId

string

Client-side unique identifier for this OTC trade. E.g. "20050900225".

remarks

string

Free-text remarks. E.g. "first otc trade with xyz client".

Response Fields

message

string

Message indicating the status of the request. E.g. "Command acknowledged - CreateOtcTrade".

requestId

string

Unique request ID assigned by the exchange.

otcTradeId

string

Unique Bullish OTC trade ID — use for status queries.

clientOtcTradeId

string

Client-side OTC trade ID echoed from the request.

sharedMatchKey

string

Shared match key echoed from the request.

Example Request

curl -X POST "https://api.exchange.bullish.com/trading-api/v2/otc-trades" \
  -H "Authorization: Bearer <JWT>" \
  -H "BX-SIGNATURE: <SIGNATURE>" \
  -H "BX-TIMESTAMP: 1728028800000" \
  -H "BX-NONCE: 1728028800000001" \
  -H "Content-Type: application/json" \
  -d '{
    "commandType": "V1CreateOtcTrade",
    "clientOtcTradeId": "20050900225",
    "sharedMatchKey": "cfBtcXrpMatch001",
    "tradingAccountId": "111000000000001",
    "isTaker": true,
    "remarks": "first otc trade with xyz client",
    "trades": [
      {
        "symbol": "BTC-USDC-PERP",
        "side": "BUY",
        "price": "98213.00000",
        "quantity": "1.5000"
      },
      {
        "symbol": "XRP-USDC-PERP",
        "side": "SELL",
        "price": "2.66000000",
        "quantity": "50.0000"
      }
    ]
  }'

Example Response

{
  "message": "Command acknowledged - CreateOtcTrade",
  "requestId": "720551234567890000",
  "otcTradeId": "720551234567890001",
  "clientOtcTradeId": "20050900225",
  "sharedMatchKey": "cfBtcXrpMatch001"
}

GET /trading-api/v2/otc-trades/

Retrieves a specific OTC trade by its exchange-assigned ID.

Authentication: Required.

Path Parameters

otcTradeId

string

required

Unique Bullish OTC trade ID.

Query Parameters

tradingAccountId

string

required

ID of the trading account.

Example Request

curl -X GET "https://api.exchange.bullish.com/trading-api/v2/otc-trades/720551234567890001?tradingAccountId=111000000000001" \
  -H "Authorization: Bearer <JWT>"

Example Response

{
  "otcTradeId": "720551234567890001",
  "clientOtcTradeId": "20050900225",
  "sharedMatchKey": "cfBtcXrpMatch001",
  "status": "MATCHED",
  "statusReason": "Ok",
  "statusReasonCode": "1001",
  "createdAtDatetime": "2024-10-04T08:00:00.000Z",
  "createdAtTimestamp": "1728028800000",
  "expireDatetime": "2024-10-04T08:01:00.000Z",
  "expireTimestamp": "1728028860000",
  "remarks": "first otc trade with xyz client",
  "trades": [
    {
      "tradeId": "720551234567890002",
      "symbol": "BTC-USDC-PERP",
      "price": "98213.00000",
      "quantity": "1.5000",
      "quoteAmount": "147319.5000",
      "baseFee": "0.00000000",
      "quoteFee": "14.7320",
      "side": "BUY",
      "isTaker": true
    },
    {
      "tradeId": "720551234567890003",
      "symbol": "XRP-USDC-PERP",
      "price": "2.66000000",
      "quantity": "50.0000",
      "quoteAmount": "133.0000",
      "baseFee": "0.00000000",
      "quoteFee": "0.0133",
      "side": "SELL",
      "isTaker": true
    }
  ]
}

POST /trading-api/v2/otc-command

Submits a cancellation command for an OTC trade. Supported command types are V1CancelOtcTrade (cancel a single OTC trade) and V1CancelAllOtcTrades (cancel all pending OTC trades for a trading account). A 200 response confirms acknowledgement only.

Authentication: Required.

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.

Cancel a Single OTC Trade

{
  "commandType": "V1CancelOtcTrade",
  "otcTradeId": "720551234567890001",
  "tradingAccountId": "111000000000001"
}

Cancel All OTC Trades

{
  "commandType": "V1CancelAllOtcTrades",
  "tradingAccountId": "111000000000001"
}

Example Request — Cancel Single OTC Trade

curl -X POST "https://api.exchange.bullish.com/trading-api/v2/otc-command" \
  -H "Authorization: Bearer <JWT>" \
  -H "BX-SIGNATURE: <SIGNATURE>" \
  -H "BX-TIMESTAMP: 1728028800000" \
  -H "BX-NONCE: 1728028800000002" \
  -H "Content-Type: application/json" \
  -d '{
    "commandType": "V1CancelOtcTrade",
    "otcTradeId": "720551234567890001",
    "tradingAccountId": "111000000000001"
  }'

Trading API

Custody API

Aggregator API

OTC Trade Endpoints — Create, Query, and Cancel OTC Trades

GET /trading-api/v2/otc-trades

Query Parameters

Response Fields (array of OtcTradeView objects)

Example Request

Example Response

POST /trading-api/v2/otc-trades

Request Headers

Request Body Fields

Response Fields

Example Request

Example Response

GET /trading-api/v2/otc-trades/

Path Parameters

Query Parameters

Example Request

Example Response

POST /trading-api/v2/otc-command

Request Headers

Cancel a Single OTC Trade

Cancel All OTC Trades

Example Request — Cancel Single OTC Trade

Build docs developers (and LLMs) love

Trading API

Custody API

Aggregator API

Documentation Index

​GET /trading-api/v2/otc-trades

​Query Parameters

​Response Fields (array of OtcTradeView objects)

​Example Request

​Example Response

​POST /trading-api/v2/otc-trades

​Request Headers

​Request Body Fields

​Response Fields

​Example Request

​Example Response

​GET /trading-api/v2/otc-trades/

​Path Parameters

​Query Parameters

​Example Request

​Example Response

​POST /trading-api/v2/otc-command

​Request Headers

​Cancel a Single OTC Trade

​Cancel All OTC Trades

​Example Request — Cancel Single OTC Trade

Build docs developers (and LLMs) love

GET /trading-api/v2/otc-trades

Query Parameters

Response Fields (array of OtcTradeView objects)

Example Request

Example Response

POST /trading-api/v2/otc-trades

Request Headers

Request Body Fields

Response Fields

Example Request

Example Response

GET /trading-api/v2/otc-trades/

Path Parameters

Query Parameters

Example Request

Example Response

POST /trading-api/v2/otc-command

Request Headers

Cancel a Single OTC Trade

Cancel All OTC Trades

Example Request — Cancel Single OTC Trade