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.
Añadir más de lo que cubre el saldo libre falla con insufficient_balance; retirar más de lo que la posición puede ceder falla con non_positive_margin.

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 · int32obligatorio

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[]obligatorio

Position identifier. Same value as txId.

Elementos del array · string

string

Ver ejemplo

[
  "string"
]

txIdstring[]obligatorio

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

Elementos del array · string

string

Ver 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

typestring · enumobligatorio

Direction of the position. Same value as direction.

Permitido: "long" "short"

Ejemplo: long

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 · int32obligatorio

Position size in base asset units, fp9 raw.

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

Ejemplo: 1000000000

notionalstring · int32obligatorio

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

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

Ejemplo: 1000000000

fractionstring · int32obligatorio

Always 0. Kept for backward compatibility.

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

Ejemplo: 1000000000

marginstring · int32obligatorio

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

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

Ejemplo: 1000000000

pnlstring · int32 · nullableobligatorio

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

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

Ejemplo: 1000000000

fundingstring · int32 · nullableobligatorio

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

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

Ejemplo: 1000000000

rolloverFeestring · int32obligatorio

Always 0. Kept for backward compatibility.

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

Ejemplo: 1000000000

settlementOraclePricestring · int32obligatorio

Always 1000000000 (1.0). Kept for backward compatibility.

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

Ejemplo: 1000000000

feestring · int32obligatorio

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

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

Ejemplo: 1000000000

feeRatestring · int32obligatorio

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

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

Ejemplo: 1000000000

exchangedQuotestring · int32obligatorio

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

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

Ejemplo: 1000000000

exchangedBasestring · int32obligatorio

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 · int32obligatorio

Realised pnl of the most recent event, fp9 raw.

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

Ejemplo: 1000000000

rawPnlInEventstring · int32obligatorio

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[]obligatorio

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.

Elementos del array · string

string

Ver ejemplo

[
  "string"
]

feeInEventstring · int32obligatorio

Fee charged by the most recent event, fp9 raw.

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

Ejemplo: 1000000000

fundingInEventstring · int32obligatorio

Funding settled by the most recent event, fp9 raw.

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

Ejemplo: 1000000000

rolloverFeeInEventstring · int32obligatorio

Always 0. Kept for backward compatibility.

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

Ejemplo: 1000000000

executionFeeRatestring · int32obligatorio

Always 0. Kept for backward compatibility.

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

Ejemplo: 1000000000

executionFeeInEventstring · int32obligatorio

Always 0. Kept for backward compatibility.

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

Ejemplo: 1000000000

executionFeestring · int32obligatorio

Always 0. Kept for backward compatibility.

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

Ejemplo: 1000000000

timestampstring · date-timeobligatorio

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

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

isOnchainbooleanobligatorio

Always true. Kept for backward compatibility.

Ejemplo: true

roestring · int32obligatorio

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 · int32obligatorio

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[]obligatorio

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

Elementos del array · string

string

Ver ejemplo

[
  "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"
  ]
}