Изменить маржу позиции

PATCH/positions/{positionId}/margin

Изменить маржу позицииТорговля

Перемещает баланс в котируемой валюте в маржу открытой позиции или из неё, что вместе с этим изменяет её кредитное плечо и цену ликвидации.

Позиция должна всё ещё быть открытой, а её счёт должен принадлежать вызывающей стороне и быть active — счёт, заблокированный лимитом управляемого капитала, здесь отклоняется.
Рынок должен быть открыт и не находиться в режиме только закрытия.
marginChange: "0" принимается, и позиция возвращается без изменений.
Добавление суммы больше, чем покрывает свободный баланс, завершается ошибкой insufficient_balance; снятие суммы больше, чем позиция может выделить, завершается ошибкой non_positive_margin.

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

Авторизация

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

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

Параметры

Путь

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

Идентификатор позиции. Его аккаунт должен принадлежать вызывающему.

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

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

marginChangestring · int32обязательно

Signed quote amount to move in or out of the position margin, fp9 raw. Positive adds margin and requires that much free balance, negative withdraws it and must keep the remaining margin positive. 0 is accepted and changes nothing.

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

Пример: 1000000000

{
  "marginChange": "1000000000"
}

Примеры

curl --request PATCH 'https://api.upscale.trade/positions/{positionId}/margin' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "marginChange": "1000000000"
}'

const response = await fetch("https://api.upscale.trade/positions/{positionId}/margin", {
  method: "PATCH",
  headers: {
    "Accept": "application/json",
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: "{\n  \"marginChange\": \"1000000000\"\n}",
});
console.log(response.status, await response.text());

import requests
 
response = requests.request(
    "PATCH",
    "https://api.upscale.trade/positions/{positionId}/margin",
    headers={"Accept":"application/json","Authorization":"Bearer YOUR_API_KEY","Content-Type":"application/json"},
    data="{\n  \"marginChange\": \"1000000000\"\n}",
    timeout=30,
)
print(response.status_code, response.text)

Ответы

401

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

403

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

404

Нет позиции с этим идентификатором.

429

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

defaultОтветapplication/json

idxstring[]обязательно

Position identifier. Same value as txId.

Элементы массива · string

string

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

[
  "string"
]

txIdstring[]обязательно

Position identifier. Kept for backward compatibility, always equal to idx.

Элементы массива · string

string

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

[
  "string"
]

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

Revision of the position: incremented by every event applied to it.

Пример: 0

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

When the position was opened.

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

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

When the last event was applied to the position.

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

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

When the position was closed; null while it is still open.

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

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

Direction of the position. Same value as direction.

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

Пример: long

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

Whether the position is still open, closed by the trader, or liquidated.

Допустимо: "opened" "closed" "liquidated"

Пример: opened

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

Market the position is held 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

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

Trader account the position 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

sizestring · int32обязательно

Position size in base asset units, fp9 raw.

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

Пример: 1000000000

notionalstring · int32обязательно

Open notional of the position in quote currency, fp9 raw — size at entry price.

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

Пример: 1000000000

fractionstring · int32обязательно

Always 0. Kept for backward compatibility.

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

Пример: 1000000000

marginstring · int32обязательно

Margin currently backing the position, fp9 raw. Moves with pnl, funding and manual margin changes.

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

Пример: 1000000000

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

Realised pnl accumulated over every event of the position, fp9 raw.

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

Пример: 1000000000

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

Funding paid (negative) or received (positive) over the life of the position, fp9 raw.

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

Пример: 1000000000

rolloverFeestring · int32обязательно

Always 0. Kept for backward compatibility.

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

Пример: 1000000000

settlementOraclePricestring · int32обязательно

Always 1000000000 (1.0). Kept for backward compatibility.

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

Пример: 1000000000

feestring · int32обязательно

Trading fees charged over the life of the position, fp9 raw.

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

Пример: 1000000000

feeRatestring · int32обязательно

Fee rate applied to the position, fp9 raw fraction (1000000 = 0.1%).

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

Пример: 1000000000

exchangedQuotestring · int32обязательно

Quote amount exchanged by the most recent event, fp9 raw.

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

Пример: 1000000000

exchangedBasestring · int32обязательно

Base amount exchanged by the most recent event, fp9 raw.

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

Пример: 1000000000

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

Direction of the position.

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

Пример: long

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

Type of the most recent event applied to the position.

Допустимо: "addMargin" "removeMargin" "closePosition" "increasePosition" "liquidate" "forceClose" "payFunding"

Пример: addMargin

pnlInEventstring · int32обязательно

Realised pnl of the most recent event, fp9 raw.

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

Пример: 1000000000

rawPnlInEventstring · int32обязательно

Realised pnl of the most recent event before the 60-second adjustment, fp9 raw. Differs from pnlInEvent only when the adjustment fired.

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

Пример: 1000000000

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

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

Пример: true

holdingTimeMsstring[]обязательно

How long the position was held before the most recent close, in milliseconds, counted from the open or the last increase. Null on events that are not closes.

Элементы массива · string

string

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

[
  "string"
]

feeInEventstring · int32обязательно

Fee charged by the most recent event, fp9 raw.

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

Пример: 1000000000

fundingInEventstring · int32обязательно

Funding settled by the most recent event, fp9 raw.

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

Пример: 1000000000

rolloverFeeInEventstring · int32обязательно

Always 0. Kept for backward compatibility.

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

Пример: 1000000000

executionFeeRatestring · int32обязательно

Always 0. Kept for backward compatibility.

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

Пример: 1000000000

executionFeeInEventstring · int32обязательно

Always 0. Kept for backward compatibility.

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

Пример: 1000000000

executionFeestring · int32обязательно

Always 0. Kept for backward compatibility.

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

Пример: 1000000000

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

Timestamp of the most recent event. Same value as lastUpdatedAt.

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

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

Always true. Kept for backward compatibility.

Пример: true

roestring · int32обязательно

Return on equity of the position — realised pnl over the margin put up, fp9 raw fraction.

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

Пример: 1000000000

scalpingCoefficientstring · int32обязательно

Dynamic spread multiplier the position was charged, fp9 raw (1000000000 = 1.0). Above 1 when the trade fell inside the market scalping window.

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

Пример: 1000000000

closeReasonstring[]обязательно

Why the platform closed the position (for example weekly_session_risk_close). Null for positions closed by the trader and for open ones.

Элементы массива · string

string

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

[
  "string"
]

{
  "idx": [
    "string"
  ],
  "txId": [
    "string"
  ],
  "version": 0,
  "openedAt": "2026-05-01T12:30:00.000Z",
  "lastUpdatedAt": "2026-05-01T12:30:00.000Z",
  "closedAt": "2026-05-01T12:30:00.000Z",
  "type": "long",
  "status": "opened",
  "market": "00000000-0000-4000-8000-000000000000",
  "trader": "00000000-0000-4000-8000-000000000000",
  "size": "1000000000",
  "notional": "1000000000",
  "fraction": "1000000000",
  "margin": "1000000000",
  "pnl": "1000000000",
  "funding": "1000000000",
  "rolloverFee": "1000000000",
  "settlementOraclePrice": "1000000000",
  "fee": "1000000000",
  "feeRate": "1000000000",
  "exchangedQuote": "1000000000",
  "exchangedBase": "1000000000",
  "direction": "long",
  "eventName": "addMargin",
  "pnlInEvent": "1000000000",
  "rawPnlInEvent": "1000000000",
  "profitAdjustmentApplied": true,
  "holdingTimeMs": [
    "string"
  ],
  "feeInEvent": "1000000000",
  "fundingInEvent": "1000000000",
  "rolloverFeeInEvent": "1000000000",
  "executionFeeRate": "1000000000",
  "executionFeeInEvent": "1000000000",
  "executionFee": "1000000000",
  "timestamp": "2026-05-01T12:30:00.000Z",
  "isOnchain": true,
  "roe": "1000000000",
  "scalpingCoefficient": "1000000000",
  "closeReason": [
    "string"
  ]
}