> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kraken.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Batch Add

> Submit a batch of orders in a single request

<div className="api-banner">
  <span className="api-protocol ws">WSS</span>
  <span className="api-detail">ws-auth.kraken.com/v2</span>
  <span className="api-tag">batch\_add</span>
</div>

Sends a collection of orders (minimum of 2 and maximum 15):

* Validation is performed on the whole batch prior to submission to the engine. If an order fails validation, the whole batch will be rejected.
* On submission to the engine, if an order fails pre-match checks (i.e. funding), then the individual order will be rejected and remainder of the batch will be processed.
* All orders in batch are limited to a single pair.

<Tabs>
  <Tab title="Request">
    <ResponseField name="method" type="string" required>
      Value: `batch_add`
    </ResponseField>

    <ResponseField name="params" type="object">
      <Expandable title="properties" defaultOpen>
        <ResponseField name="deadline" type="string">
          <span className="field-attr">Format:</span> RFC3339<br />
          <span className="field-attr">Example:</span> `2022-12-25T09:30:59.123Z`

          Range of valid offsets (from current time) is 500 milliseconds to 60 seconds, default is 5 seconds. The precision of this parameter is to the millisecond. The engine will prevent this order from matching after this time, it provides protection against latency on time sensitive orders.
        </ResponseField>

        <ResponseField name="symbol" type="string" required>
          <span className="field-attr">Example:</span> `"BTC/USD"`

          The symbol of the currency pair.
        </ResponseField>

        <ResponseField name="validate" type="boolean">
          <span className="field-attr">One of:</span> `true`, `false`<br />
          <span className="field-attr">Default:</span> `false`

          If set to `true` the order will be validated only, it will not trade in the matching engine.
        </ResponseField>

        <ResponseField name="token" type="string" required>
          Authentication token. See [authentication guide](/exchange/guides/websockets/authentication) for details.
        </ResponseField>

        <ResponseField name="orders" type="object[]">
          A list of orders in the batch.

          <Expandable title="properties" defaultOpen>
            <ResponseField name="cash_order_qty" type="float">
              <span className="field-attr">Condition:</span> market orders only

              Order volume expressed in quote currency.
            </ResponseField>

            <ResponseField name="conditional" type="object">
              The conditional parameters are used as a template for generating the secondary close orders when the primary order fills. Each fill on the primary order will generate a new secondary order. The size of the secondary order will be the same size as the executed quantity and have the opposite side.

              <Expandable title="properties" defaultOpen>
                <ResponseField name="order_type" type="string">
                  <span className="field-attr">One of:</span> `limit`, `stop-loss`, `stop-loss-limit`, `take-profit`, `take-profit-limit`, `trailing-stop`, `trailing-stop-limit`

                  Defines the order type of the secondary close orders which will be created on each fill.
                </ResponseField>

                <ResponseField name="limit_price" type="float">
                  Defines the limit price on the secondary close orders. Only required on secondary order types that support limit price: `limit`, `stop-loss-limit`, `take-profit-limit`.
                </ResponseField>

                <ResponseField name="limit_price_type" type="string">
                  <span className="field-attr">One of:</span> `static`, `pct`, `quote`<br />
                  <span className="field-attr">Default:</span> `quote`<br />
                  <span className="field-attr">Condition:</span> Only available on trailing-stop-limit orders

                  The units for the limit price on the secondary order.

                  * `static`: a static market price for the asset, i.e. 30000 for BTC/USD.
                  * `pct`: a percentage offset from the reference price, i.e. -10% from index price.
                  * `quote`: a notional offset from the reference price in the quote currency, i.e, 150 BTC/USD from last price.

                  Note, for `trailing-stop-limit` order type, the value represents offset from the trigger price. 0 would set a limit price the same as the trigger price.
                </ResponseField>

                <ResponseField name="trigger_price" type="float">
                  Specifies the amount for the trigger price - it supports both static market prices and relative prices. This field is used in combination with the `price_type` field below to determine the effective trigger price.

                  **Examples:**

                  * To trigger at 29000.5 BTC/USD, use price=29000.5, price\_type=static.
                  * To trigger when price rises by 5%, use price=5, price\_type=pct.
                  * To trigger when price drops by 150 USD, use price=-150, price\_type=quote.

                  Note, for `trailing-stop` and `trailing-stop-limit` order types, the price represents the reversion from the peak. It is always a positive offset value.
                </ResponseField>

                <ResponseField name="trigger_price_type" type="string">
                  <span className="field-attr">One of:</span> `static`, `pct`, `quote`<br />
                  <span className="field-attr">Default:</span> `static`

                  The units for the trigger price.

                  * `static`: a static market price for the asset, i.e. 30000 for BTC/USD.
                  * `pct`: a percentage offset from the reference price, i.e. -10% from index price.
                  * `quote`: a notional offset from the reference price in the quote currency, i.e, 150 BTC/USD from last price.
                </ResponseField>

                <ResponseField name="stop_price" type="float" deprecated>
                  <span className="field-attr">Deprecated:</span> Use `trigger_price`

                  Defines the trigger price on the secondary close orders. Only required on triggered secondary order types: `stop-loss`, `stop-loss-limit`, `take-profit`, `take-profit-limit`.
                </ResponseField>
              </Expandable>
            </ResponseField>

            <ResponseField name="display_qty" type="float">
              <span className="field-attr">Condition:</span> iceberg orders only

              Defines the quantity to show in the book while the rest of order quantity remains hidden. Minimum value is 1 / 15 of `order_qty`.
            </ResponseField>

            <ResponseField name="effective_time" type="string">
              <span className="field-attr">Format:</span> RFC3339<br />
              <span className="field-attr">Example:</span> `2022-12-25T09:30:59Z`

              Scheduled start time (precision to seconds).
            </ResponseField>

            <ResponseField name="expire_time" type="string">
              <span className="field-attr">Format:</span> RFC3339<br />
              <span className="field-attr">Example:</span> `2022-12-25T09:30:59Z`<br />
              <span className="field-attr">Condition:</span> GTD orders only

              Expiration time of the order (precision to seconds). GTD orders can have an expiry time up to one month in future.
            </ResponseField>

            <ResponseField name="fee_preference" type="string">
              <span className="field-attr">One of:</span> `base`, `quote`

              Fee preference base or quote currency. `quote` is the default for buy orders, `base` is the default for sell orders.
            </ResponseField>

            <ResponseField name="limit_price" type="float">
              Limit price for order types that support limit price restriction.
            </ResponseField>

            <ResponseField name="limit_price_type" type="string">
              <span className="field-attr">One of:</span> `static`, `pct`, `quote`<br />
              <span className="field-attr">Default:</span> `quote`<br />
              <span className="field-attr">Condition:</span> Only available on trailing-stop orders

              The units for the limit price.
            </ResponseField>

            <ResponseField name="margin" type="boolean">
              <span className="field-attr">One of:</span> `false`, `true`<br />
              <span className="field-attr">Default:</span> `false`

              Funds the order on margin using the maximum leverage for the pair (maximum is leverage of 5).
            </ResponseField>

            <ResponseField name="no_mpp" type="boolean" deprecated>
              <span className="field-attr">One of:</span> `true`, `false`<br />
              <span className="field-attr">Default:</span> `false`<br />
              <span className="field-attr">Condition:</span> Market orders only<br />
              <span className="field-attr">Deprecated:</span> If supplied, the flag is accepted but ignored

              Disables Market Price Protection (MPP) if set to `true`. MPP is a feature that protects market orders from filling at a bad price due to price slippage in an illiquid or volatile market. See [MPP support article](https://support.kraken.com/hc/en-us/articles/201648183-Market-Price-Protection).
            </ResponseField>

            <ResponseField name="cl_ord_id" type="string">
              Adds an alphanumeric client order identifier which uniquely identifies an open order for each client. This field is mutually exclusive with `order_userref` parameter. The `cl_ord_id` parameter can be one of the following formats:

              * Long UUID: `6d1b345e-2821-40e2-ad83-4ecb18a06876` 32 hex characters separated with 4 dashes.
              * Short UUID: `da8e4ad59b78481c93e589746b0cf91f` 32 hex characters with no dashes.
              * Free text: `arb-20240509-00010` Free format ascii text up to 18 characters.
            </ResponseField>

            <ResponseField name="order_userref" type="integer">
              This is an optional non-unique, numeric identifier which can be associated with a number of orders by the client. This field is mutually exclusive with `cl_ord_id` parameter. Many clients choose a unique integer value generated by their systems (i.e. a timestamp). However, because we don't enforce uniqueness on our side, it can also be used to easily tag a group of orders for querying or cancelling.
            </ResponseField>

            <ResponseField name="order_qty" type="float" required>
              Order quantity in terms of the base asset.
            </ResponseField>

            <ResponseField name="order_type" type="string" required>
              <span className="field-attr">One of:</span> `limit`, `market`, `iceberg`, `stop-loss`, `stop-loss-limit`, `take-profit`, `take-profit-limit`, `trailing-stop`, `trailing-stop-limit`, `settle-position`

              The execution model of the order.
            </ResponseField>

            <ResponseField name="post_only" type="boolean">
              <span className="field-attr">One of:</span> `true`, `false`<br />
              <span className="field-attr">Default:</span> `false`<br />
              <span className="field-attr">Condition:</span> Orders with limit price only

              Cancels the order if it will take liquidity on arrival. Post only orders will always be posted passively in the book.
            </ResponseField>

            <ResponseField name="reduce_only" type="boolean">
              <span className="field-attr">One of:</span> `true`, `false`<br />
              <span className="field-attr">Default:</span> `false`

              Reduces an existing margin position without opening an opposite long or short position worth more than the current value of your leveraged assets.
            </ResponseField>

            <ResponseField name="side" type="string" required>
              <span className="field-attr">One of:</span> `buy`, `sell`

              Side of the order.
            </ResponseField>

            <ResponseField name="stp_type" type="string">
              <span className="field-attr">One of:</span> `cancel_newest`, `cancel_oldest`, `cancel_both`<br />
              <span className="field-attr">Default:</span> `cancel_newest`

              Self Trade Prevention (STP) is a protection feature to prevent users from inadvertently or deliberately trading against themselves. To prevent a self-match, one of the following STP modes can be used to define which order(s) will be expired.

              * `cancel_newest`: arriving order will be canceled.
              * `cancel_oldest`: resting order will be canceled.
              * `cancel_both`: both arriving and resting orders will be canceled.
            </ResponseField>

            <ResponseField name="time_in_force" type="string">
              <span className="field-attr">One of:</span> `gtc`, `gtd`, `ioc`, `fok`<br />
              <span className="field-attr">Default:</span> `gtc`

              Time-in-force specifies how long an order remains in effect before being expired.

              * `gtc`: Good Till Canceled - until user has cancelled.
              * `gtd`: Good Till Date - until `expire_time` parameter.
              * `ioc`: Immediate Or Cancel - immediately cancels back any quantity that cannot be filled on arrival.
              * `fok`: Fill Or Kill - immediately fills the full order quantity or cancels it entirely. Available for `limit` orders only.
            </ResponseField>

            <ResponseField name="triggers" type="object">
              <span className="field-attr">Condition:</span> Required for triggered order types only

              The parameters for setting the trigger price conditions.

              <Expandable title="properties" defaultOpen>
                <ResponseField name="reference" type="string">
                  <span className="field-attr">One of:</span> `index`, `last`<br />
                  <span className="field-attr">Default:</span> `last`

                  The reference price to track for triggering orders.

                  * `index`: the index price in the broader market (for this pair). Note, to keep triggers serviceable during connectivity issues with external index feeds, the last price will be used as the reference price.
                  * `last`: the last traded price in the Kraken order book (for this pair).
                </ResponseField>

                <ResponseField name="price" type="float" required>
                  Specifies the amount for the trigger price - it supports both static market prices and relative prices. This field is used in combination with the `price_type` field below to determine the effective trigger price.

                  **Examples:**

                  * To trigger at 29000.5 BTC/USD, use price=29000.5, price\_type=static.
                  * To trigger when price rises by 5%, use price=5, price\_type=pct.
                  * To trigger when price drops by 150 USD, use price=-150, price\_type=quote.

                  Note, for `trailing-stop` and `trailing-stop-limit` order types, the price represents the reversion from the peak. It is always a positive offset value.
                </ResponseField>

                <ResponseField name="price_type" type="string">
                  <span className="field-attr">One of:</span> `static`, `pct`, `quote`<br />
                  <span className="field-attr">Default:</span> `static`

                  The units for the trigger price.

                  * `static`: a static market price for the asset, i.e. 30000 for BTC/USD.
                  * `pct`: a percentage offset from the reference price, i.e. -10% from index price.
                  * `quote`: a notional offset from the reference price in the quote currency, i.e, 150 BTC/USD from last price.
                </ResponseField>
              </Expandable>
            </ResponseField>

            <ResponseField name="sender_sub_id" type="string">
              <span className="field-attr">Condition:</span> For institutional accounts with enhanced Self Trade Prevention (STP). The `sender_sub_id` parameter can be one of the following formats:

              Adds an alphanumeric sub-account/trader identifier which enables STP to be performed at a more granular level.

              * Long UUID: `6d1b345e-2821-40e2-ad83-4ecb18a06876` 32 hex characters separated with 4 dashes.
              * Short UUID: `da8e4ad59b78481c93e589746b0cf91f` 32 hex characters with no dashes.
              * Free text: `arb-20240509-00010` Free format ascii text up to 18 characters.
            </ResponseField>

            <ResponseField name="stop_price" type="float" deprecated>
              <span className="field-attr">Deprecated:</span> Use `triggers` object

              The stop price for trigger order types.
            </ResponseField>

            <ResponseField name="trigger" type="string" deprecated>
              <span className="field-attr">One of:</span> `last`, `index`<br />
              <span className="field-attr">Default:</span> `last`<br />
              <span className="field-attr">Condition:</span> Triggered order types only<br />
              <span className="field-attr">Deprecated:</span> Use `triggers` object

              The reference price to trigger the order.

              * `index`: the index price for the broader market for this symbol.
              * `last`: the last traded price in the order book for this symbol.
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="req_id" type="integer">
      Optional client originated request identifier sent as acknowledgment in the response.
    </ResponseField>
  </Tab>

  <Tab title="Response">
    The order of returned txid's in the response array is the same as the order of the order list sent in request.

    <ResponseField name="method" type="string">
      Value: `batch_add`
    </ResponseField>

    <ResponseField name="result" type="object[]">
      <span className="field-attr">Condition:</span> if `success` is `true`

      <Expandable title="properties" defaultOpen>
        <ResponseField name="order_id" type="string">
          Unique order identifier generated by Kraken.
        </ResponseField>

        <ResponseField name="cl_ord_id" type="string">
          An optional, alphanumeric identifier specified by the client in the `batch_add` parameters.
        </ResponseField>

        <ResponseField name="order_userref" type="integer">
          An optional order identifier specified by the client in the `batch_add` parameters.
        </ResponseField>

        <ResponseField name="warnings" type="array of string">
          Non-fatal warnings about the order, if any.
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="error" type="string">
      Error message. Condition: if `success` is `false`.
    </ResponseField>

    <ResponseField name="success" type="boolean">
      Indicates if the request was successfully processed by the engine. One of: `true`, `false`
    </ResponseField>

    <ResponseField name="req_id" type="integer">
      Optional client originated request identifier sent as acknowledgment in the response.
    </ResponseField>

    <ResponseField name="time_in" type="string">
      The timestamp when the request was received on the wire, just prior to parsing data. Format: RFC3339. Example: `2022-12-25T09:30:59.123456Z`
    </ResponseField>

    <ResponseField name="time_out" type="string">
      The timestamp when the response was sent on the wire, just prior to transmitting data. Format: RFC3339. Example: `2022-12-25T09:30:59.123456Z`
    </ResponseField>
  </Tab>
</Tabs>

<Panel>
  <CodeGroup>
    ```json Request theme={null}
    {
        "method": "batch_add",
        "params": {
            "deadline": "2022-06-13T08:09:10.123456Z",
            "orders": [
                {
                    "limit_price": 1010.10,
                    "order_qty": 0.123456789,
                    "order_type": "limit",
                    "order_userref": 1,
                    "side": "buy"
                },
                {
                    "limit_price": 2020.20,
                    "order_qty": 0.987654321,
                    "order_type": "limit",
                    "order_userref": 2,
                    "side": "sell",
                    "stp_type": "cancel_both"
                }
            ],
            "symbol": "BTC/USD",
            "token": "TxxxxxxxxxOxxxxxxxxxxKxxxxxxxExxxxxxxxN",
            "validate": false
        },
        "req_id": 1234567890
    }
    ```

    ```json Response theme={null}
    {
        "method": "batch_add",
        "req_id": 1234567890,
        "result": [
            {
                "order_id": "ORDERX-IDXXX-XXXXX1",
                "order_userref": 1
            },
            {
                "order_id": "ORDERX-IDXXX-XXXXX2",
                "order_userref": 2
            }
        ],
        "success": true,
        "time_in": "2022-06-13T08:09:10.123456Z",
        "time_out": "2022-06-13T08:09:10.7890123"
    }
    ```
  </CodeGroup>
</Panel>