Cambiar el margen de la posición

PATCH/positions/{positionId}/margin

Cambiar el margen de la posiciónTrading

Mueve el saldo de cotización dentro o fuera del margen de una posición abierta, lo que desplaza con ello su apalancamiento y su precio de liquidación.

La posición debe seguir abierta, y su cuenta debe pertenecer a quien llama y estar active — una cuenta bloqueada por el límite de capital gestionado se rechaza aquí.
El mercado debe estar abierto y no en modo de solo cierre.
marginChange: "0" se acepta y devuelve la posición sin cambios.
Agregar más de lo que cubre el saldo libre falla con insufficient_balance; dejar un margen nominal cero o negativo falla con non_positive_margin.
El apalancamiento resultante debe mantenerse dentro del rango permitido; de lo contrario, la solicitud falla con invalid_leverage.
Retirar margen debe dejar la posición fuera de liquidación al precio de mercado actual. Alcanzar o cruzar el precio de liquidación recalculado falla con margin_withdrawal_liquidation (HTTP 400); no se aplican cambios de margen ni de saldo.

URL base https://api.upscale.trade

Autorización

bearerhttp · bearerobligatorio

Clave de API personal, con el prefijo usk_.

Parámetros

Ruta

positionIdstring · uuidobligatorio

Identificador de posición. Su cuenta debe pertenecer al llamador.

Ejemplo: 00000000-0000-4000-8000-000000000000

Cuerpo de la solicitud · obligatorio

marginChangestring · fp9obligatorio

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

Ejemplo: 1000000000

{
  "marginChange": "1000000000"
}

Ejemplos

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)

Respuestas

401

No autorizado

403

La cuenta pertenece a otro usuario (account_access_denied), o la solicitud se autentica con una clave de API mientras api_trading está deshabilitado en la cuenta (api_trading_not_enabled). La cuenta no está en un estado activo. El mercado está en pausa (market_paused) o solo acepta órdenes de cierre (market_close_only).

404

No existe ninguna posición con este identificador.

429

Se superó el límite de velocidad de la clave de API (api_key_rate_limit_exceeded). Retry-After indica cuándo volver; el cuerpo incluye el bucket (read / write), la ventana que se activó, su límite y retryAt.

defaultRespuestaapplication/json

idxstring · nullableobligatorio

Position identifier.

Ejemplo: string

versionnumberobligatorio

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

Ejemplo: 0

openedAtstring · date-timeobligatorio

When the position was opened.

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

lastUpdatedAtstring · date-timeobligatorio

When the last event was applied to the position.

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

closedAtstring · date-time · nullableobligatorio

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

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

statusstring · enumobligatorio

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

Permitido: "opened" "closed" "liquidated"

Ejemplo: opened

marketstring · uuidobligatorio

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

Ejemplo: 00000000-0000-4000-8000-000000000000

traderstring · uuidobligatorio

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

Ejemplo: 00000000-0000-4000-8000-000000000000

sizestring · fp9obligatorio

Position size in base asset units, fp9 raw.

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

Ejemplo: 1000000000

notionalstring · fp9obligatorio

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

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

Ejemplo: 1000000000

marginstring · fp9obligatorio

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

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

Ejemplo: 1000000000

pnlstring · fp9 · nullableobligatorio

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

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

Ejemplo: 1000000000

fundingstring · fp9 · nullableobligatorio

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

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

Ejemplo: 1000000000

feestring · fp9obligatorio

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

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

Ejemplo: 1000000000

feeRatestring · fp9obligatorio

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

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

Ejemplo: 1000000000

exchangedQuotestring · fp9obligatorio

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

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

Ejemplo: 1000000000

exchangedBasestring · fp9obligatorio

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

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

Ejemplo: 1000000000

directionstring · enumobligatorio

Direction of the position.

Permitido: "long" "short"

Ejemplo: long

eventNamestring · enumobligatorio

Type of the most recent event applied to the position.

Permitido: "addMargin" "removeMargin" "closePosition" "increasePosition" "liquidate" "forceClose" "payFunding"

Ejemplo: addMargin

pnlInEventstring · fp9obligatorio

Realised pnl of the most recent event, fp9 raw.

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

Ejemplo: 1000000000

rawPnlInEventstring · fp9obligatorio

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

Ejemplo: 1000000000

profitAdjustmentAppliedbooleanobligatorio

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.

Ejemplo: true

holdingTimeMsstring · nullableobligatorio

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.

Ejemplo: string

feeInEventstring · fp9obligatorio

Fee charged by the most recent event, fp9 raw.

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

Ejemplo: 1000000000

fundingInEventstring · fp9obligatorio

Funding settled by the most recent event, fp9 raw.

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

Ejemplo: 1000000000

roestring · fp9obligatorio

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

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

Ejemplo: 1000000000

scalpingCoefficientstring · fp9obligatorio

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

Ejemplo: 1000000000

closeReasonstring · nullableobligatorio

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

Ejemplo: string

{
  "idx": "string",
  "version": 0,
  "openedAt": "2026-05-01T12:30:00.000Z",
  "lastUpdatedAt": "2026-05-01T12:30:00.000Z",
  "closedAt": "2026-05-01T12:30:00.000Z",
  "status": "opened",
  "market": "00000000-0000-4000-8000-000000000000",
  "trader": "00000000-0000-4000-8000-000000000000",
  "size": "1000000000",
  "notional": "1000000000",
  "margin": "1000000000",
  "pnl": "1000000000",
  "funding": "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",
  "roe": "1000000000",
  "scalpingCoefficient": "1000000000",
  "closeReason": "string"
}