Skip to main content
POST

Authorizations

Api-Access-Key
string
header
required

An API key associated with a security role

Headers

Idempotency-Key
string
required

Client-supplied key that deduplicates retried requests. Reusing a key returns the original result instead of repeating the action.

Api-Signature
string
required

A hex-encoded Ed25519 signature of timestamp_epoch_seconds + uppercase(http_method) + request_path + request_body.

Pattern: ^[0-9A-Fa-f]{128,160}$
Api-Timestamp
integer<int64>
required

Current timestamp, represented as unix epoch seconds

Path Parameters

accountId
string<uuid>
required

Account ID or subaccount ID (a UUID) for this order to book into. See the endpoint description for how this affects the allowed request body fields. An unknown ID is rejected with a 400 and code INVALID_ACCOUNT.

Example:

"3486b413-93d3-4447-afce-2b9c9dc34a32"

Body

application/json
symbol
string
required

Symbol for the order, e.g. BTC-USD.

Pattern: ^[A-Z0-9_]+-[A-Z0-9_]+$
side
enum<string>
required

Order side, either "BUY" or "SELL".

Available options:
BUY,
SELL
currency
string
required

The currency in which order quantity is specified in, e.g. BTC or USD. Must be one of the two legs of symbol.

  • For FOK orders, a BUY must specify the quote currency (e.g. USD for BTC-USD) and a SELL must specify the base currency (e.g. BTC for BTC-USD). Violations are rejected with INVALID_CURRENCY_FOR_FOK.
  • For STOP_LOSS orders, currency must be the base currency of symbol (e.g. BTC for BTC-USD).
  • For all other time-in-force values and order types, either leg may be used.
quantity
string
required

Order quantity in units of currency, as a positive decimal number encoded as a string.

Pattern: ^\d+(\.\d+)?$
orderType
enum<string>
default:MARKET
required

Order type. One of:

  • MARKET - executes immediately at the best available price, with a maximum slippage of 5% from the current market price. Always executed with IOC time in force: whatever can be filled within the slippage bound is executed immediately and the remainder is canceled. limitPrice must not be specified.
  • LIMIT - executes at limitPrice or better. limitPrice is required.
  • STOP_LOSS - dormant until the market reaches triggerPrice, then submitted as a market order. Used to limit losses on an existing position. triggerPrice is required; limitPrice must not be specified. Execution price is not guaranteed. Must be a SELL with quantity in the base currency of symbol; any other side or currency leg is rejected.
  • STOP_LIMIT - dormant until the market reaches triggerPrice, then submitted as a limit order at limitPrice. Both triggerPrice and limitPrice are required. Unlike STOP_LOSS, execution price is bounded by limitPrice, but the order may not fill if the market moves through it.
  • TAKE_PROFIT_LIMIT - dormant until the market reaches triggerPrice in the profitable direction, then submitted as a limit order at limitPrice. Used to lock in gains on an existing position. Both triggerPrice and limitPrice are required.
Available options:
MARKET,
LIMIT,
STOP_LOSS,
STOP_LIMIT,
TAKE_PROFIT_LIMIT
timestamp
string<date-time>
required

Timestamp when submitting this order. Date-times are always in UTC RFC 3339 'date-time'.

Example:

"2019-01-02T12:34:56.000Z"

limitPrice
string

Limit price for the order, as a positive decimal number encoded as a string.

  • Required for LIMIT, STOP_LIMIT, and TAKE_PROFIT_LIMIT orders.
  • Must not be specified for MARKET and STOP_LOSS orders.
Pattern: ^\d+(\.\d+)?$
triggerPrice
string

Market price at which a dormant order is triggered and submitted to the book, as a positive decimal number encoded as a string.

  • Required for STOP_LOSS, STOP_LIMIT, and TAKE_PROFIT_LIMIT orders.
  • Must not be specified for MARKET and LIMIT orders.
  • For STOP_LOSS, which is always a SELL: triggers when the market moves against the position, at or below triggerPrice.
  • For STOP_LIMIT: triggers when the market moves against the position (at or below triggerPrice for SELL, at or above for BUY).
  • For TAKE_PROFIT_LIMIT: triggers when the market moves in favor of the position (at or above triggerPrice for SELL, at or below for BUY).
Pattern: ^\d+(\.\d+)?$
timeInForce
enum<string>

How long the order remains active before it is executed or expires. If not provided, defaults to GTC for all order types except MARKET, which is always executed as IOC. One of:

  • FOK (fill or kill) - the order must be fully filled immediately, otherwise it is canceled with no partial execution. Note the currency-leg restriction on FOK orders described under currency.
  • IOC (immediate or cancel) - any portion that can be filled immediately is executed, and the remainder is canceled.
  • GTC (good till canceled) - the order remains active until it is fully executed or explicitly canceled.
  • GTD (good till date) - the order remains active until it is fully executed or expiryTime is reached. expiryTime is required.

MARKET orders are always executed as IOC: for MARKET orders this field may be omitted or set to IOC; any other value is rejected.

Available options:
FOK,
IOC,
GTC,
GTD
expiryTime
string<date-time>

Time at which the order expires and is automatically canceled if not yet fully executed.

  • Required when timeInForce is GTD.
  • Must not be specified for any other time in force.
  • Must be in the future. Date-times are always in UTC RFC 3339 'date-time'.
Example:

"2019-01-02T12:34:56.000Z"

externalId
string

Unique client-assigned external ID, between 1 and 36 characters.

  • Must be unique among accepted orders: submitting an order with the externalId of a previously accepted order is rejected with 409 DUPLICATE_ORDER.
  • If a previous submission was rejected (e.g. due to a validation error), its externalId may be reused.
Required string length: 1 - 36
allocations
Order Allocation Request · object[]

Order subaccount allocations: how the order is split across subaccounts.

  • Only allowed when the accountId path parameter is an account ID; it is illegal to provide allocations when accountId is a subaccount ID.
  • Optional for OMNIBUS accounts: when omitted, the entire order books at the account level.
  • Required for FBO accounts, since FBO orders cannot book at the account level.
  • If provided, must contain at least one allocation. Note that to book an entire order into a single subaccount, there are two equivalent options: place the order with the subaccount ID in the path (and no allocations), or place it with the account ID and a single-entry allocations array.
  • The allocation quantities must sum to the order quantity.
Minimum array length: 1
specLotId
string

Optional specification lot ID for tax reporting purposes, scoped to the entire order. When provided, instructs the tax service to retire the specified lot for this trade.

  • Only allowed when the accountId path parameter is a subaccount ID. When accountId is an account ID, use the allocation-level specLotId instead; the two are mutually exclusive.
  • Only applicable for SELL orders with timeInForce FOK. Spec lots cannot be retired on IOC, GTC, or GTD orders, since the lot can only be assigned when the fill is all-or-nothing. MARKET orders execute as IOC and therefore cannot carry one.

Response

Order accepted. Only the order ID and external ID are returned; the client is expected to look up the order's state via the order lookup endpoint.

data
Place Order Result · object
required