WhiteBit Place Margin OCO Order

asyncapi: 3.0.0
info:
  title: WhiteBit Place Margin OCO Order
  version: 1.0.0
  description: |
    Place a One-Cancels-Other pair on a margin or futures market.

    The pair consists of a limit take-profit leg and a stop-limit stop-loss leg, of which only
    one can execute. When either leg fills, the other is withdrawn.

    One request produces three identifiers. The group id is the `id` inside `result`, next to
    `type: "oco"`; each leg carries its own order id. Cancel the pair through
    `order_cancel_conditional` using the group id — the leg ids serve for tracking fills.
  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. OCO is available on margin and futures markets only."
    - code: 150
      message: take profit is not post only
      description: "The take-profit leg would execute immediately as a taker. It must rest as a maker order — move `price` further from the market."
    - code: 151
      message: wrong activation price for stop loss
      description: "The stop-loss trigger sits on the wrong side of the current price."
    - code: 108
      message: wrong limit price for take profit
      description: "The take-profit limit price is inconsistent with its trigger."
    - code: 1
      message: limit_client_order_id and stop_client_order_id cannot be equal
      description: "The two legs were given the same client order id. Each leg needs its own, or neither."
    - code: 152
      message: can not place stop loss / take profit
      description: "One of the legs could not be created. Error `153` covers the same condition for the other leg."
    - code: 161
      message: conditional order validation
      description: "The group failed consistency validation as a whole."

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 OCO group placement channel
    messages:
      collateralOrderOcoPlaceRequest:
        $ref: '#/components/messages/collateralOrderOcoPlaceRequest'
      collateralOrderOcoPlaceResponse:
        $ref: '#/components/messages/collateralOrderOcoPlaceResponse'

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

  receiveCollateralOrderOcoPlaceResponse:
    action: send
    channel:
      $ref: '#/channels/~1ws'
    messages:
      - $ref: '#/channels/~1ws/messages/collateralOrderOcoPlaceResponse'

components:
  messages:
    collateralOrderOcoPlaceRequest:
      name: CollateralOrderOcoPlaceRequest
      title: Place OCO group
      summary: Place a linked take-profit and stop-loss pair
      payload:
        $ref: '#/components/schemas/CollateralOrderOcoPlaceRequest'
      examples:
        - name: collateralOrderOcoPlaceSell
          summary: |
            Place a sell OCO group with parameters:
            - params[0]: group object with the take-profit price above and the stop-loss trigger below
          payload:
            id: 500016
            method: collateral_order_oco_place
            params:
              - market: BTC_PERP
                side: sell
                amount: "0.001"
                price: "65301.08"
                activation_price: "63370.99"
                stop_limit_price: "62405.95"
                stp: "no"

    collateralOrderOcoPlaceResponse:
      name: CollateralOrderOcoPlaceResponse
      title: Place OCO Group Response
      summary: Group id with the take_profit and stop_loss legs
      payload:
        $ref: '#/components/schemas/CollateralOrderOcoPlaceResponse'
      examples:
        - name: collateralOrderOcoPlaceAccepted
          summary: Group accepted; timestamps and deal counters on each leg are elided for length
          payload:
            id: 500016
            result:
              type: oco
              id: 2423735892717
              stop_loss:
                id: 2423735892718
                market: BTC_PERP
                type: 9
                side: 1
                reduce_only: false
                position_side: BOTH
                activation_price: "63370.99"
                activation_condition: lte
                activated: 0
                price: "62405.95"
                amount: "0.001"
                left: "0.001"
                status: OPEN
              take_profit:
                id: 2423735892719
                market: BTC_PERP
                type: 7
                side: 1
                reduce_only: false
                position_side: BOTH
                price: "65301.08"
                amount: "0.001"
                left: "0.001"
                status: OPEN
            error: null

  schemas:
    CollateralOrderOcoPlaceRequest:
      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_oco_place
          description: "Method name. Fixed value: `collateral_order_oco_place`."
        params:
          type: array
          minItems: 1
          maxItems: 1
          items:
            $ref: '#/components/schemas/CollateralOrderOcoPlaceParams'
          description: Array containing exactly one group parameter object

    CollateralOrderOcoPlaceParams:
      type: object
      required:
        - market
        - side
        - amount
        - price
        - activation_price
        - stop_limit_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: "Side of both legs. The legs always point the same way, because together they exit one position."
        amount:
          type: string
          description: "Order size in stock, applied to each leg."
          example: "0.001"
        price:
          type: string
          description: "Limit price of the take-profit leg. On a sell it sits above the market. A price that would cross as a taker is rejected with error `150`."
          example: "65301.08"
        activation_price:
          type: string
          description: "Trigger price of the stop-loss leg, on the opposite side of the market from `price`."
          example: "63370.99"
        stop_limit_price:
          type: string
          description: "Limit price the stop-loss leg is placed at once triggered. Set it beyond `activation_price` so the exit still fills after the trigger."
          example: "62405.95"
        limit_client_order_id:
          type: string
          description: "Client order id for the take-profit leg. Must differ from `stop_client_order_id`."
        stop_client_order_id:
          type: string
          description: "Client order id for the stop-loss leg. Must differ from `limit_client_order_id`."
        reduce_only:
          type: boolean
          description: "Restrict both legs to shrinking an existing position."
        position_side:
          type: string
          enum: ["BOTH", "LONG", "SHORT"]
          description: "Position leg in hedge mode; futures markets only. `BOTH` in one-way mode."
        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."

    CollateralOrderOcoPlaceResponse:
      type: object
      required:
        - id
        - result
        - error
      properties:
        id:
          type: integer
          description: Request identifier matching the request
        result:
          type: object
          description: "Group object rather than a single order. Carries `type` `\"oco\"`, the group `id`, and the `take_profit` and `stop_loss` legs. Each leg is a full order object — the take-profit reports `type` `7`, the stop-loss `type` `9`."
        error:
          type: "null"
          description: Error object (null on success)