Create new order

POST/orders

Create new orderTrading

Places an order and returns it as the trading engine stored it. Increase orders (market, limit, stop_market, stop_limit) open or grow a position; close orders (stop, take, trailing_stop) attach to an existing position through positionId.

amount is read in a different unit by each of the two: on an increase order it is a quote amount reserved from the free balance, on a close order it is the base asset size of the position to close, with nothing reserved. The rest of the size fields (expectedAmount, sizeMode, baseSize, leverage) belong to increase orders only.

Beyond the field-level schema the request is checked for:

Shape for the type. Every rejection here is a 400 whose code names the field combination at fault:
- size — amount_not_positive, base_size_required, base_size_negative, base_size_not_allowed;
- leverage — leverage_required, leverage_negative;
- trigger price — trigger_price_required, trigger_price_negative;
- stop-loss / take-profit attached to an increase order — stop_trigger_price_negative, take_trigger_price_negative, stop_trigger_price_gt_trigger_price, stop_trigger_price_lt_trigger_price, take_trigger_price_gt_trigger_price, take_trigger_price_lt_trigger_price;
- stop-limit price — stop_limit_price_required, stop_limit_price_negative, stop_limit_price_gt_trigger_price, stop_limit_price_lt_trigger_price;
- trailing stop — trailing_stop_activation_price_negative, trailing_stop_offset_required, trailing_stop_offset_conflict, trailing_stop_offset_negative, trailing_stop_offset_percent_negative, trailing_stop_offset_percent_gte_one;
- close orders — position_id_required.
Leverage of an increase order. Must stay within market bounds: not below the market minimum and not above the phase maximum, with invalid_leverage (leverage plus minLeverage or maxLeverage in the body).
Account. Must belong to the caller and be in a trading status; increase orders are additionally refused while the account is locked by the managed capital limit, and need amount available as free balance.
Market. Must be open and inside the category the account may trade (crypto or RWA). A close-only market takes nothing but a take order created without a trigger price.
Position, when positionId is given: it must exist (position_not_found), be open, sit on the same account, belong to the same market and run in the same direction as the order (position_not_available).
Trigger price, against the current market price and — for stop / take — against the liquidation price of the position (trigger_price_gt_current, trigger_price_lt_current, trigger_price_gt_liquidation, trigger_price_lt_liquidation). A market order with an attached stop-loss / take-profit is checked against the liquidation price its position would have after the fill: market_price_unavailable when there is no current price to check against, order_validation_invariant when the size fields needed for that projection are missing.
Notional of an increase order. (amount − fee) × leverage must fit the max open notional the market allows in that direction (order_exceeds_max_open_notional).

A deferred order is not executed here, so it can still fail when its trigger fires later: it then ends up with status canceled_by_error and an errorCode (insufficient_reserve_at_execution, order_below_min_notional, order_exceeds_market_depth, order_exceeds_max_open_notional, order_zero_size_at_execution, slippage_tolerance, market_close_only_at_execution), and its reserve is released.

Send an x-idempotency-key header to make the call replay-safe: inside the replay window stated on that header, the same key on the same route replays the stored response (marked with X-Idempotency-Cached: true and X-Idempotency-Timestamp) instead of acting again, and a second call arriving while the first one is still running gets 409 (idempotency_key_in_flight).

Base URL https://api.upscale.trade

Authorization

bearerhttp · bearerrequired

Personal API key, prefixed with usk_.

Parameters

Header

x-idempotency-keystringoptional

Idempotency key — any opaque string, a uuid v4 works well. Repeating the call with the same key on this route within 1 hour replays the stored response instead of acting again; a replay carries X-Idempotency-Cached: true and X-Idempotency-Timestamp. Omit the header to opt out.

Example: 9f1c2b7e-5a3d-4f61-9b0e-2c7d4a8e1f35

Request body · required

accountIdstring · uuidrequired

Trader account the order is placed on. Must belong to the caller.

pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$

Example: 00000000-0000-4000-8000-000000000000

marketIdstring · uuidrequired

Market the order is placed on, as returned by GET /v2/markets.

pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$

Example: 00000000-0000-4000-8000-000000000000

typestring · enumrequired

Order type. Increase (position-opening) types: market, limit, stop_market, stop_limit. Close types, attached to an existing position: stop, take, trailing_stop. liquidation is raised by the platform itself and add_margin / remove_margin are legacy — none of the three is accepted here.

Allowed: "market" "limit" "stop" "trailing_stop" "take" "stop_limit" "stop_market"

Example: market

directionstring · enumrequired

Order direction. For a close order it must match the direction of the position it is attached to.

Allowed: "long" "short"

Example: long

amountstring · int32required

What the order is sized by, fp9 raw — the unit depends on the order class. On an increase order (market, limit, stop_market, stop_limit) it is a quote amount reserved from the free balance (margin, fee, spread and buffer): the account must hold at least this much, and the reserve is released when the order is cancelled. On a close order (stop, take, trailing_stop) it is the base asset size of the position to close and nothing is reserved; a size larger than the position holds closes it in full.

pattern: ^(?:-?[1-9][0-9]*|0)$

Example: 100000000000

12 optional fields

positionIdstring · uuid · nullableoptional

Position a close order (stop, take, trailing_stop) is attached to. Required for those types, ignored for increase orders.

pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$

Example: 00000000-0000-4000-8000-000000000000

expectedAmountstring · int32 · nullableoptional

Slippage tolerance for increase orders: the position size the caller expects for amount, fp9 raw. Execution outside the tolerance fails with slippage_tolerance. Omitted or 0 — no tolerance check. Not applicable to close orders.

pattern: ^(?:-?[1-9][0-9]*|0)$

Example: 0

leveragestring · int32 · nullableoptional

Leverage, fp9 raw (10000000000 = 10x). Required for increase orders and must be within the leverage bounds of the market.

pattern: ^(?:-?[1-9][0-9]*|0)$

Example: 10000000000

triggerPricestring · int32 · nullableoptional

Price at which the order fires, fp9 raw. Required for limit, stop, take, stop_market and stop_limit, and rejected for market. For stop / take, 0 means the order is created without a trigger and can be set later.

pattern: ^(?:-?[1-9][0-9]*|0)$

Example: 65000000000000

stopTriggerPricestring · int32 · nullableoptional

Stop-loss attached to an increase order, fp9 raw. Must sit below the entry trigger price for long and above it for short.

pattern: ^(?:-?[1-9][0-9]*|0)$

Example: 1000000000

takeTriggerPricestring · int32 · nullableoptional

Take-profit attached to an increase order, fp9 raw. Must sit above the entry trigger price for long and below it for short.

pattern: ^(?:-?[1-9][0-9]*|0)$

Example: 1000000000

trailingStopActivationPricestring · int32 · nullableoptional

Price at which a trailing_stop starts trailing, fp9 raw. Omitted — the order trails from the moment it is created.

pattern: ^(?:-?[1-9][0-9]*|0)$

Example: 1000000000

trailingStopOffsetstring · int32 · nullableoptional

Trailing distance as an absolute quote amount, fp9 raw. Exactly one of trailingStopOffset / trailingStopOffsetPercent is required.

pattern: ^(?:-?[1-9][0-9]*|0)$

Example: 1000000000

trailingStopOffsetPercentstring · int32 · nullableoptional

Trailing distance as a fraction of price, fp9 raw and strictly below 1000000000 (100%). Exactly one of trailingStopOffset / trailingStopOffsetPercent is required.

pattern: ^(?:-?[1-9][0-9]*|0)$

Example: 50000000

stopLimitPricestring · int32 · nullableoptional

Limit price a stop_limit order is placed at once its trigger fires, fp9 raw. Required for that type; must be at or below the trigger price for long and at or above it for short.

pattern: ^(?:-?[1-9][0-9]*|0)$

Example: 1000000000

sizeModestring · enumoptional

How the size of an increase order is expressed: quote (default) sizes it by amount, base sizes it by baseSize while amount stays the reserve. Increase orders only — a close order is always sized by amount in base asset units.

Allowed: "quote" "base"

Example: quote

baseSizestring · int32 · nullableoptional

Order size in base asset units, fp9 raw. Required when sizeMode is base and rejected otherwise, and meaningful for increase orders only.

pattern: ^(?:-?[1-9][0-9]*|0)$

Example: 1000000000

{
  "accountId": "00000000-0000-4000-8000-000000000000",
  "marketId": "00000000-0000-4000-8000-000000000000",
  "type": "market",
  "direction": "long",
  "amount": "100000000000"
}

Examples

curl --request POST 'https://api.upscale.trade/orders' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "accountId": "00000000-0000-4000-8000-000000000000",
  "marketId": "00000000-0000-4000-8000-000000000000",
  "type": "market",
  "direction": "long",
  "amount": "100000000000"
}'

const response = await fetch("https://api.upscale.trade/orders", {
  method: "POST",
  headers: {
    "Accept": "application/json",
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: "{\n  \"accountId\": \"00000000-0000-4000-8000-000000000000\",\n  \"marketId\": \"00000000-0000-4000-8000-000000000000\",\n  \"type\": \"market\",\n  \"direction\": \"long\",\n  \"amount\": \"100000000000\"\n}",
});
console.log(response.status, await response.text());

import requests
 
response = requests.request(
    "POST",
    "https://api.upscale.trade/orders",
    headers={"Accept":"application/json","Authorization":"Bearer YOUR_API_KEY","Content-Type":"application/json"},
    data="{\n  \"accountId\": \"00000000-0000-4000-8000-000000000000\",\n  \"marketId\": \"00000000-0000-4000-8000-000000000000\",\n  \"type\": \"market\",\n  \"direction\": \"long\",\n  \"amount\": \"100000000000\"\n}",
    timeout=30,
)
print(response.status_code, response.text)

Responses

401

Unauthorized

403

The account belongs to another user (account_access_denied), or the request is authenticated with an API key while api_trading is disabled on the account (api_trading_not_enabled). Trading on the account is over in its current status (challenge_closed), or the account is locked by the managed capital limit (funded_limit_trading_locked). The market is paused (market_paused) or accepts closing orders only (market_close_only).

404

No such account, market, or position.

409

Another call with the same x-idempotency-key is still running (idempotency_key_in_flight). Retry once it finishes.

429

Rate limit of the API key exceeded (api_key_rate_limit_exceeded). Retry-After says when to come back; the body carries the bucket (read / write), the window that tripped, its limit and retryAt.

defaultResponseapplication/json

idstring · uuidrequired

Order identifier.

pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$

Example: 00000000-0000-4000-8000-000000000000

txIdstringrequired

Order identifier. Kept for backward compatibility, always equal to id.

Example: string

traderstring · uuidrequired

Trader account the order belongs to.

pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$

Example: 00000000-0000-4000-8000-000000000000

marketstring · uuidrequired

Market the order is placed on.

pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$

Example: 00000000-0000-4000-8000-000000000000

statusstring · enumrequired

Lifecycle state: active while it waits, executed once filled, canceled when cancelled by the trader or the platform, canceled_by_update when replaced by an edit, canceled_by_position when the position it was attached to went away, canceled_by_error when execution failed — see errorCode.

Allowed: "active" "canceled" "canceled_by_update" "canceled_by_error" "canceled_by_position" "executed"

Example: active

typestring · enumrequired

Order type. liquidation marks an order the engine raised itself.

Allowed: "market" "limit" "stop" "trailing_stop" "take" "stop_limit" "stop_market" "liquidation"

Example: market

directionstring · enumrequired

Order direction.

Allowed: "long" "short"

Example: long

triggerPricestring · int32required

Price at which the order fires, fp9 raw. 0 when the order carries no trigger.

pattern: ^(?:-?[1-9][0-9]*|0)$

Example: 1000000000

requestedTriggerPricestring · int32 · nullablerequired

Trigger price as requested, before the engine pushed it out to the minimum stop distance, fp9 raw. Null when the requested price was kept as is.

pattern: ^(?:-?[1-9][0-9]*|0)$

Example: 1000000000

stopPricestring · int32required

Trigger price of a stop_market / stop_limit order, fp9 raw; 0 for every other type.

pattern: ^(?:-?[1-9][0-9]*|0)$

Example: 1000000000

limitPricestring · int32required

Price the order is placed at once triggered, fp9 raw: the stop-limit price, falling back to the trigger price.

pattern: ^(?:-?[1-9][0-9]*|0)$

Example: 1000000000

stopTriggerPricestring · int32required

Stop-loss attached to the order, fp9 raw. 0 when none is attached.

pattern: ^(?:-?[1-9][0-9]*|0)$

Example: 1000000000

takeTriggerPricestring · int32required

Take-profit attached to the order, fp9 raw. 0 when none is attached.

pattern: ^(?:-?[1-9][0-9]*|0)$

Example: 1000000000

trailingStopActivationPricestring · int32required

Price at which a trailing stop starts trailing, fp9 raw. 0 when it trails from creation.

pattern: ^(?:-?[1-9][0-9]*|0)$

Example: 1000000000

trailingStopOffsetstring · int32required

Trailing distance as an absolute quote amount, fp9 raw. 0 when the distance is set as a percent.

pattern: ^(?:-?[1-9][0-9]*|0)$

Example: 1000000000

trailingStopOffsetPercentstring · int32required

Trailing distance as a fraction of price, fp9 raw. 0 when the distance is absolute.

pattern: ^(?:-?[1-9][0-9]*|0)$

Example: 1000000000

leveragestring · int32 · nullablerequired

Leverage of the order, fp9 raw. Null on close orders, which inherit the leverage of the position.

pattern: ^(?:-?[1-9][0-9]*|0)$

Example: 1000000000

indexstringrequired

Order identifier. Kept for backward compatibility, always equal to id.

Example: string

positionIdstring[]required

Position a close order is attached to. Null for orders that open or grow a position.

Array items · string

string

View example

[
  "string"
]

parentOrderIdstring[]required

Order this one was spawned from: a stop or take created out of stopTriggerPrice / takeTriggerPrice, or the limit order a stop_limit turned into. Null when the order was submitted directly.

Array items · string

string

View example

[
  "string"
]

expirationstring · date-time · nullablerequired

Always null. Kept for backward compatibility — orders do not expire on their own.

Example: 2026-05-01T12:30:00.000Z

amountstring · int32required

Size of the order, fp9 raw, in the unit its class uses: on an increase order a quote amount — the reserve while it waits, and what it actually spent once executed; on a close order (stop, take, trailing_stop) the base asset size it closes, as requested at creation.

pattern: ^(?:-?[1-9][0-9]*|0)$

Example: 1000000000

indexPricestring · int32 · nullablerequired

Index price the order executed at, fp9 raw. Null while the order has not executed.

pattern: ^(?:-?[1-9][0-9]*|0)$

Example: 1000000000

settlementOraclePricestring · int32required

Always 1000000000 (1.0). Kept for backward compatibility.

pattern: ^(?:-?[1-9][0-9]*|0)$

Example: 1000000000

createdAtstring · date-timerequired

When the order was accepted.

Example: 2026-05-01T12:30:00.000Z

errorstring[]required

Always null. Kept for backward compatibility — use errorCode.

Array items · string

string

View example

[
  "string"
]

realizedPnlstring · int32 · nullablerequired

Pnl realised by this order, fp9 raw. Set only on an executed close order; null while pending and on orders that open or grow a position.

pattern: ^(?:-?[1-9][0-9]*|0)$

Example: 1000000000

rawRealizedPnlstring · int32 · nullablerequired

Realised pnl before the 60-second adjustment, fp9 raw. Differs from realizedPnl only when the adjustment fired.

pattern: ^(?:-?[1-9][0-9]*|0)$

Example: 1000000000

profitAdjustmentAppliedbooleanrequired

Whether the 60-second adjustment capped the profit of this order — inside a minute of an open or increase the position pnl cannot grow above what it was at that moment.

Example: true

executedAfterPausebooleanrequired

Whether the order executed after a market pause. Not set by the current engine — always false.

Example: true

sizeModestring · enumrequired

How the size was expressed on creation: quote sizes the order by amount, base sizes it by baseSize.

Allowed: "quote" "base"

Example: quote

baseSizestring · int32 · nullablerequired

Order size in base asset units, fp9 raw. Null for quote-sized orders.

pattern: ^(?:-?[1-9][0-9]*|0)$

Example: 1000000000

reservedAmountstring · int32 · nullablerequired

Quote amount reserved when the order with sizeMode=base was created, fp9 raw. Stays at the original reserve after execution, while amount is rewritten to what was spent. Null for quote-sized orders, where amount is the reserve.

pattern: ^(?:-?[1-9][0-9]*|0)$

Example: 1000000000

errorCodestring[]required

Why execution failed, set together with status canceled_by_error — for example insufficient_reserve_at_execution, order_below_min_notional, order_exceeds_market_depth or slippage_tolerance. Null otherwise.

Array items · string

string

View example

[
  "string"
]

reasonstring · enum · nullablerequired

Why the platform cancelled the order itself, for example force_close or weekly_session_risk_close. Null for trader-driven cancellations.

Allowed: "force_close" "stop_accounts_fail" "stop_accounts_freeze" "stop_accounts_promote" "stop_accounts_manual" "weekly_session_risk_close" null

Example: force_close

{
  "id": "00000000-0000-4000-8000-000000000000",
  "txId": "string",
  "trader": "00000000-0000-4000-8000-000000000000",
  "market": "00000000-0000-4000-8000-000000000000",
  "status": "active",
  "type": "market",
  "direction": "long",
  "triggerPrice": "1000000000",
  "requestedTriggerPrice": "1000000000",
  "stopPrice": "1000000000",
  "limitPrice": "1000000000",
  "stopTriggerPrice": "1000000000",
  "takeTriggerPrice": "1000000000",
  "trailingStopActivationPrice": "1000000000",
  "trailingStopOffset": "1000000000",
  "trailingStopOffsetPercent": "1000000000",
  "leverage": "1000000000",
  "index": "string",
  "positionId": [
    "string"
  ],
  "parentOrderId": [
    "string"
  ],
  "expiration": "2026-05-01T12:30:00.000Z",
  "amount": "1000000000",
  "indexPrice": "1000000000",
  "settlementOraclePrice": "1000000000",
  "createdAt": "2026-05-01T12:30:00.000Z",
  "error": [
    "string"
  ],
  "realizedPnl": "1000000000",
  "rawRealizedPnl": "1000000000",
  "profitAdjustmentApplied": true,
  "executedAfterPause": true,
  "sizeMode": "quote",
  "baseSize": "1000000000",
  "reservedAmount": "1000000000",
  "errorCode": [
    "string"
  ],
  "reason": "force_close"
}