Bullish command entry API

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

        but does not indicate that the command was executed.

        This endpoint uses the signing format which does not require strict field

        ordering and addition of null fields in the request body. Quantities and prices does not require strict precision.

        E.g. for asset precision of 4 - `100`, `100.0`, `100.00`, `100.000` and `100.0000` are all accepted.


        Command schemas and examples are provided below. Supported commands:

        - V3CancelOrder

        - V1CancelAllOrders

        - V1CancelAllOrdersByMarket

        - V1DelayedCancelAllOrders

        - V1UnsetDelayedCancelAllOrders

        - V1AmendOrder

        - V3TerminateAMMInstruction

        - V2TransferAsset


        Requires

        - bearer token in authorization header


        **Ratelimited:** `True`. Higher tiers of rate limits available by providing the `BX-RATELIMIT-TOKEN` request header.'
      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:
    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'
    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'
    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'
    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'
    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
    OrderHandle:
      description: Unique numeric (i64) identifier generated on the client side expressed as a string value
      type: string
      example: '299834741023572480'
    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'
    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'
    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'
    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'
    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'
    MarketSymbol:
      type: string
      description: market symbol. E.g. `BTCUSDC`
      example: BTCUSDC
    AssetSymbol:
      type: string
      description: asset symbol as denoted in the world
      example: BTC
    RequestID:
      type: string
      example: '197735387747975680'
    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
    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'
    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'
    TradingAccountId:
      description: unique trading account ID
      type: string
      example: '111000000000001'
    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'
    OrderID:
      type: string
      example: '297735387747975680'
    AMMInstructionID:
      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'
    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'
    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'
    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'
    AssetValue:
      description: see [asset value](/rest/general/price-quantity-precision) format
      type: string
      example: '1.00000000'
    OrderTypeAsStringAmend:
      type: string
      description: order type can have the following string values `"LIMIT"`, `"POST_ONLY"`
      example: LIMIT
  examples:
    DelayedCancelAllOrdersCommand:
      value:
        $ref: '#/components/schemas/DelayedCancelAllOrdersCommand/example'
    DelayedCancelAllOrdersCommandResponse:
      value:
        $ref: '#/components/schemas/DelayedCancelAllOrdersResponse/example'
    CancelOrderCommandResponse:
      description: Only one of `orderId` or `clientOrderId` present
      value:
        $ref: '#/components/schemas/CancelOrderCommandResponseV3/example'
    CancelAllOrdersCommandResponse:
      value:
        $ref: '#/components/schemas/CancelAllOrdersCommandResponse/example'
    CancelAllOrdersByMarketCommandResponse:
      value:
        $ref: '#/components/schemas/CancelAllOrdersByMarketResponse/example'
    CancelAllOrdersByMarketCommand:
      value:
        $ref: '#/components/schemas/CancelAllOrdersByMarketCommand/example'
    CancelOrderCommand:
      description: Only one of `orderId` or `clientOrderId` can be used in the cancel order command
      value:
        $ref: '#/components/schemas/CancelOrderCommandV3/example'
    TransferAssetCommandResponse:
      value:
        $ref: '#/components/schemas/TradingAccountTransferResponse/example'
    AmendOrderCommandResponse:
      value:
        $ref: '#/components/schemas/AmendOrderCommandResponseV1/example'
    TerminateAMMInstructionCommand:
      value:
        $ref: '#/components/schemas/TerminateAMMInstructionCommandV3/example'
    UnsetDelayedCancelAllOrdersCommandResponse:
      value:
        $ref: '#/components/schemas/UnsetDelayedCancelAllOrdersResponse/example'
    UnsetDelayedCancelAllOrdersCommand:
      value:
        $ref: '#/components/schemas/UnsetDelayedCancelAllOrdersCommand/example'
    TransferAssetCommand:
      value:
        $ref: '#/components/schemas/TransferAssetCommandV2/example'
    CancelAllOrdersCommand:
      value:
        $ref: '#/components/schemas/CancelAllOrdersCommand/example'
    AmendOrderCommand:
      value:
        $ref: '#/components/schemas/AmendOrderCommandV1/example'
    TerminateAMMInstructionCommandResponse:
      value:
        $ref: '#/components/schemas/TerminateAMMInstructionCommandResponseV3/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-TIMESTAMP:
      in: header
      name: BX-TIMESTAMP
      description: timestamp is the number of milliseconds since EPOCH
      required: true
      schema:
        type: string
    BX-SIGNATURE:
      in: header
      name: BX-SIGNATURE
      description: signature obtained using the [signing format](/rest/authentication#signing-format)
      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'
  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