Skip to main content
POST
POST /v2/trade/perps/orders: Place an Order
Sign each request with a fresh HMAC signature. The cURL and HTTP header values below are placeholders, not reusable credentials. For runnable signing code, use request signing examples.
Places an order. Scope trade.perps; Idempotency-Key is required. The user’s readiness must be ready or credential_expiring. Every order rule is checked before the order reaches the venue; see Limits.

Body

integer
The venue instrument id. Send this or symbol.
string
Alias of instrument_id, for example BTC-USD.
string
required
buy (long) or sell (short).
string
required
Base-asset quantity (for example BTC, not pUSD), decimal string.
string
Limit price. Omit for a market-style order. At most price_decimals decimal places, a non-integer price has at most 5 significant figures, and |price − mark_price| ≤ mark_price × price_bounds.
string
gtc, ioc or fok. Defaults to gtc with a price and ioc without.
boolean
Requires tif: "gtc" and a price.
boolean
Only reduce the position. See Close a position.
object
object
string
Your label, up to 64 characters. Echoed back; never sent to the venue.

Response

The answer is one of two. 201: the venue answered.
string | null
The venue’s order id. null when nothing was placed (venue_status: "not_placed").
string
Your label, echoed back.
string
accepted, open, partially_filled, filled, cancelled, rejected or unknown (a venue status Bravado does not map).
string | null
The venue’s raw status string.
string
For an IOC, FOK or post-only order, when the read-back resolves in time.
boolean
true when the order went to the venue reduce-only.
boolean
true when your integration’s reduce-only mode turned the order reduce-only.
boolean
true when reduce-only mode capped the quantity at the position size.
For an IOC, FOK or post-only order, Bravado reads the order back before answering, so status and filled_size are the venue’s when the read-back resolves in time. If it does not, the 201 says accepted, with venue_status: null and no filled_size: read GET /v2/trade/perps/orders/{order_id} for the outcome. 202 pending_confirmation: the venue may or may not have the order.
string
pending_confirmation.
string
Read the order by this id.
string
Your label, echoed back.
integer
Wait this long before the first read.
Do not send it again, and never under a new key. Poll GET /v2/trade/perps/orders/{intent_id} after retry_after_ms until status is open or terminal. An order that never reached the venue ends as rejected with venue_status: "not_placed". Replaying the request with the same Idempotency-Key returns the same 202. To find an order you placed, read GET /v2/trade/perps/orders/ik:<your Idempotency-Key>. A read of a placed order returns the venue’s view, whose client_order_id is the order’s coid rather than your label, so keep your own map from label to order_id.

Close a position

To close, send the opposite side with reduce_only: true. A reduce-only order can only shrink the position; one that would increase or flip it is refused with 422 REDUCE_ONLY_VIOLATION.
  • A close is exempt from min_notional. A close is a reduce-only order against the position, no larger than it, and it may be worth less than min_notional. The venue has accepted such a close when what it leaves open is still worth at least min_notional; whether it accepts a whole-position close below min_notional is the venue’s call. If the venue does refuse a close, you get 400 INVALID_SIZE, or a 201 with status: "rejected" and venue_status: "below_min_notional". Neither is ever reported as filled.
  • A partial close may not leave dust. A partial close is refused before the venue with 400 INVALID_SIZE when what it leaves open, (position size − quantity) × mark price, would be worth less than min_notional. The refusal carries details.rule: "reduce_only_remainder_below_min_notional" and the numbers as decimal strings: details.position_size, details.remainder and details.min_notional. To close the whole position instead, send quantity: details.position_size.
  • On a 201, reduce_only_applied: true says the order went to the venue reduce-only.

Errors

Every Perps code and its retry rule: Errors. A 504 is an unknown outcome: look the order up at GET /v2/trade/perps/orders/ik:<your key> before anything else.

Example