Add Order
REQUESTwss://ws-auth.kraken.com/v2
add_orderAuthentication Required
Sends a single, new order into the exchange. A range of order types, Time-In-Force (TIF) and order flags can be specified by the parameters below.
For triggered order types (stop-loss
, take-profit
, trailing-stop
), the triggers
section contains the parameters for price tracking and trigger thresholds.
For One-Triggers-Other (OTO) orders, the conditional
section contains the parameters to add a secondary close order to the primary order.
Request
- Request Schema
- Example: Limit
- Example: Stop Loss
- Example: OTO
MESSAGE BODY
add_order
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.
market
: The full order quantity executes immediately at the best available price in the order book.limit
: The full order quantity is placed immediately with a limit price restriction to only trade at this price or better.stop-loss
: A market order is triggered when the reference price reaches the stop price (from an unfavourable direction).stop-loss-limit
: A limit order is triggered when the reference price reaches the stop price (from an unfavourable direction).take-profit
: A market order is triggered when the reference price reaches the stop price (from an favourable direction).take-profit-limit
: A limit order is triggered when the reference price reaches the stop price (from an favourable direction).trailing-stop
: A market order is triggered when the market reverts a specified distance from the peak price.trailing-stop-limit
: A limit order is triggered when the market reverts a specified distance from the peak price.iceberg
: Hides the full order size by only showing your chosen display size in the book at your limit price.
buy
, sell
] static
, pct
, quote
] quote
The units for the limit 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
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.
The parameters for setting the trigger price conditions.
index
, last
] 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).
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.
static
, pct
, quote
] 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
Note, for trailing-stop
and trailing-stop-limit
order types, the price represents the reversion from the peak. It is always a positive value with pct
or quote
offset.
gtc
, gtd
, ioc
] 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 - untilexpire_time
parameter.ioc
: Immediate Or Cancel - immediately cancels back any quantity that cannot be filled on arrival.
false
, true
] false
true
, false
] false
Cancels the order if it will take liquidity on arrival. Post only orders will always be posted passively in the book.
true
, false
] false
Reduces an existing margin position without opening an opposite long or short position worth more than the current value of your leveraged assets.
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.
Adds a alphanumeric client order identifier which uniquely identifies an open order for each client. This field is mutually exclusive with order_userref
parameter.
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.
This is an optional non-unique, numeric identifier which can associated with a number of orders by the client. This field is mutually exclusive with cl_ord_id
parameter.
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.
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.
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
.
static
, pct
, quote
] quote
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.
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.
static
, pct
, quote
] 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
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
.
Defines the quantity to show in the book while the rest of order quantity remains hidden.
Minimum value is 1 / 15 of order_qty
.
base
, quote
] Fee preference base or quote currency. quote
is the default for buy orders, base
is the default for sell orders.
true
, false
] false
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.
cancel_newest
, cancel_oldest
, cancel_both
] 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.
true
, false
] false
If set to true
the order will be validated only, it will not trade in the matching engine.
Adds a alphanumeric sub-account/trader identifier which enables STP to be performed at a more granular level.
Thesender_sub_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.
last
, index
] last
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.
Create a simple buy order with a limit price.
{
"method": "add_order",
"params": {
"order_type": "limit",
"side": "buy",
"limit_price": 26500.4,
"order_userref": 100054,
"order_qty": 1.2,
"symbol": "BTC/USD",
"token": "G38a1tGFzqGiUCmnegBcm8d4nfP3tytiNQz6tkCBYXY"
},
"req_id": 123456789
}
Create a sell stop-loss order to trigger when the market drops 2% from last price.
{
"method": "add_order",
"params": {
"order_type": "stop-loss",
"side": "sell",
"order_qty": 100,
"symbol": "MATIC/USD",
"triggers": {
"reference": "last",
"price": -2.0,
"price_type": "pct"
},
"token": "G38a1tGFzqGiUCmnegBcm8d4nfP3tytiNQz6tkCBYXY"
}
}
A more detailed example, create a limit price order to buy 1.2 BTC at 28440 USD and create a secondary stop-loss order to sell 1.2 BTC when the price drops below 28410 USD. The stop-loss order has a limit price restriction to not trade below 28400 USD.
{
"method": "add_order",
"params": {
"order_type": "limit",
"side": "buy",
"order_qty": 1.2,
"symbol": "BTC/USD",
"limit_price": 28440,
"conditional": {
"order_type": "stop-loss-limit",
"trigger_price": 28410,
"limit_price": 28400
},
"token": "G38a1tGFzqGiUCmnegBcm8d4nfP3tytiNQz6tkCBYXY"
}
}
Response
- Response Schema
- Example
MESSAGE BODY
add_order
add_order
parameters.add_order
parameters.true
, false
] {
"method": "add_order",
"req_id": 123456789,
"result": {
"order_id": "AA5JGQ-SBMRC-SCJ7J7",
"order_userref": 100054
},
"success": true,
"time_in": "2023-09-21T14:15:07.197274Z",
"time_out": "2023-09-21T14:15:07.205301Z"
}