Создать новый ордер

POST/orders

Создать новый ордерТорговля

Размещает ордер и возвращает его в том виде, в котором его сохранил торговый движок. Ордера на увеличение (market, limit, stop_market, stop_limit) открывают или увеличивают позицию; ордера закрытия (stop, take, trailing_stop) привязываются к существующей позиции через positionId.

amount читается в разных единицах для каждого из двух: в ордере на увеличение это сумма в котируемой валюте, зарезервированная из свободного баланса; в ордере на закрытие это размер базового актива позиции для закрытия, при этом ничего не резервируется. Остальные поля размера (expectedAmount, sizeMode, baseSize, leverage) относятся только к ордерам на увеличение.

Помимо схемы на уровне полей, запрос проверяется на:

Форма для типа. Каждое отклонение здесь — это 400, код которого указывает на проблемную комбинацию полей:
- размер — amount_not_positive, base_size_required, base_size_negative, base_size_not_allowed;
- плечо — leverage_required, leverage_negative;
- цена триггера — trigger_price_required, trigger_price_negative;
- стоп-лосс / тейк-профит, привязанные к ордеру на увеличение — 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_required, stop_limit_price_negative, stop_limit_price_gt_trigger_price, stop_limit_price_lt_trigger_price;
- трейлинг-стоп — 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;
- trailing_stop_offset_too_large — абсолютное смещение трейлинга для LONG привело бы к нулевой или отрицательной цене срабатывания;
- ордера на закрытие — position_id_required.
Плечо ордера на увеличение. Должно оставаться в границах рынка: не ниже минимума рынка и не выше максимума фазы, с invalid_leverage (leverage плюс minLeverage или maxLeverage в теле).
Аккаунт. Должен принадлежать вызывающему и находиться в торговом статусе; ордера на увеличение дополнительно отклоняются, пока аккаунт заблокирован лимитом управляемого капитала, и требуют, чтобы amount был доступен как свободный баланс.
Рынок. Должен быть открыт и относиться к категории, в которой аккаунт может торговать (crypto или RWA). Рынок только для закрытия принимает только take-ордер, созданный без триггерной цены.
Позиция, когда задан positionId: она должна существовать (position_not_found), быть открытой, находиться на том же аккаунте, принадлежать тому же рынку и иметь то же направление, что и ордер (position_not_available).
Триггерная цена, относительно текущей рыночной цены и — для stop / take — относительно цены ликвидации позиции (trigger_price_gt_current, trigger_price_lt_current, trigger_price_gt_liquidation, trigger_price_lt_liquidation). market-ордер с прикреплённым стоп-лоссом / тейк-профитом проверяется относительно цены ликвидации, которая будет у его позиции после исполнения: market_price_unavailable когда нет текущей цены для проверки, order_validation_invariant когда поля размера, необходимые для этого прогноза, отсутствуют.
Нотионал ордера на увеличение. (amount − fee) × leverage должен укладываться в максимальный открытый нотионал, который рынок допускает в этом направлении (order_exceeds_max_open_notional).

Отложенный ордер здесь не исполняется, поэтому он всё ещё может завершиться ошибкой, когда его триггер сработает позже: тогда он получает статус canceled_by_error и errorCode (insufficient_reserve_at_execution, order_below_min_notional, order_exceeds_market_depth, order_exceeds_max_open_notional, order_exceeds_max_price_impact, order_zero_size_at_execution, slippage_tolerance, market_close_only_at_execution), а его резерв освобождается. Ордер на увеличение также отменяется с order_exceeds_max_price_impact, когда его влияние на цену без статического спреда превышает рыночный maxPriceImpact (0 означает отсутствие лимита).

Отправьте заголовок x-idempotency-key, чтобы сделать вызов безопасным при повторной отправке: в пределах окна повторной отправки, указанного в этом заголовке, тот же ключ на том же маршруте воспроизводит сохранённый ответ (помеченный X-Idempotency-Cached: true и X-Idempotency-Timestamp) вместо повторного выполнения, а второй вызов, поступивший, пока первый всё ещё выполняется, получает 409 (idempotency_key_in_flight).

Базовый URL https://api.upscale.trade

Авторизация

bearerhttp · bearerобязательно

Персональный API-ключ с префиксом usk_.

Параметры

Заголовок

x-idempotency-keystringнеобязательно

Ключ идемпотентности — любая непрозрачная строка, uuid v4 хорошо подходит. Повторный вызов с тем же ключом на этом маршруте в течение 1 часа воспроизводит сохранённый ответ вместо повторного выполнения; при воспроизведении возвращаются X-Idempotency-Cached: true и X-Idempotency-Timestamp. Чтобы отказаться, не указывайте заголовок.

Пример: 9f1c2b7e-5a3d-4f61-9b0e-2c7d4a8e1f35

Тело запроса · обязательно

accountIdstring · uuidобязательно

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})$

Пример: 00000000-0000-4000-8000-000000000000

marketIdstring · uuidобязательно

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})$

Пример: 00000000-0000-4000-8000-000000000000

typestring · enumобязательно

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.

Допустимо: "market" "limit" "stop" "trailing_stop" "take" "stop_limit" "stop_market"

Пример: market

directionstring · enumобязательно

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

Допустимо: "long" "short"

Пример: long

amountstring · fp9обязательно

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)$

Пример: 100000000000

Необязательные поля: 12

positionIdstring · uuid · nullableнеобязательно

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})$

Пример: 00000000-0000-4000-8000-000000000000

expectedAmountstring · fp9 · nullableнеобязательно

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)$

Пример: 0

leveragestring · fp9 · nullableнеобязательно

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)$

Пример: 10000000000

triggerPricestring · fp9 · nullableнеобязательно

Price at which the order fires, fp9 raw. Required for limit, stop, take, stop_market and stop_limit, and ignored for market. stop needs a positive price. take with 0 closes amount of the position at market right away; it is the only order a close-only market accepts.

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

Пример: 65000000000000

stopTriggerPricestring · fp9 · nullableнеобязательно

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)$

Пример: 1000000000

takeTriggerPricestring · fp9 · nullableнеобязательно

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)$

Пример: 1000000000

trailingStopActivationPricestring · fp9 · nullableнеобязательно

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)$

Пример: 1000000000

trailingStopOffsetstring · fp9 · nullableнеобязательно

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

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

Пример: 1000000000

trailingStopOffsetPercentstring · fp9 · nullableнеобязательно

Trailing distance as a price multiplier, fp9 raw: one minus the percent, so 5% is 950000000. The stop trails at the best price × multiplier for long and at the best price × (2 − multiplier) for short. Strictly below 1000000000. Exactly one of trailingStopOffset / trailingStopOffsetPercent is required.

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

Пример: 950000000

stopLimitPricestring · fp9 · nullableнеобязательно

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)$

Пример: 1000000000

sizeModestring · enumнеобязательно

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.

Допустимо: "quote" "base"

Пример: quote

baseSizestring · fp9 · nullableнеобязательно

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)$

Пример: 1000000000

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

Примеры

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)

Ответы

401

Неавторизовано

403

Аккаунт принадлежит другому пользователю (account_access_denied), или запрос аутентифицирован с помощью API-ключа, тогда как api_trading отключён на аккаунте (api_trading_not_enabled). Торговля на аккаунте завершена в его текущем статусе (challenge_closed), или аккаунт заблокирован лимитом управляемого капитала (funded_limit_trading_locked). Рынок приостановлен (market_paused) или принимает только ордера на закрытие (market_close_only).

404

Нет такого аккаунта, рынка или позиции.

409

Другой вызов с тем же x-idempotency-key всё ещё выполняется (idempotency_key_in_flight). Повторите попытку, когда он завершится.

429

Превышен лимит частоты запросов API-ключа (api_key_rate_limit_exceeded). Retry-After указывает, когда вернуться; тело содержит бакет (read / write), окно, которое сработало, его лимит и retryAt.

defaultОтветapplication/json

idstring · uuidобязательно

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})$

Пример: 00000000-0000-4000-8000-000000000000

traderstring · uuidобязательно

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})$

Пример: 00000000-0000-4000-8000-000000000000

marketstring · uuidобязательно

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})$

Пример: 00000000-0000-4000-8000-000000000000

statusstring · enumобязательно

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.

Допустимо: "active" "canceled" "canceled_by_update" "canceled_by_error" "canceled_by_position" "executed"

Пример: active

typestring · enumобязательно

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

Допустимо: "market" "limit" "stop" "trailing_stop" "take" "stop_limit" "stop_market" "liquidation"

Пример: market

directionstring · enumобязательно

Order direction.

Допустимо: "long" "short"

Пример: long

triggerPricestring · fp9обязательно

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

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

Пример: 1000000000

requestedTriggerPricestring · fp9 · nullableобязательно

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)$

Пример: 1000000000

stopPricestring · fp9обязательно

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

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

Пример: 1000000000

limitPricestring · fp9обязательно

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)$

Пример: 1000000000

stopTriggerPricestring · fp9обязательно

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

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

Пример: 1000000000

takeTriggerPricestring · fp9обязательно

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

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

Пример: 1000000000

trailingStopActivationPricestring · fp9обязательно

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

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

Пример: 1000000000

trailingStopOffsetstring · fp9обязательно

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

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

Пример: 1000000000

trailingStopOffsetPercentstring · fp9обязательно

Trailing distance as a price multiplier, fp9 raw: one minus the percent, so 5% is 950000000. 0 when the distance is absolute.

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

Пример: 1000000000

leveragestring · fp9 · nullableобязательно

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

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

Пример: 1000000000

positionIdstring · nullableобязательно

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

Пример: string

parentOrderIdstring · nullableобязательно

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.

Пример: string

amountstring · fp9обязательно

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)$

Пример: 1000000000

indexPricestring · fp9 · nullableобязательно

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

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

Пример: 1000000000

recentVolumestring · fp9 · nullableобязательно

Volume of the previous opens and increases on the same account, market and direction that was still counted in the price impact of this order when it executed, USD fp9 raw. The recovery window is configurable, 60 seconds by default. Fixed at execution. Null for orders that have not executed, close orders and markets without dynamic price impact.

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

Пример: 1000000000

priceImpactstring · fp9 · nullableобязательно

Price impact applied to this open or increase, excluding the static spread, as a fraction fp9 raw (10000000 = 1%). Includes the recent volume in recentVolume. Fixed at execution. Null for orders that have not executed, close orders and markets without dynamic price impact.

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

Пример: 1000000000

createdAtstring · date-timeобязательно

When the order was accepted.

Пример: 2026-05-01T12:30:00.000Z

realizedPnlstring · fp9 · nullableобязательно

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)$

Пример: 1000000000

rawRealizedPnlstring · fp9 · nullableобязательно

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

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

Пример: 1000000000

profitAdjustmentAppliedbooleanобязательно

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.

Пример: true

sizeModestring · enumобязательно

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

Допустимо: "quote" "base"

Пример: quote

baseSizestring · fp9 · nullableобязательно

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

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

Пример: 1000000000

reservedAmountstring · fp9 · nullableобязательно

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)$

Пример: 1000000000

errorCodestring · nullableобязательно

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.

Пример: string

reasonstring · enum · nullableобязательно

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

Допустимо: "force_close" "stop_accounts_fail" "stop_accounts_freeze" "stop_accounts_promote" "stop_accounts_manual" "weekly_session_risk_close"

Пример: force_close

vpiobject · nullableобязательно

VPI parameters of the market at the moment the order executed. Null while the order has not executed.

Объект · 5 поля

spreadstring · fp9обязательно

Spread charged on top of the index price, fp9 raw fraction.

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

Пример: 1000000000

marketDepthLongstringобязательно

Depth on the long side, in whole USD — not fp9.

pattern: ^-?[0-9]+(\.[0-9]+)?$

Пример: 45604631.000000000

marketDepthShortstringобязательно

Depth on the short side, in whole USD — not fp9.

pattern: ^-?[0-9]+(\.[0-9]+)?$

Пример: 38744214.000000000

coefficientLongstring · fp9обязательно

Price-impact coefficient applied to long orders, fp9 raw.

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

Пример: 1000000000

coefficientShortstring · fp9обязательно

Price-impact coefficient applied to short orders, fp9 raw.

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

Пример: 1000000000

Посмотреть пример

{
  "spread": "1000000000",
  "marketDepthLong": "45604631.000000000",
  "marketDepthShort": "38744214.000000000",
  "coefficientLong": "1000000000",
  "coefficientShort": "1000000000"
}

{
  "id": "00000000-0000-4000-8000-000000000000",
  "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",
  "positionId": "string",
  "parentOrderId": "string",
  "amount": "1000000000",
  "indexPrice": "1000000000",
  "recentVolume": "1000000000",
  "priceImpact": "1000000000",
  "createdAt": "2026-05-01T12:30:00.000Z",
  "realizedPnl": "1000000000",
  "rawRealizedPnl": "1000000000",
  "profitAdjustmentApplied": true,
  "sizeMode": "quote",
  "baseSize": "1000000000",
  "reservedAmount": "1000000000",
  "errorCode": "string",
  "reason": "force_close",
  "vpi": {
    "spread": "1000000000",
    "marketDepthLong": "45604631.000000000",
    "marketDepthShort": "38744214.000000000",
    "coefficientLong": "1000000000",
    "coefficientShort": "1000000000"
  }
}