WhiteBit Place Margin Limit Order

asyncapi: 3.0.0
info:
  title: WhiteBit Place Margin Limit Order
  version: 1.0.0
  description: |
    Place a margin or futures limit order over the WebSocket connection.

    This is the margin counterpart of `order_limit_place`, and like its spot twin it is the
    only method in the `collateral_*` family that accepts `rpi`.

    Across the whole family `amount` is always [stock](/glossary#stock), including the market
    methods. Leverage and margin come from the account collateral configuration and are not
    order parameters.
  x-auth-required: true
  x-rate-limits:
    connections-per-minute: 1000
    order-placements-per-10-seconds: 10000
  x-error-codes:
    - code: 19
      message: market is not margin market
      description: "The method was called on a spot-only market. Use the spot `order_*` equivalent there."
    - code: 14
      message: margin order by taker price
      description: "A post-only margin order would cross the spread."
    - code: 17
      message: user margin balance not enough
      description: "The collateral balance does not cover the order."
    - code: 111
      message: margin position is too big
      description: "The resulting position would exceed the size cap for the market."
    - code: 112
      message: margin pending orders value is too big
      description: "The total value of pending margin orders would exceed the account limit."
    - code: 114
      message: order's position side does not match user's setting
      description: "`position_side` was sent (as non-`BOTH`) without hedge mode enabled, or was omitted or sent as `BOTH` while hedge mode is enabled, or otherwise does not match the account setting."
    - code: 250
      message: price must be >= X / <= Y
      description: "The limit price falls outside the market price band."

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: Margin and futures limit order placement channel
    messages:
      collateralOrderLimitPlaceRequest:
        $ref: '#/components/messages/collateralOrderLimitPlaceRequest'
      collateralOrderLimitPlaceResponse:
        $ref: '#/components/messages/collateralOrderLimitPlaceResponse'

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

  receiveCollateralOrderLimitPlaceResponse:
    action: send
    channel:
      $ref: '#/channels/~1ws'
    messages:
      - $ref: '#/channels/~1ws/messages/collateralOrderLimitPlaceResponse'

components:
  messages:
    collateralOrderLimitPlaceRequest:
      name: CollateralOrderLimitPlaceRequest
      title: Place margin limit order
      summary: Place a margin or futures limit order
      payload:
        $ref: '#/components/schemas/CollateralOrderLimitPlaceRequest'
      examples:
        - name: collateralOrderLimitPlaceBuy
          summary: |
            Place a buy limit order with parameters:
            - params[0]: order object with market, side, amount, and price
          payload:
            id: 500010
            method: collateral_order_limit_place
            params:
              - market: BTC_PERP
                side: buy
                amount: "0.001"
                price: "63385.90"
                stp: "no"

    collateralOrderLimitPlaceResponse:
      name: CollateralOrderLimitPlaceResponse
      title: Place Margin Limit Order Response
      summary: Accepted order object (status OPEN)
      payload:
        $ref: '#/components/schemas/CollateralOrderLimitPlaceResponse'
      examples:
        - name: collateralOrderLimitPlaceAccepted
          summary: Order resting in the order book with the position fields present
          payload:
            id: 500010
            result:
              id: 2423735881146
              market: BTC_PERP
              type: 7
              side: 2
              post_only: false
              ioc: false
              reduce_only: false
              position_side: BOTH
              ctime: 1786452691.474534
              mtime: 1786452691.474534
              price: "63385.9"
              amount: "0.001"
              left: "0.001"
              deal_stock: "0"
              deal_money: "0"
              deal_fee: "0"
              client_order_id: ""
              stp: "no"
              status: OPEN
            error: null

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

    CollateralOrderLimitPlaceParams:
      type: object
      required:
        - market
        - side
        - amount
        - price
      properties:
        market:
          type: string
          description: "Margin or futures market name. A spot-only market is rejected with error `19`."
          example: BTC_PERP
        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.001"
        price:
          type: string
          description: "Limit price, validated against the maker and taker price bands for the given side."
          example: "63385.90"
        reduce_only:
          type: boolean
          description: "Restrict the order to shrinking an existing position. It can never open or flip one. With nothing to reduce, the order is dropped with status `AUTO_CANCELED_REDUCE_ONLY`, or rejected up front with error `116`."
        position_side:
          type: string
          enum: ["BOTH", "LONG", "SHORT"]
          description: "Position leg in hedge mode; futures markets only. `BOTH` in one-way mode. Optional at the request layer but functionally required in hedge mode — omitting it, or sending `BOTH`, is rejected with error `114`. Any value other than `BOTH` on a non-futures margin market is rejected with error `1`."
        post_only:
          type: boolean
          description: "Reject the order instead of taking liquidity. Cannot be combined with `ioc`."
        ioc:
          type: boolean
          description: "Immediate-or-cancel — cancel the unmatched remainder instead of resting it. Cannot be combined with `post_only` or `rpi`."
        rpi:
          type: boolean
          description: "Retail Price Improvement order. Implies `post_only`; cannot be combined with `ioc`."
        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: `no`=No Prevention, `co`=Cancel Oldest, `cn`=Cancel Newest, `cb`=Cancel Both. Defaults to `no` when omitted."

    CollateralOrderLimitPlaceResponse:
      type: object
      required:
        - id
        - result
        - error
      properties:
        id:
          type: integer
          description: Request identifier matching the request
        result:
          type: object
          description: "Accepted order. Returns the standard order object plus `reduce_only` and `position_side`. A margin limit order reports `type` `7`."
        error:
          type: "null"
          description: Error object (null on success)