WhiteBit Place Spot Stop-BBO Order

asyncapi: 3.0.0
info:
  title: WhiteBit Place Spot Stop-BBO Order
  version: 1.0.0
  description: |
    Place a spot stop order that turns into a BBO order.

    The price is resolved from the order book at activation time rather than at placement,
    which is why `price` stays `"0"` while the order waits.
  x-auth-required: true
  x-rate-limits:
    connections-per-minute: 1000
    order-placements-per-10-seconds: 10000
  x-error-codes:
    - code: 1
      message: bbo role must be an integer in range 1..2
      description: "The `bbo_role` value is outside `1`–`2`, or is not an integer."
    - code: 101
      message: activation price should not be equal to the last price
      description: "The activation price equals the current last price. Move the trigger to either side of it."
    - code: 251
      message: activation price is out of bands
      description: "The activation price falls outside the market price bands."
    - code: 12
      message: not enough traders
      description: "The order book has no quote on the required side at activation, so the order cannot be priced and is dropped."
    - code: 51
      message: trading in the market is not allowed
      description: "Trading is suspended, or the market runs in post-only mode — a stop method is rejected there."

servers:
  production:
    host: wss.whitebit.com
    protocol: wss
    description: WhiteBIT Global Server
  eu:
    host: api.whitebit.eu
    protocol: wss
    description: WhiteBIT EU Server

channels:
  /ws:
    address: /ws
    description: Spot stop-BBO order placement channel
    messages:
      orderStopBboPlaceRequest:
        $ref: '#/components/messages/orderStopBboPlaceRequest'
      orderStopBboPlaceResponse:
        $ref: '#/components/messages/orderStopBboPlaceResponse'

operations:
  sendOrderStopBboPlaceRequest:
    action: receive
    channel:
      $ref: '#/channels/~1ws'
    messages:
      - $ref: '#/channels/~1ws/messages/orderStopBboPlaceRequest'

  receiveOrderStopBboPlaceResponse:
    action: send
    channel:
      $ref: '#/channels/~1ws'
    messages:
      - $ref: '#/channels/~1ws/messages/orderStopBboPlaceResponse'

components:
  messages:
    orderStopBboPlaceRequest:
      name: OrderStopBboPlaceRequest
      title: Place stop-BBO order
      summary: Place a spot stop order that becomes a BBO order
      payload:
        $ref: '#/components/schemas/OrderStopBboPlaceRequest'
      examples:
        - name: orderStopBboPlaceMakerSell
          summary: |
            Place a maker-role sell stop order with parameters:
            - params[0]: order object with market, side, amount, activation_price, and bbo_role
          payload:
            id: 500009
            method: order_stop_bbo_place
            params:
              - market: ETH_USDT
                side: sell
                amount: "0.00108"
                activation_price: "1859.73"
                bbo_role: 1
                stp: "no"

    orderStopBboPlaceResponse:
      name: OrderStopBboPlaceResponse
      title: Place Stop-BBO Order Response
      summary: Accepted conditional order, price resolved on activation
      payload:
        $ref: '#/components/schemas/OrderStopBboPlaceResponse'
      examples:
        - name: orderStopBboPlaceAccepted
          summary: Order waiting for the trigger with price "0" and post_only set by the maker role
          payload:
            id: 500009
            result:
              id: 2423735880229
              market: ETH_USDT
              type: 3
              side: 1
              post_only: true
              ioc: false
              ctime: 1786452691.362412
              mtime: 1786452691.362412
              activation_price: "1859.73"
              activation_condition: lte
              activated: 0
              price: "0"
              amount: "0.00108"
              left: "0.00108"
              deal_stock: "0"
              deal_money: "0"
              deal_fee: "0"
              client_order_id: ""
              stp: "no"
              status: OPEN
            error: null

  schemas:
    OrderStopBboPlaceRequest:
      type: object
      required:
        - id
        - method
        - params
      properties:
        id:
          type: integer
          description: Unique request identifier. The response echoes this value.
        method:
          type: string
          const: order_stop_bbo_place
          description: "Method name. Fixed value: `order_stop_bbo_place`."
        params:
          type: array
          minItems: 1
          maxItems: 1
          items:
            $ref: '#/components/schemas/OrderStopBboPlaceParams'
          description: Array containing exactly one order parameter object

    OrderStopBboPlaceParams:
      type: object
      required:
        - market
        - side
        - amount
        - activation_price
        - bbo_role
      properties:
        market:
          type: string
          description: "Spot market name. A futures market is rejected with error `1`."
          example: ETH_USDT
        side:
          type: string
          enum: ["buy", "sell"]
          description: "Order side. The response reports the side numerically: `1` for sell, `2` for buy."
        amount:
          type: string
          description: "Order size in stock, at the market stock precision."
          example: "0.00108"
        activation_price:
          type: string
          description: "Trigger price, validated against the market price bands. Outside them the call returns error `251`."
          example: "1859.73"
        bbo_role:
          type: integer
          enum: [1, 2]
          description: "Pricing role applied at activation. `1` maker — price at the own-side best and set `post_only`. `2` taker — price at the opposite-side best."
        client_order_id:
          type: string
          description: "Custom client order id, echoed on the response. Must be unique among active orders — a collision returns error `43`."
        stp:
          type: string
          enum: ["no", "co", "cn", "cb"]
          description: "Self-trade prevention mode applied to the order created on activation. Defaults to `no` when omitted."

    OrderStopBboPlaceResponse:
      type: object
      required:
        - id
        - result
        - error
      properties:
        id:
          type: integer
          description: Request identifier matching the request
        result:
          type: object
          description: "Accepted conditional order reporting `type` `3` with `price` `\"0\"`, because the price is resolved from the order book only when the trigger fires."
        error:
          type: "null"
          description: Error object (null on success)