Obtener todos los eventos por posición

GET/positions/{positionId}/history

Obtener todos los eventos por posiciónTrading

Qué ocurrió con una posición, las más recientes primero: aumentos, cierres parciales y totales, liquidación, cierre forzoso, cambios de margen.

Los pagos de financiación quedan fuera de este feed.
Un cierre forzoso lleva consigo el evento de mercado que tiene detrás, que es donde reside el motivo del mismo.

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

Ejemplos

curl --request GET 'https://api.upscale.trade/positions/{positionId}/history' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY'

const response = await fetch("https://api.upscale.trade/positions/{positionId}/history", {
  method: "GET",
  headers: {
    "Accept": "application/json",
    "Authorization": "Bearer YOUR_API_KEY"
  },
});
console.log(response.status, await response.text());

import requests
 
response = requests.request(
    "GET",
    "https://api.upscale.trade/positions/{positionId}/history",
    headers={"Accept":"application/json","Authorization":"Bearer YOUR_API_KEY"},
    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).

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

Array de PositionEventResponse

idxstring[]obligatorio

Identificador de la posición. Mismo valor que txId.

Elementos del array · string

string

Ver ejemplo

[
  "string"
]

txIdstring[]obligatorio

Identificador de la posición. Se mantiene por compatibilidad hacia atrás, siempre igual a idx.

Elementos del array · string

string

Ver ejemplo

[
  "string"
]

versionnumberobligatorio

Revisión de la posición: incrementada por cada evento que se le aplica.

Ejemplo: 0

openedAtstring · date-timeobligatorio

Cuándo se abrió la posición.

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

lastUpdatedAtstring · date-timeobligatorio

Cuándo se aplicó el último evento a la posición.

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

closedAtstring · date-time · nullableobligatorio

Cuándo se cerró la posición; null mientras sigue abierta.

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

typestring · enumobligatorio

Dirección de la posición. Mismo valor que direction.

Permitido: "long" "short"

Ejemplo: long

statusstring · enumobligatorio

Si la posición sigue abierta, fue cerrada por el trader o fue liquidada.

Permitido: "opened" "closed" "liquidated"

Ejemplo: opened

marketstring · uuidobligatorio

Mercado en el que se mantiene la posición.

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

Cuenta del trader a la que pertenece la posición.

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

Tamaño de la posición en unidades del activo base, fp9 sin procesar.

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

Ejemplo: 1000000000

notionalstring · int32obligatorio

Nocional abierto de la posición en moneda de cotización, fp9 sin procesar — tamaño al precio de entrada.

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

Ejemplo: 1000000000

fractionstring · int32obligatorio

Siempre 0. Se mantiene por compatibilidad hacia atrás.

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

Ejemplo: 1000000000

marginstring · int32obligatorio

Margen que actualmente respalda la posición, fp9 sin procesar. Cambia con pnl, financiación y cambios manuales de margen.

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

Ejemplo: 1000000000

pnlstring · int32 · nullableobligatorio

Pnl realizado acumulado a lo largo de cada evento de la posición, fp9 sin procesar.

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

Ejemplo: 1000000000

fundingstring · int32 · nullableobligatorio

Financiación pagada (negativa) o recibida (positiva) durante la vida de la posición, fp9 en bruto.

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

Ejemplo: 1000000000

rolloverFeestring · int32obligatorio

Siempre 0. Se mantiene por compatibilidad hacia atrás.

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

Ejemplo: 1000000000

settlementOraclePricestring · int32obligatorio

Siempre 1000000000 (1.0). Se mantiene por compatibilidad con versiones anteriores.

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

Ejemplo: 1000000000

feestring · int32obligatorio

Comisiones de trading cobradas durante la vida de la posición, fp9 en bruto.

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

Ejemplo: 1000000000

feeRatestring · int32obligatorio

Tasa de comisión aplicada a la posición, fp9 fracción en bruto (1000000 = 0.1%).

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

Ejemplo: 1000000000

exchangedQuotestring · int32obligatorio

Importe de cotización intercambiado por el evento más reciente, fp9 en bruto.

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

Ejemplo: 1000000000

exchangedBasestring · int32obligatorio

Importe base intercambiado por el evento más reciente, fp9 en bruto.

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

Ejemplo: 1000000000

directionstring · enumobligatorio

Dirección de la posición.

Permitido: "long" "short"

Ejemplo: long

eventNamestring · enumobligatorio

Tipo del evento más reciente aplicado a la posición.

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

Ejemplo: addMargin

pnlInEventstring · int32obligatorio

Pnl realizado del evento más reciente, fp9 en bruto.

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

Ejemplo: 1000000000

rawPnlInEventstring · int32obligatorio

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.

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

Ejemplo: 1000000000

profitAdjustmentAppliedbooleanobligatorio

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.

Ejemplo: true

holdingTimeMsstring[]obligatorio

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.

Elementos del array · string

string

Ver ejemplo

[
  "string"
]

feeInEventstring · int32obligatorio

Comisión cobrada por el evento más reciente, fp9 en bruto.

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

Ejemplo: 1000000000

fundingInEventstring · int32obligatorio

Financiación liquidada por el evento más reciente, fp9 en bruto.

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

Ejemplo: 1000000000

rolloverFeeInEventstring · int32obligatorio

Siempre 0. Se mantiene por compatibilidad hacia atrás.

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

Ejemplo: 1000000000

executionFeeRatestring · int32obligatorio

Siempre 0. Se mantiene por compatibilidad hacia atrás.

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

Ejemplo: 1000000000

executionFeeInEventstring · int32obligatorio

Siempre 0. Se mantiene por compatibilidad hacia atrás.

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

Ejemplo: 1000000000

executionFeestring · int32obligatorio

Siempre 0. Se mantiene por compatibilidad hacia atrás.

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

Ejemplo: 1000000000

timestampstring · date-timeobligatorio

Marca de tiempo del evento más reciente. Mismo valor que lastUpdatedAt.

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

isOnchainbooleanobligatorio

Siempre true. Se mantiene por compatibilidad con versiones anteriores.

Ejemplo: true

roestring · int32obligatorio

Rentabilidad sobre el capital de la posición — pnl realizado sobre el margen aportado, fp9 fracción sin procesar.

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

Ejemplo: 1000000000

scalpingCoefficientstring · int32obligatorio

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.

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

Ejemplo: 1000000000

closeReasonstring[]obligatorio

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.

Elementos del array · string

string

Ver ejemplo

[
  "string"
]

orderobject · nullableobligatorio

Orden que produjo este evento; null para eventos que la plataforma generó por sí misma, como financiación o un cierre forzoso.

Objeto · 35 campos

idstring · uuidobligatorio

Identificador de la orden.

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

txIdstringobligatorio

Identificador de la orden. Se conserva por compatibilidad con versiones anteriores, siempre igual a id.

Ejemplo: string

traderstring · uuidobligatorio

Cuenta del trader a la que pertenece la orden.

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

marketstring · uuidobligatorio

Mercado en el que se coloca la orden.

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

statusstring · enumobligatorio

Estado del ciclo de vida: active mientras espera, executed una vez ejecutada, canceled cuando es cancelada por el trader o la plataforma, canceled_by_update cuando es reemplazada por una edición, canceled_by_position cuando la posición a la que estaba vinculada desapareció, canceled_by_error cuando falló la ejecución — consulta errorCode.

Permitido: "active" "canceled" "canceled_by_update" "canceled_by_error" "canceled_by_position" "executed"

Ejemplo: active

typestring · enumobligatorio

Tipo de orden. liquidation marca una orden que el propio motor generó.

Permitido: "market" "limit" "stop" "trailing_stop" "take" "stop_limit" "stop_market" "liquidation"

Ejemplo: market

directionstring · enumobligatorio

Dirección de la orden.

Permitido: "long" "short"

Ejemplo: long

triggerPricestring · int32obligatorio

Precio al que se dispara la orden, fp9 en bruto. 0 cuando la orden no lleva disparador.

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

Ejemplo: 1000000000

requestedTriggerPricestring · int32 · nullableobligatorio

Precio de activación tal como se solicitó, antes de que el motor lo desplazara hasta la distancia mínima de stop, fp9 en bruto. Nulo cuando el precio solicitado se mantuvo tal cual.

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

Ejemplo: 1000000000

stopPricestring · int32obligatorio

Precio de activación de una orden stop_market / stop_limit, fp9 en bruto; 0 para cualquier otro tipo.

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

Ejemplo: 1000000000

limitPricestring · int32obligatorio

Precio al que se coloca la orden una vez activada, fp9 en bruto: el precio stop-limit, recurriendo al precio de activación como alternativa.

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

Ejemplo: 1000000000

stopTriggerPricestring · int32obligatorio

Stop-loss asociado a la orden, fp9 en bruto. 0 cuando no hay ninguno asociado.

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

Ejemplo: 1000000000

takeTriggerPricestring · int32obligatorio

Take-profit asociado a la orden, fp9 en bruto. 0 cuando no hay ninguno asociado.

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

Ejemplo: 1000000000

trailingStopActivationPricestring · int32obligatorio

Precio al que un stop móvil comienza a hacer seguimiento, fp9 sin procesar. 0 cuando hace seguimiento desde la creación.

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

Ejemplo: 1000000000

trailingStopOffsetstring · int32obligatorio

Distancia de seguimiento como un importe absoluto de cotización, fp9 sin procesar. 0 cuando la distancia se establece como porcentaje.

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

Ejemplo: 1000000000

trailingStopOffsetPercentstring · int32obligatorio

Distancia de seguimiento como una fracción del precio, fp9 sin procesar. 0 cuando la distancia es absoluta.

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

Ejemplo: 1000000000

leveragestring · int32 · nullableobligatorio

Apalancamiento de la orden, fp9 en bruto. Nulo en órdenes de cierre, que heredan el apalancamiento de la posición.

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

Ejemplo: 1000000000

indexstringobligatorio

Identificador de la orden. Se conserva por compatibilidad con versiones anteriores, siempre igual a id.

Ejemplo: string

positionIdstring · nullableobligatorio

Posición a la que está asociada una orden de cierre. Nulo para órdenes que abren o aumentan una posición.

Ejemplo: string

parentOrderIdstring · nullableobligatorio

Orden de la que se generó esta: un stop o un take creado a partir de stopTriggerPrice / takeTriggerPrice, o la orden limit en la que se convirtió un stop_limit. Nulo cuando la orden se envió directamente.

Ejemplo: string

expirationstring · date-time · nullableobligatorio

Siempre nulo. Se mantiene por compatibilidad con versiones anteriores: las órdenes no expiran por sí solas.

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

amountstring · int32obligatorio

Tamaño de la orden, fp9 en bruto, en la unidad que usa su clase: en una orden de incremento, un importe de cotización — la reserva mientras espera, y lo que realmente gastó una vez ejecutada; en una orden de cierre (stop, take, trailing_stop), el tamaño del activo base que cierra, tal como se solicitó al crearla.

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

Ejemplo: 1000000000

indexPricestring · int32 · nullableobligatorio

Precio índice al que se ejecutó la orden, fp9 en bruto. Nulo mientras la orden no se haya ejecutado.

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

Ejemplo: 1000000000

settlementOraclePricestring · int32obligatorio

Siempre 1000000000 (1.0). Se mantiene por compatibilidad con versiones anteriores.

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

Ejemplo: 1000000000

createdAtstring · date-timeobligatorio

Cuándo se aceptó la orden.

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

errorstring · nullableobligatorio

Siempre null. Se mantiene por compatibilidad hacia atrás — utilice errorCode.

Ejemplo: string

realizedPnlstring · int32 · nullableobligatorio

Pnl realizado por esta orden, fp9 en bruto. Se establece solo en una orden de cierre ejecutada; null mientras está pendiente y en órdenes que abren o aumentan una posición.

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

Ejemplo: 1000000000

rawRealizedPnlstring · int32 · nullableobligatorio

Pnl realizado antes del ajuste de 60 segundos, fp9 en bruto. Difiere de realizedPnl solo cuando se activó el ajuste.

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

Ejemplo: 1000000000

profitAdjustmentAppliedbooleanobligatorio

Si el ajuste de 60 segundos limitó la ganancia de esta orden — dentro de un minuto de una apertura o un aumento, el pnl de la posición no puede crecer por encima de lo que era en ese momento.

Ejemplo: true

executedAfterPausebooleanobligatorio

Indica si la orden se ejecutó después de una pausa del mercado. No lo establece el motor actual — siempre false.

Ejemplo: true

sizeModestring · enumobligatorio

Cómo se expresó el tamaño al crearse: quote dimensiona la orden por amount, base la dimensiona por baseSize.

Permitido: "quote" "base"

Ejemplo: quote

baseSizestring · int32 · nullableobligatorio

Tamaño de la orden en unidades del activo base, fp9 en bruto. Nulo para órdenes dimensionadas por quote.

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

Ejemplo: 1000000000

reservedAmountstring · int32 · nullableobligatorio

Importe de quote reservado cuando se creó la orden con sizeMode=base, fp9 en bruto. Se mantiene en la reserva original después de la ejecución, mientras que amount se reescribe a lo que se gastó. Nulo para órdenes dimensionadas por quote, donde amount es la reserva.

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

Ejemplo: 1000000000

errorCodestring · nullableobligatorio

Por qué falló la ejecución, establecido junto con el estado canceled_by_error — por ejemplo insufficient_reserve_at_execution, order_below_min_notional, order_exceeds_market_depth o slippage_tolerance. Nulo en caso contrario.

Ejemplo: string

reasonstring · enum · nullableobligatorio

Por qué la plataforma canceló la orden por sí misma, por ejemplo force_close o weekly_session_risk_close. Nulo para cancelaciones impulsadas por el trader.

Permitido: "force_close" "stop_accounts_fail" "stop_accounts_freeze" "stop_accounts_promote" "stop_accounts_manual" "weekly_session_risk_close" null

Ejemplo: force_close

Ver ejemplo

{
  "id": "00000000-0000-4000-8000-000000000000",
  "txId": "string",
  "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",
  "index": "string",
  "positionId": "string",
  "parentOrderId": "string",
  "expiration": "2026-05-01T12:30:00.000Z",
  "amount": "1000000000",
  "indexPrice": "1000000000",
  "settlementOraclePrice": "1000000000",
  "createdAt": "2026-05-01T12:30:00.000Z",
  "error": "string",
  "realizedPnl": "1000000000",
  "rawRealizedPnl": "1000000000",
  "profitAdjustmentApplied": true,
  "executedAfterPause": true,
  "sizeMode": "quote",
  "baseSize": "1000000000",
  "reservedAmount": "1000000000",
  "errorCode": "string",
  "reason": "force_close"
}

[
  {
    "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"
    ],
    "order": {
      "id": "00000000-0000-4000-8000-000000000000",
      "txId": "string",
      "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",
      "index": "string",
      "positionId": "string",
      "parentOrderId": "string",
      "expiration": "2026-05-01T12:30:00.000Z",
      "amount": "1000000000",
      "indexPrice": "1000000000",
      "settlementOraclePrice": "1000000000",
      "createdAt": "2026-05-01T12:30:00.000Z",
      "error": "string",
      "realizedPnl": "1000000000",
      "rawRealizedPnl": "1000000000",
      "profitAdjustmentApplied": true,
      "executedAfterPause": true,
      "sizeMode": "quote",
      "baseSize": "1000000000",
      "reservedAmount": "1000000000",
      "errorCode": "string",
      "reason": "force_close"
    }
  }
]