# Cambiar el margen de la posición
`PATCH /positions/{positionId}/margin`
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`.
## Autorización
bearer: http · bearer (obligatorio). Clave de API personal, con el prefijo `usk_`.
## Parámetros
- path: positionId (string · uuid; obligatorio). Identificador de posición. Su cuenta debe pertenecer al llamador.
Tipo: string · uuid
format: uuid
## Cuerpo de la solicitud · MarginChangeRequest
application/json · obligatorio
Esquema: MarginChangeRequest
Tipo: object
Campos obligatorios: marginChange
Tipos de campos obligatorios: marginChange (string · int32; obligatorio)
- marginChange (string · int32; obligatorio)
marginChange ejemplo: 1000000000
marginChange.Tipo: string · int32
marginChange.Importe de cotización con signo para mover dentro o fuera del margen de la posición, fp9 en bruto. Positivo añade margen y requiere esa cantidad de saldo libre; negativo lo retira y debe mantener positivo el margen restante. `0` se acepta y no cambia nada.
marginChange.format: int32
marginChange.pattern: ^(?:-?[1-9][0-9]*|0)$
Ejemplo
```json
{
"marginChange": "1000000000"
}
```
## Ejemplo · cURL
```bash
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"
}'
```
## Ejemplo · JavaScript
```javascript
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());
```
## Ejemplo · Python
```python
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)
```
## Respuesta 401
**401** — No autorizado
## Respuesta 403
**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`).
## Respuesta 404
**404** — No existe ninguna posición con este identificador.
## Respuesta 429
**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`.
## Respuesta default · PositionResponse
**default** application/json — Respuesta
Esquema: PositionResponse
Tipo: object
Campos obligatorios: idx, txId, version, openedAt, lastUpdatedAt, closedAt, type, status, market, trader, size, notional, fraction, margin, pnl, funding, rolloverFee, settlementOraclePrice, fee, feeRate, exchangedQuote, exchangedBase, direction, eventName, pnlInEvent, rawPnlInEvent, profitAdjustmentApplied, holdingTimeMs, feeInEvent, fundingInEvent, rolloverFeeInEvent, executionFeeRate, executionFeeInEvent, executionFee, timestamp, isOnchain, roe, scalpingCoefficient, closeReason
Tipos de campos obligatorios: idx (string[]; obligatorio), txId (string[]; obligatorio), version (number; obligatorio), openedAt (string · date-time; obligatorio), lastUpdatedAt (string · date-time; obligatorio), closedAt (string · date-time · nullable; obligatorio), type (string · enum; obligatorio), status (string · enum; obligatorio), market (string · uuid; obligatorio), trader (string · uuid; obligatorio), size (string · int32; obligatorio), notional (string · int32; obligatorio), fraction (string · int32; obligatorio), margin (string · int32; obligatorio), pnl (string · int32 · nullable; obligatorio), funding (string · int32 · nullable; obligatorio), rolloverFee (string · int32; obligatorio), settlementOraclePrice (string · int32; obligatorio), fee (string · int32; obligatorio), feeRate (string · int32; obligatorio), exchangedQuote (string · int32; obligatorio), exchangedBase (string · int32; obligatorio), direction (string · enum; obligatorio), eventName (string · enum; obligatorio), pnlInEvent (string · int32; obligatorio), rawPnlInEvent (string · int32; obligatorio), profitAdjustmentApplied (boolean; obligatorio), holdingTimeMs (string[]; obligatorio), feeInEvent (string · int32; obligatorio), fundingInEvent (string · int32; obligatorio), rolloverFeeInEvent (string · int32; obligatorio), executionFeeRate (string · int32; obligatorio), executionFeeInEvent (string · int32; obligatorio), executionFee (string · int32; obligatorio), timestamp (string · date-time; obligatorio), isOnchain (boolean; obligatorio), roe (string · int32; obligatorio), scalpingCoefficient (string · int32; obligatorio), closeReason (string[]; obligatorio)
- idx (string[]; obligatorio)
idx ejemplo: [
"string"
]
idx.Tipo: string[]
idx.Identificador de la posición. Mismo valor que `txId`.
idx.[]Tipo: string
- txId (string[]; obligatorio)
txId ejemplo: [
"string"
]
txId.Tipo: string[]
txId.Identificador de la posición. Se mantiene por compatibilidad hacia atrás, siempre igual a `idx`.
txId.[]Tipo: string
- version (number; obligatorio)
version ejemplo: 0
version.Tipo: number
version.Revisión de la posición: incrementada por cada evento que se le aplica.
- openedAt (string · date-time; obligatorio)
openedAt ejemplo: 2026-05-01T12:30:00.000Z
openedAt.Tipo: string · date-time
openedAt.Cuándo se abrió la posición.
openedAt.format: date-time
- lastUpdatedAt (string · date-time; obligatorio)
lastUpdatedAt ejemplo: 2026-05-01T12:30:00.000Z
lastUpdatedAt.Tipo: string · date-time
lastUpdatedAt.Cuándo se aplicó el último evento a la posición.
lastUpdatedAt.format: date-time
- closedAt (string · date-time · nullable; obligatorio)
closedAt ejemplo: 2026-05-01T12:30:00.000Z
closedAt.Tipo: string · date-time · nullable
closedAt.Cuándo se cerró la posición; null mientras sigue abierta.
closedAt.format: date-time
- type (string · enum; obligatorio)
type ejemplo: long
type.Tipo: string · enum
type.Dirección de la posición. Mismo valor que `direction`.
type.Valores permitidos: ["long","short"]
- status (string · enum; obligatorio)
status ejemplo: opened
status.Tipo: string · enum
status.Si la posición sigue abierta, fue cerrada por el trader o fue liquidada.
status.Valores permitidos: ["opened","closed","liquidated"]
- market (string · uuid; obligatorio)
market ejemplo: 00000000-0000-4000-8000-000000000000
market.Tipo: string · uuid
market.Mercado en el que se mantiene la posición.
market.format: uuid
market.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})$
- trader (string · uuid; obligatorio)
trader ejemplo: 00000000-0000-4000-8000-000000000000
trader.Tipo: string · uuid
trader.Cuenta del trader a la que pertenece la posición.
trader.format: uuid
trader.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})$
- size (string · int32; obligatorio)
size ejemplo: 1000000000
size.Tipo: string · int32
size.Tamaño de la posición en unidades del activo base, fp9 sin procesar.
size.format: int32
size.pattern: ^(?:-?[1-9][0-9]*|0)$
- notional (string · int32; obligatorio)
notional ejemplo: 1000000000
notional.Tipo: string · int32
notional.Nocional abierto de la posición en moneda de cotización, fp9 sin procesar — tamaño al precio de entrada.
notional.format: int32
notional.pattern: ^(?:-?[1-9][0-9]*|0)$
- fraction (string · int32; obligatorio)
fraction ejemplo: 1000000000
fraction.Tipo: string · int32
fraction.Siempre `0`. Se mantiene por compatibilidad hacia atrás.
fraction.format: int32
fraction.pattern: ^(?:-?[1-9][0-9]*|0)$
- margin (string · int32; obligatorio)
margin ejemplo: 1000000000
margin.Tipo: string · int32
margin.Margen que actualmente respalda la posición, fp9 sin procesar. Cambia con pnl, financiación y cambios manuales de margen.
margin.format: int32
margin.pattern: ^(?:-?[1-9][0-9]*|0)$
- pnl (string · int32 · nullable; obligatorio)
pnl ejemplo: 1000000000
pnl.Tipo: string · int32 · nullable
pnl.Pnl realizado acumulado a lo largo de cada evento de la posición, fp9 sin procesar.
pnl.format: int32
pnl.pattern: ^(?:-?[1-9][0-9]*|0)$
- funding (string · int32 · nullable; obligatorio)
funding ejemplo: 1000000000
funding.Tipo: string · int32 · nullable
funding.Financiación pagada (negativa) o recibida (positiva) durante la vida de la posición, fp9 en bruto.
funding.format: int32
funding.pattern: ^(?:-?[1-9][0-9]*|0)$
- rolloverFee (string · int32; obligatorio)
rolloverFee ejemplo: 1000000000
rolloverFee.Tipo: string · int32
rolloverFee.Siempre `0`. Se mantiene por compatibilidad hacia atrás.
rolloverFee.format: int32
rolloverFee.pattern: ^(?:-?[1-9][0-9]*|0)$
- settlementOraclePrice (string · int32; obligatorio)
settlementOraclePrice ejemplo: 1000000000
settlementOraclePrice.Tipo: string · int32
settlementOraclePrice.Siempre `1000000000` (1.0). Se mantiene por compatibilidad con versiones anteriores.
settlementOraclePrice.format: int32
settlementOraclePrice.pattern: ^(?:-?[1-9][0-9]*|0)$
- fee (string · int32; obligatorio)
fee ejemplo: 1000000000
fee.Tipo: string · int32
fee.Comisiones de trading cobradas durante la vida de la posición, fp9 en bruto.
fee.format: int32
fee.pattern: ^(?:-?[1-9][0-9]*|0)$
- feeRate (string · int32; obligatorio)
feeRate ejemplo: 1000000000
feeRate.Tipo: string · int32
feeRate.Tasa de comisión aplicada a la posición, fp9 fracción en bruto (`1000000` = 0.1%).
feeRate.format: int32
feeRate.pattern: ^(?:-?[1-9][0-9]*|0)$
- exchangedQuote (string · int32; obligatorio)
exchangedQuote ejemplo: 1000000000
exchangedQuote.Tipo: string · int32
exchangedQuote.Importe de cotización intercambiado por el evento más reciente, fp9 en bruto.
exchangedQuote.format: int32
exchangedQuote.pattern: ^(?:-?[1-9][0-9]*|0)$
- exchangedBase (string · int32; obligatorio)
exchangedBase ejemplo: 1000000000
exchangedBase.Tipo: string · int32
exchangedBase.Importe base intercambiado por el evento más reciente, fp9 en bruto.
exchangedBase.format: int32
exchangedBase.pattern: ^(?:-?[1-9][0-9]*|0)$
- direction (string · enum; obligatorio)
direction ejemplo: long
direction.Tipo: string · enum
direction.Dirección de la posición.
direction.Valores permitidos: ["long","short"]
- eventName (string · enum; obligatorio)
eventName ejemplo: addMargin
eventName.Tipo: string · enum
eventName.Tipo del evento más reciente aplicado a la posición.
eventName.Valores permitidos: ["addMargin","removeMargin","closePosition","increasePosition","liquidate","forceClose","payFunding"]
- pnlInEvent (string · int32; obligatorio)
pnlInEvent ejemplo: 1000000000
pnlInEvent.Tipo: string · int32
pnlInEvent.Pnl realizado del evento más reciente, fp9 en bruto.
pnlInEvent.format: int32
pnlInEvent.pattern: ^(?:-?[1-9][0-9]*|0)$
- rawPnlInEvent (string · int32; obligatorio)
rawPnlInEvent ejemplo: 1000000000
rawPnlInEvent.Tipo: string · int32
rawPnlInEvent.Pnl realizado del evento más reciente antes del ajuste de 60 segundos, fp9 en bruto. Difiere de `pnlInEvent` solo cuando se activó el ajuste.
rawPnlInEvent.format: int32
rawPnlInEvent.pattern: ^(?:-?[1-9][0-9]*|0)$
- profitAdjustmentApplied (boolean; obligatorio)
profitAdjustmentApplied ejemplo: true
profitAdjustmentApplied.Tipo: boolean
profitAdjustmentApplied.Si el ajuste de 60 segundos limitó la ganancia del evento más reciente — dentro de un minuto de una apertura o un aumento de la posición, el pnl de la posición no puede crecer por encima de lo que era en ese momento.
- holdingTimeMs (string[]; obligatorio)
holdingTimeMs ejemplo: [
"string"
]
holdingTimeMs.Tipo: string[]
holdingTimeMs.Cuánto tiempo se mantuvo la posición antes del cierre más reciente, en milisegundos, contado desde la apertura o el último incremento. Nulo en eventos que no son cierres.
holdingTimeMs.[]Tipo: string
- feeInEvent (string · int32; obligatorio)
feeInEvent ejemplo: 1000000000
feeInEvent.Tipo: string · int32
feeInEvent.Comisión cobrada por el evento más reciente, fp9 en bruto.
feeInEvent.format: int32
feeInEvent.pattern: ^(?:-?[1-9][0-9]*|0)$
- fundingInEvent (string · int32; obligatorio)
fundingInEvent ejemplo: 1000000000
fundingInEvent.Tipo: string · int32
fundingInEvent.Financiación liquidada por el evento más reciente, fp9 en bruto.
fundingInEvent.format: int32
fundingInEvent.pattern: ^(?:-?[1-9][0-9]*|0)$
- rolloverFeeInEvent (string · int32; obligatorio)
rolloverFeeInEvent ejemplo: 1000000000
rolloverFeeInEvent.Tipo: string · int32
rolloverFeeInEvent.Siempre `0`. Se mantiene por compatibilidad hacia atrás.
rolloverFeeInEvent.format: int32
rolloverFeeInEvent.pattern: ^(?:-?[1-9][0-9]*|0)$
- executionFeeRate (string · int32; obligatorio)
executionFeeRate ejemplo: 1000000000
executionFeeRate.Tipo: string · int32
executionFeeRate.Siempre `0`. Se mantiene por compatibilidad hacia atrás.
executionFeeRate.format: int32
executionFeeRate.pattern: ^(?:-?[1-9][0-9]*|0)$
- executionFeeInEvent (string · int32; obligatorio)
executionFeeInEvent ejemplo: 1000000000
executionFeeInEvent.Tipo: string · int32
executionFeeInEvent.Siempre `0`. Se mantiene por compatibilidad hacia atrás.
executionFeeInEvent.format: int32
executionFeeInEvent.pattern: ^(?:-?[1-9][0-9]*|0)$
- executionFee (string · int32; obligatorio)
executionFee ejemplo: 1000000000
executionFee.Tipo: string · int32
executionFee.Siempre `0`. Se mantiene por compatibilidad hacia atrás.
executionFee.format: int32
executionFee.pattern: ^(?:-?[1-9][0-9]*|0)$
- timestamp (string · date-time; obligatorio)
timestamp ejemplo: 2026-05-01T12:30:00.000Z
timestamp.Tipo: string · date-time
timestamp.Marca de tiempo del evento más reciente. Mismo valor que `lastUpdatedAt`.
timestamp.format: date-time
- isOnchain (boolean; obligatorio)
isOnchain ejemplo: true
isOnchain.Tipo: boolean
isOnchain.Siempre `true`. Se mantiene por compatibilidad con versiones anteriores.
- roe (string · int32; obligatorio)
roe ejemplo: 1000000000
roe.Tipo: string · int32
roe.Rentabilidad sobre el capital de la posición — pnl realizado sobre el margen aportado, fp9 fracción sin procesar.
roe.format: int32
roe.pattern: ^(?:-?[1-9][0-9]*|0)$
- scalpingCoefficient (string · int32; obligatorio)
scalpingCoefficient ejemplo: 1000000000
scalpingCoefficient.Tipo: string · int32
scalpingCoefficient.Multiplicador dinámico de spread que se aplicó a la posición, fp9 sin procesar (`1000000000` = 1.0). Por encima de 1 cuando la operación quedó dentro de la ventana de scalping del mercado.
scalpingCoefficient.format: int32
scalpingCoefficient.pattern: ^(?:-?[1-9][0-9]*|0)$
- closeReason (string[]; obligatorio)
closeReason ejemplo: [
"string"
]
closeReason.Tipo: string[]
closeReason.Por qué la plataforma cerró la posición (por ejemplo, `weekly_session_risk_close`). Nulo para las posiciones cerradas por el trader y para las abiertas.
closeReason.[]Tipo: string
Ejemplo
```json
{
"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"
]
}
```