openapi: 3.2.0
info:
description: REST API specification for the Bullish Trading API.
version: 1.0.0
title: Bullish Trading Trades API
contact:
name: Bullish Help Center
email: support@bullish.com
url: https://support.bullish.com
servers:
- url: https://api.exchange.bullish.com/trading-api
description: PRODUCTION
- url: https://registered.api.exchange.bullish.com/trading-api
description: PRODUCTION
- url: https://prod.access.bullish.com/trading-api
description: PRODUCTION (Direct Connect)
- url: https://api.bugbounty.bullish.com/trading-api
description: SECURITY SANDBOX
- url: https://api.simnext.bullish-test.com/trading-api
description: API SANDBOX
- url: https://registered.api.simnext.bullish-test.com/trading-api
description: API SANDBOX
- url: https://simnext.access.bullish.com/trading-api
description: API SANDBOX (Direct Connect)
tags:
- name: trades
x-displayName: Trades
description: Authenticated APIs for reading trade data
paths:
/v1/trades:
get:
tags:
- trades
summary: Get Trades
description: 'Get a list of trades based on specified filters.
- requires [bearer token](/rest/authentication#add-authenticated-request-header) in authorization header
- Only the last 24 hours of data is available for querying
- [supports pagination](/rest/general/pagination)
- filtering on `createdAtDatetime`, `createdAtTimestamp` requires additional keywords, [see filtering support](/rest/general/filtering)
**Ratelimited:** `True`
'
operationId: getTrades
parameters:
- in: query
name: symbol
schema:
$ref: '#/components/schemas/MarketSymbol'
required: false
- in: query
name: orderId
description: unique order ID
schema:
$ref: '#/components/schemas/OrderID'
required: false
- in: query
name: clientOrderId
description: unique numeric (i64) identifier generated on the client side, only orderId or clientOrderId can be used
schema:
$ref: '#/components/schemas/OrderHandle'
required: false
- in: query
name: tradingAccountId
description: Id of the trading account
schema:
$ref: '#/components/schemas/TradingAccountId'
required: true
- in: query
name: otcTradeId
description: unique Bullish otc trade id
schema:
$ref: '#/components/schemas/OtcTradeId'
required: false
- in: query
name: clientOtcTradeId
description: unique client otc trade id
schema:
$ref: '#/components/schemas/ClientOtcTradeId'
required: false
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
minItems: 0
maxItems: 10
items:
$ref: '#/components/schemas/Trade'
'401':
description: Not Authenticated
'403':
description: Access Forbidden
'429':
description: Too Many Requests
'500':
description: Internal Server Error
security:
- jwtTokenAuth: []
/v1/trades/{tradeId}:
get:
parameters:
- in: path
name: tradeId
schema:
type: number
required: true
description: trade ID
- in: query
name: tradingAccountId
description: Id of the trading account
schema:
$ref: '#/components/schemas/TradingAccountId'
required: true
tags:
- trades
summary: Get Trade by ID
description: 'Gets a trade by ID, requires [bearer token](/rest/authentication#add-authenticated-request-header) in authorization header
**Ratelimited:** `True`
'
operationId: getTradeById
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Trade'
'401':
description: Not Authenticated
'403':
description: Access Forbidden
'404':
description: Resource Not Found
'429':
description: Too Many Requests
'500':
description: Internal Server Error
security:
- jwtTokenAuth: []
/v1/trades/client-order-id/{clientOrderId}:
get:
parameters:
- in: path
name: clientOrderId
schema:
$ref: '#/components/schemas/OrderHandle'
required: true
description: unique numeric (i64) identifier generated on the client side
- in: query
name: tradingAccountId
description: Id of the trading account
schema:
$ref: '#/components/schemas/TradingAccountId'
required: true
tags:
- trades
summary: Get Trades by clientOrder ID
description: 'Gets trade(s) associated with the clientOrderID, requires [bearer token](/rest/authentication#add-authenticated-request-header) in authorization header
**Ratelimited:** `True`
'
operationId: trade-get-trade-by-client-order-id
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Trade'
'401':
description: Not Authenticated
'403':
description: Access Forbidden
'404':
description: Resource Not Found
'429':
description: Too Many Requests
'500':
description: Internal Server Error
security:
- jwtTokenAuth: []
components:
schemas:
AssetValue:
description: see [asset value](/rest/general/price-quantity-precision) format
type: string
example: '1.00000000'
QuoteAssetSymbol:
type: string
description: asset symbol as denoted in the world
example: USDC
OtcTradeId:
type: string
description: unique numeric (i64) identifier generated on Bullish side expressed as a string value
example: '200000000000000098'
OrderHandle:
description: Unique numeric (i64) identifier generated on the client side expressed as a string value
type: string
example: '299834741023572480'
Trade:
type: object
required:
- tradeId
- orderId
- clientOrderId
- symbol
- price
- quantity
- quoteAmount
- baseFee
- quoteFee
- side
- isTaker
- tradeRebateAmount
- tradeRebateAssetSymbol
- otcMatchId
- otcTradeId
- clientOtcTradeId
- createdAtTimestamp
- createdAtDatetime
properties:
tradeId:
description: unique trade ID
allOf:
- $ref: '#/components/schemas/TradeID'
orderId:
description: unique order ID
allOf:
- $ref: '#/components/schemas/OrderID'
clientOrderId:
description: unique numeric (i64) identifier generated on the client side
allOf:
- $ref: '#/components/schemas/OrderHandle'
symbol:
description: market symbol
allOf:
- $ref: '#/components/schemas/MarketSymbol'
price:
description: price, see [asset value](/rest/general/price-quantity-precision) format
allOf:
- $ref: '#/components/schemas/AssetValue'
quantity:
description: quantity, see [asset value](/rest/general/price-quantity-precision) format
allOf:
- $ref: '#/components/schemas/AssetValue'
quoteAmount:
description: quote quantity deducted from asset account, see [asset value](/rest/general/price-quantity-precision) format
allOf:
- $ref: '#/components/schemas/AssetValue'
baseFee:
description: base fee, see [asset value](/rest/general/price-quantity-precision) format
allOf:
- $ref: '#/components/schemas/AssetValue'
quoteFee:
description: quote fee, see [asset value](/rest/general/price-quantity-precision) format
allOf:
- $ref: '#/components/schemas/AssetValue'
side:
description: order side
allOf:
- $ref: '#/components/schemas/OrderSideAsString'
example: BUY
isTaker:
description: denotes whether this is a taker's trade
allOf:
- $ref: '#/components/schemas/Boolean'
tradeRebateAmount:
description: amount of rebate that is credited to the user as part of the trade.
allOf:
- $ref: '#/components/schemas/AssetValue'
tradeRebateAssetSymbol:
description: the symbol of the asset in which the rebate is paid
allOf:
- $ref: '#/components/schemas/QuoteAssetSymbol'
otcMatchId:
description: unique OTC match ID.
allOf:
- $ref: '#/components/schemas/OtcMatchId'
otcTradeId:
description: unique Bullish OTC trade ID
allOf:
- $ref: '#/components/schemas/OtcTradeId'
clientOtcTradeId:
description: unique Client OTC trade ID
allOf:
- $ref: '#/components/schemas/ClientOtcTradeId'
createdAtDatetime:
description: denotes the time the trade was executed by the exchange, ISO 8601 with millisecond as string
allOf:
- $ref: '#/components/schemas/DateTime'
createdAtTimestamp:
description: denotes the time the trade was executed by the exchange
allOf:
- $ref: '#/components/schemas/TimeStampAsString'
TimeStampAsString:
type: string
format: string
example: '1621490985000'
description: unsigned 64 bit integer value which is the number of milliseconds since EPOCH expressed as string
OrderSideAsString:
type: string
description: order side can have the following string values `"BUY"`, `"SELL"`
example: BUY
TradeID:
type: string
example: '100020000000000060'
OrderID:
type: string
example: '297735387747975680'
OtcMatchId:
type: string
description: unique numeric (i64) identifier generated on Bullish side expressed as a string value
example: '15'
ClientOtcTradeId:
type: string
description: unique numeric (i64) identifier generated on the client side expressed as a string value
example: '20050900225'
TradingAccountId:
description: unique trading account ID
type: string
example: '111000000000001'
MarketSymbol:
type: string
description: market symbol. E.g. `BTCUSDC`
example: BTCUSDC
Boolean:
type: boolean
format: true or false
example: true
DateTime:
type: string
format: date-time
example: '2025-05-20T01:01:01.000Z'
description: ISO 8601 with millisecond as string
securitySchemes:
jwtTokenAuth:
type: http
scheme: bearer
bearerFormat: JWT
x-tagGroups:
- name: Public Endpoints
tags:
- general
- asset-data
- market-data
- market-history-data
- index-price-data
- derivatives-public
- auction-public
- name: Private Endpoints
tags:
- session-management
- trading-accounts
- account-assets
- orders
- trades
- amm-instructions
- transfer
- custody
- derivatives
- market-maker-protection
- history
- otc
- idb
- portfolio-margin-simulator