Authenticated API for submitting commands into the exchange.
openapi: 3.2.0
info:
description: REST API specification for the Bullish Trading API.
version: 1.0.0
title: Bullish Trading command entry 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: command entry
x-displayName: Command Entry
description: Authenticated API for submitting commands into the exchange.
paths:
/v2/command:
post:
tags:
- command entry
summary: Create Command
description: "Submits a command to the trading engine. A successful response indicates that the command entry was acknowledged \nbut does not indicate that the command was executed. \nThis endpoint uses the [signing format](/rest/authentication#signing-format) which does not require strict field \nordering and addition of null fields in the request body. Quantities and prices does not require strict precision. \nE.g. for asset precision of 4 - `100`, `100.0`, `100.00`, `100.000` and `100.0000` are all accepted.\n\nCommand schemas and examples are provided below. Supported commands:\n- V3CancelOrder\n- V1CancelAllOrders\n- V1CancelAllOrdersByMarket\n- V1DelayedCancelAllOrders\n- V1UnsetDelayedCancelAllOrders\n- V1AmendOrder\n- V3TerminateAMMInstruction\n- V2TransferAsset\n\nRequires\n- [bearer token](/rest/authentication#add-authenticated-request-header) in authorization header\n\n**Ratelimited:** `True`. Higher tiers of rate limits available by providing the `BX-RATELIMIT-TOKEN` request header.\n"
operationId: submitCommand
parameters:
- $ref: '#/components/parameters/BX-SIGNATURE'
- $ref: '#/components/parameters/BX-TIMESTAMP'
- $ref: '#/components/parameters/BX-NONCE'
- $ref: '#/components/parameters/BX-NONCE-WINDOW-ENABLED'
responses:
'200':
description: Status OK. This means a command was successfully acknowledged.
content:
application/json:
schema:
discriminator:
propertyName: commandType
mapping:
V3CancelOrder: '#/components/schemas/CancelOrderCommandResponseV3'
V1CancelAllOrders: '#/components/schemas/CancelAllOrdersCommandResponse'
V1CancelAllOrdersByMarket: '#/components/schemas/CancelAllOrdersByMarketResponse'
V1DelayedCancelAllOrders: '#/components/schemas/DelayedCancelAllOrdersResponse'
V1UnsetDelayedCancelAllOrders: '#/components/schemas/UnsetDelayedCancelAllOrdersResponse'
V3TerminateAMMInstruction: '#/components/schemas/TerminateAMMInstructionCommandResponseV3'
V2TransferAsset: '#/components/schemas/TradingAccountTransferResponse'
V1AmendOrder: '#/components/schemas/AmendOrderCommandResponseV1'
oneOf:
- $ref: '#/components/schemas/CancelOrderCommandResponseV3'
- $ref: '#/components/schemas/CancelAllOrdersCommandResponse'
- $ref: '#/components/schemas/CancelAllOrdersByMarketResponse'
- $ref: '#/components/schemas/DelayedCancelAllOrdersResponse'
- $ref: '#/components/schemas/UnsetDelayedCancelAllOrdersResponse'
- $ref: '#/components/schemas/TerminateAMMInstructionCommandResponseV3'
- $ref: '#/components/schemas/TradingAccountTransferResponse'
- $ref: '#/components/schemas/AmendOrderCommandResponseV1'
examples:
CancelOrderCommand:
$ref: '#/components/examples/CancelOrderCommandResponse'
CancelAllOrdersCommand:
$ref: '#/components/examples/CancelAllOrdersCommandResponse'
CancelAllOrdersByMarketCommand:
$ref: '#/components/examples/CancelAllOrdersByMarketCommandResponse'
DelayedCancelAllOrdersCommand:
$ref: '#/components/examples/DelayedCancelAllOrdersCommandResponse'
UnsetDelayedCancelAllOrdersCommand:
$ref: '#/components/examples/UnsetDelayedCancelAllOrdersCommandResponse'
TerminateAMMInstructionCommand:
$ref: '#/components/examples/TerminateAMMInstructionCommandResponse'
TransferAssetCommand:
$ref: '#/components/examples/TransferAssetCommandResponse'
AmendOrderCommand:
$ref: '#/components/examples/AmendOrderCommandResponse'
'400':
description: 'Bad Request
For example, sending a request with the `BX-SIGNATURE` header missing will result in the following response:
'
content:
application/json:
schema:
$ref: '#/components/schemas/BadOrderEntryResponse'
'401':
description: Not Authenticated
'403':
description: Access Forbidden
'429':
description: Too Many Requests
'500':
description: Internal Server Error
requestBody:
required: true
content:
application/json:
schema:
discriminator:
propertyName: commandType
mapping:
V3CancelOrder: '#/components/schemas/CancelOrderCommandV3'
V1CancelAllOrders: '#/components/schemas/CancelAllOrdersCommand'
V1CancelAllOrdersByMarket: '#/components/schemas/CancelAllOrdersByMarketCommand'
V1DelayedCancelAllOrders: '#/components/schemas/DelayedCancelAllOrdersCommand'
V1UnsetDelayedCancelAllOrders: '#/components/schemas/UnsetDelayedCancelAllOrdersCommand'
V3TerminateAMMInstruction: '#/components/schemas/TerminateAMMInstructionCommandV3'
V2TransferAsset: '#/components/schemas/TransferAssetCommandV2'
V1AmendOrder: '#/components/schemas/AmendOrderCommandV1'
oneOf:
- $ref: '#/components/schemas/CancelOrderCommandV3'
- $ref: '#/components/schemas/CancelAllOrdersCommand'
- $ref: '#/components/schemas/CancelAllOrdersByMarketCommand'
- $ref: '#/components/schemas/DelayedCancelAllOrdersCommand'
- $ref: '#/components/schemas/UnsetDelayedCancelAllOrdersCommand'
- $ref: '#/components/schemas/TerminateAMMInstructionCommandV3'
- $ref: '#/components/schemas/TransferAssetCommandV2'
- $ref: '#/components/schemas/AmendOrderCommandV1'
examples:
CancelOrderCommand:
$ref: '#/components/examples/CancelOrderCommand'
CancelAllOrdersCommand:
$ref: '#/components/examples/CancelAllOrdersCommand'
CancelAllOrdersByMarketCommand:
$ref: '#/components/examples/CancelAllOrdersByMarketCommand'
DelayedCancelAllOrdersCommand:
$ref: '#/components/examples/DelayedCancelAllOrdersCommand'
UnsetDelayedCancelAllOrdersCommand:
$ref: '#/components/examples/UnsetDelayedCancelAllOrdersCommand'
AmendOrderCommand:
$ref: '#/components/examples/AmendOrderCommand'
TerminateAMMInstructionCommand:
$ref: '#/components/examples/TerminateAMMInstructionCommand'
TransferAssetCommand:
$ref: '#/components/examples/TransferAssetCommand'
security:
- jwtTokenAuth: []
components:
schemas:
RequestID:
type: string
example: '197735387747975680'
CancelAllOrdersByMarketCommand:
type: object
required:
- commandType
- symbol
- tradingAccountId
properties:
commandType:
description: The command type, it must be 'V1CancelAllOrdersByMarket'
type: string
enum:
- V1CancelAllOrdersByMarket
symbol:
description: market symbol. E.g. `BTCUSDC`
allOf:
- $ref: '#/components/schemas/MarketSymbol'
tradingAccountId:
description: unique trading account Id
allOf:
- $ref: '#/components/schemas/TradingAccountId'
example:
commandType: V1CancelAllOrdersByMarket
symbol: BTCUSDC
tradingAccountId: '111000000000001'
TradingAccountTransferResponse:
type: object
required:
- commandType
- message
- requestId
properties:
commandType:
description: The command type
type: string
enum:
- V2TransferAsset
message:
description: message
type: string
requestId:
description: unique request ID
allOf:
- $ref: '#/components/schemas/RequestID'
example:
commandType: V2TransferAsset
message: Command acknowledged - TransferAsset
requestId: '633909659774222336'
CancelOrderCommandResponseV3:
type: object
required:
- commandType
- message
- requestId
properties:
commandType:
description: The command type
type: string
enum:
- V3CancelOrder
message:
description: message
type: string
requestId:
description: unique request ID
allOf:
- $ref: '#/components/schemas/RequestID'
orderId:
description: unique order ID
allOf:
- $ref: '#/components/schemas/OrderID'
clientOrderId:
description: unique numeric identifier generated on the client side expressed as a string value
type: string
example:
commandType: V3CancelOrder
message: Command acknowledged - CancelOrder
requestId: '633910976353665024'
orderId: '633910775316480001'
OrderHandle:
description: Unique numeric (i64) identifier generated on the client side expressed as a string value
type: string
example: '299834741023572480'
TerminateAMMInstructionCommandV3:
type: object
required:
- commandType
- instructionId
- symbol
- tradingAccountId
properties:
commandType:
description: The command type, it must be 'V3TerminateAMMInstruction'
type: string
enum:
- V3TerminateAMMInstruction
instructionId:
description: unique AMM instruction ID
allOf:
- $ref: '#/components/schemas/AMMInstructionID'
symbol:
allOf:
- $ref: '#/components/schemas/MarketSymbol'
tradingAccountId:
allOf:
- $ref: '#/components/schemas/TradingAccountId'
example:
commandType: V3TerminateAMMInstruction
instructionId: '297735387747975680'
symbol: BTCUSDC
tradingAccountId: '111000000000001'
AMMInstructionID:
type: string
example: '297735387747975680'
OrderID:
type: string
example: '297735387747975680'
TransferAssetCommandV2:
type: object
required:
- commandType
- assetSymbol
- quantity
- fromTradingAccountId
- toTradingAccountId
properties:
commandType:
description: The command type, e.g. 'V2TransferAsset'
type: string
enum:
- V2TransferAsset
assetSymbol:
description: Symbol of the asset. i.e. currency
allOf:
- $ref: '#/components/schemas/AssetSymbol'
quantity:
description: "Quantity of the asset. Can be representated with any number of trailing zeroes up to asset precision \n(eg `100.1`, `100.10`, `100.100`, `100.1000` are valid for asset precision 4)\n"
type: string
fromTradingAccountId:
description: Source of the asset transfer
allOf:
- $ref: '#/components/schemas/TradingAccountId'
toTradingAccountId:
description: Destination of the asset transfer
allOf:
- $ref: '#/components/schemas/TradingAccountId'
example:
commandType: V2TransferAsset
assetSymbol:
$ref: '#/components/schemas/AssetSymbol/example'
quantity: '100.1'
fromTradingAccountId:
$ref: '#/components/schemas/TradingAccountId/example'
toTradingAccountId: '111000000000002'
CancelOrderCommandV3:
type: object
required:
- commandType
- tradingAccountId
- symbol
properties:
commandType:
description: The command type, it must be 'V3CancelOrder'
type: string
enum:
- V3CancelOrder
orderId:
description: Unique order ID, only orderId or clientOrderId can be used in the V3CancelOrder command
allOf:
- $ref: '#/components/schemas/OrderID'
clientOrderId:
description: Unique numeric (i64) identifier generated on the client side expressed as a string value, only orderId or clientOrderId can be used in the V3CancelOrder command
allOf:
- $ref: '#/components/schemas/OrderHandle'
symbol:
allOf:
- $ref: '#/components/schemas/MarketSymbol'
tradingAccountId:
allOf:
- $ref: '#/components/schemas/TradingAccountId'
example:
commandType: V3CancelOrder
orderId: '297735387747975680'
symbol: BTCUSDC
tradingAccountId: '111000000000001'
BadOrderEntryResponse:
type: object
required:
- message
- errorCode
- errorCodeName
properties:
message:
description: message
type: string
example: Missing signature header
errorCode:
description: unique error code
type: integer
example: 6029
errorCodeName:
description: unique error code name
type: string
example: MISSING_SIGNATURE_HEADER
TerminateAMMInstructionCommandResponseV3:
type: object
required:
- commandType
- message
- requestId
- instructionId
properties:
commandType:
description: The command type
type: string
enum:
- V3TerminateAMMInstruction
message:
description: message
type: string
requestId:
description: unique request ID
allOf:
- $ref: '#/components/schemas/RequestID'
instructionId:
description: unique AMM instruction ID
allOf:
- $ref: '#/components/schemas/AMMInstructionID'
example:
commandType: V3TerminateAMMInstruction
message: Command acknowledged - TerminateAMMInstruction
requestId: '633906221577404416'
instructionId: '633906221577404424'
CancelAllOrdersCommand:
type: object
required:
- commandType
- tradingAccountId
properties:
commandType:
description: The command type, it must be 'V1CancelAllOrders'
type: string
enum:
- V1CancelAllOrders
tradingAccountId:
description: Unique trading account Id
allOf:
- $ref: '#/components/schemas/TradingAccountId'
example:
commandType: V1CancelAllOrders
tradingAccountId: '111000000000001'
UnsetDelayedCancelAllOrdersResponse:
type: object
required:
- commandType
- message
- requestId
properties:
commandType:
description: The command type
type: string
enum:
- V1UnsetDelayedCancelAllOrders
message:
description: message
type: string
requestId:
description: unique request ID
allOf:
- $ref: '#/components/schemas/RequestID'
example:
commandType: V1UnsetDelayedCancelAllOrders
message: Command acknowledged - UnsetDelayedCancelAllOrders
requestId: '633910976353665024'
AmendOrderCommandResponseV1:
type: object
required:
- commandType
- message
- requestId
- orderId
properties:
commandType:
description: The command type
type: string
enum:
- V1AmendOrder
message:
description: message
type: string
requestId:
description: unique request ID
allOf:
- $ref: '#/components/schemas/RequestID'
orderId:
description: unique order ID
allOf:
- $ref: '#/components/schemas/OrderID'
clientOrderId:
description: Will be updated as part of a successful order amendment
type: string
example:
commandType: V1AmendOrder
message: Command acknowledged - AmendOrder
requestId: '633910976353665024'
orderId: '633910775316480001'
clientOrderId: 1234567-1
AssetValue:
description: see [asset value](/rest/general/price-quantity-precision) format
type: string
example: '1.00000000'
UnsetDelayedCancelAllOrdersCommand:
type: object
required:
- commandType
- tradingAccountId
properties:
commandType:
description: The command type, it must be 'V1UnsetDelayedCancelAllOrders'
type: string
enum:
- V1UnsetDelayedCancelAllOrders
example: V1UnsetDelayedCancelAllOrders
tradingAccountId:
allOf:
- $ref: '#/components/schemas/TradingAccountId'
example:
commandType: V1UnsetDelayedCancelAllOrders
tradingAccountId: '111000000000001'
TradingAccountId:
description: unique trading account ID
type: string
example: '111000000000001'
AmendOrderCommandV1:
type: object
required:
- commandType
- symbol
- tradingAccountId
properties:
commandType:
description: The command type, it must be 'V1AmendOrder'
type: string
enum:
- V1AmendOrder
orderId:
description: unique order ID
allOf:
- $ref: '#/components/schemas/OrderID'
symbol:
allOf:
- $ref: '#/components/schemas/MarketSymbol'
type:
allOf:
- $ref: '#/components/schemas/OrderTypeAsStringAmend'
price:
description: price
allOf:
- $ref: '#/components/schemas/AssetValue'
clientOrderId:
description: unique numeric identifier generated on the client side expressed as a string value
type: string
quantity:
description: quantity
allOf:
- $ref: '#/components/schemas/AssetValue'
tradingAccountId:
allOf:
- $ref: '#/components/schemas/TradingAccountId'
example:
commandType: V1AmendOrder
orderId: '297735387747975680'
symbol: BTCUSDC
type: LIMIT
price: '1.00000000'
clientOrderId: '633914459442118656'
quantity: '1.00000000'
tradingAccountId: '111000000000001'
AssetSymbol:
type: string
description: asset symbol as denoted in the world
example: BTC
DelayedCancelAllOrdersCommand:
type: object
required:
- commandType
- delayBySeconds
- tradingAccountId
properties:
commandType:
description: The command type, it must be 'V1DelayedCancelAllOrders'
type: string
enum:
- V1DelayedCancelAllOrders
example: V1DelayedCancelAllOrders
cancelId:
allOf:
- $ref: '#/components/schemas/CancelId'
delayBySeconds:
description: Delay of the cancel-all-order in seconds
allOf:
- $ref: '#/components/schemas/DelayBySeconds'
tradingAccountId:
allOf:
- $ref: '#/components/schemas/TradingAccountId'
example:
commandType: V1DelayedCancelAllOrders
delayBySeconds: '5'
tradingAccountId: '111000000000001'
CancelAllOrdersByMarketResponse:
type: object
required:
- commandType
- message
- requestId
properties:
commandType:
description: The command type
type: string
enum:
- V1CancelAllOrdersByMarket
message:
description: message
type: string
requestId:
description: unique request ID
allOf:
- $ref: '#/components/schemas/RequestID'
example:
commandType: V1CancelAllOrdersByMarket
message: Command acknowledged - CancelAllOrdersByMarket
requestId: '633914459442118656'
DelayedCancelAllOrdersResponse:
type: object
required:
- commandType
- message
- requestId
properties:
commandType:
description: The command type
type: string
enum:
- V1DelayedCancelAllOrders
message:
description: message
type: string
requestId:
description: unique request ID
allOf:
- $ref: '#/components/schemas/RequestID'
example:
commandType: V1DelayedCancelAllOrders
message: Command acknowledged - DelayedCancelAllOrders
requestId: '633910976353665024'
CancelId:
description: Unique id for this cancel request which is an unsigned 64 bit integer expressed as string
type: string
example: '123456789'
DelayBySeconds:
description: Delay the cancel-all-orders request by (seconds) as a timeout mechanism
type: string
enum:
- '5'
- '10'
- '15'
- '20'
- '25'
- '30'
- '40'
- '50'
- '60'
example: '5'
CancelAllOrdersCommandResponse:
type: object
required:
- commandType
- message
- requestId
properties:
commandType:
description: The command type
type: string
enum:
- V1CancelAllOrders
message:
description: message
type: string
requestId:
description: unique request ID
allOf:
- $ref: '#/components/schemas/RequestID'
example:
commandType: V1CancelAllOrders
message: Command acknowledged - CancelAllOrders
requestId: '633910976353665024'
OrderTypeAsStringAmend:
type: string
description: order type can have the following string values `"LIMIT"`, `"POST_ONLY"`
example: LIMIT
MarketSymbol:
type: string
description: market symbol. E.g. `BTCUSDC`
example: BTCUSDC
examples:
TerminateAMMInstructionCommandResponse:
value:
$ref: '#/components/schemas/TerminateAMMInstructionCommandResponseV3/example'
DelayedCancelAllOrdersCommand:
value:
$ref: '#/components/schemas/DelayedCancelAllOrdersCommand/example'
TransferAssetCommandResponse:
value:
$ref: '#/components/schemas/TradingAccountTransferResponse/example'
AmendOrderCommandResponse:
value:
$ref: '#/components/schemas/AmendOrderCommandResponseV1/example'
CancelOrderCommand:
description: Only one of `orderId` or `clientOrderId` can be used in the cancel order command
value:
$ref: '#/components/schemas/CancelOrderCommandV3/example'
CancelOrderCommandResponse:
description: Only one of `orderId` or `clientOrderId` present
value:
$ref: '#/components/schemas/CancelOrderCommandResponseV3/example'
CancelAllOrdersByMarketCommand:
value:
$ref: '#/components/schemas/CancelAllOrdersByMarketCommand/example'
CancelAllOrdersByMarketCommandResponse:
value:
$ref: '#/components/schemas/CancelAllOrdersByMarketResponse/example'
CancelAllOrdersCommand:
value:
$ref: '#/components/schemas/CancelAllOrdersCommand/example'
CancelAllOrdersCommandResponse:
value:
$ref: '#/components/schemas/CancelAllOrdersCommandResponse/example'
TransferAssetCommand:
value:
$ref: '#/components/schemas/TransferAssetCommandV2/example'
DelayedCancelAllOrdersCommandResponse:
value:
$ref: '#/components/schemas/DelayedCancelAllOrdersResponse/example'
UnsetDelayedCancelAllOrdersCommand:
value:
$ref: '#/components/schemas/UnsetDelayedCancelAllOrdersCommand/example'
TerminateAMMInstructionCommand:
value:
$ref: '#/components/schemas/TerminateAMMInstructionCommandV3/example'
AmendOrderCommand:
value:
$ref: '#/components/schemas/AmendOrderCommandV1/example'
UnsetDelayedCancelAllOrdersCommandResponse:
value:
$ref: '#/components/schemas/UnsetDelayedCancelAllOrdersResponse/example'
parameters:
BX-NONCE:
in: header
name: BX-NONCE
description: nonce is a client side incremented unsigned 64 bit integer
required: true
schema:
type: string
BX-NONCE-WINDOW-ENABLED:
in: header
name: BX-NONCE-WINDOW-ENABLED
description: 'string representation of a boolean value, [enables out-of-order order requests to be processed](/rest/order-processing-create-cancel-request-mechanism)
'
schema:
type: string
enum:
- 'false'
- 'true'
default: 'false'
BX-SIGNATURE:
in: header
name: BX-SIGNATURE
description: signature obtained using the [signing format](/rest/authentication#signing-format)
required: true
schema:
type: string
BX-TIMESTAMP:
in: header
name: BX-TIMESTAMP
description: timestamp is the number of milliseconds since EPOCH
required: true
schema:
type: 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