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

Identificador de posición.

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

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

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

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

Ejemplo: 1000000000

notionalstring · fp9obligatorio

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

marginstring · fp9obligatorio

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

feestring · fp9obligatorio

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

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

Ejemplo: 1000000000

feeRatestring · fp9obligatorio

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

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

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

Ejemplo: 1000000000

exchangedBasestring · fp9obligatorio

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

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

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

Ejemplo: 1000000000

rawPnlInEventstring · fp9obligatorio

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

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.

Ejemplo: string

feeInEventstring · fp9obligatorio

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

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

Ejemplo: 1000000000

fundingInEventstring · fp9obligatorio

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

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

Ejemplo: 1000000000

roestring · fp9obligatorio

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

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

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.

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

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

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 · fp9 · 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 · fp9obligatorio

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

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

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

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

Ejemplo: 1000000000

takeTriggerPricestring · fp9obligatorio

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

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

Ejemplo: 1000000000

trailingStopActivationPricestring · fp9obligatorio

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

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

Distancia de seguimiento como multiplicador de precio, fp9 en bruto: uno menos el porcentaje, por lo que 5% es 950000000. 0 cuando la distancia es absoluta.

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

Ejemplo: 1000000000

leveragestring · fp9 · 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

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

amountstring · fp9obligatorio

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

recentVolumestring · fp9 · nullableobligatorio

Volumen de las aperturas y aumentos previos en la misma cuenta, mercado y dirección que todavía se contabilizaba en el impacto en el precio de esta orden cuando se ejecutó, USD fp9 en bruto. La ventana de recuperación es configurable, 60 segundos por defecto. Fijado en la ejecución. Nulo para órdenes que no se han ejecutado, órdenes de cierre y mercados sin impacto dinámico en el precio.

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

Ejemplo: 1000000000

priceImpactstring · fp9 · nullableobligatorio

Impacto en el precio aplicado a esta apertura o aumento, excluyendo el spread estático, como una fracción fp9 en bruto (10000000 = 1%). Incluye el volumen reciente en recentVolume. Fijado en la ejecución. Nulo para órdenes que no se han ejecutado, órdenes de cierre y mercados sin impacto dinámico en el precio.

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

Ejemplo: 1000000000

createdAtstring · date-timeobligatorio

Cuándo se aceptó la orden.

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

realizedPnlstring · fp9 · 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 · fp9 · 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

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 · fp9 · 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 · fp9 · 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"

Ejemplo: force_close

vpiobject · nullableobligatorio

Parámetros VPI del mercado en el momento en que se ejecutó la orden. Nulo mientras la orden no se haya ejecutado.

Objeto · 5 campos

spreadstring · fp9obligatorio

Spread cobrado sobre el precio del índice, fracción fp9 en bruto.

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

Ejemplo: 1000000000

marketDepthLongstringobligatorio

Profundidad en el lado largo, en USD enteros — no fp9.

pattern: ^-?[0-9]+(\.[0-9]+)?$

Ejemplo: 45604631.000000000

marketDepthShortstringobligatorio

Profundidad en el lado corto, en USD enteros — no fp9.

pattern: ^-?[0-9]+(\.[0-9]+)?$

Ejemplo: 38744214.000000000

coefficientLongstring · fp9obligatorio

Coeficiente de impacto en el precio aplicado a las órdenes largas, fp9 en bruto.

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

Ejemplo: 1000000000

coefficientShortstring · fp9obligatorio

Coeficiente de impacto en el precio aplicado a las órdenes cortas, fp9 en bruto.

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

Ejemplo: 1000000000

Ver ejemplo

{
  "spread": "1000000000",
  "marketDepthLong": "45604631.000000000",
  "marketDepthShort": "38744214.000000000",
  "coefficientLong": "1000000000",
  "coefficientShort": "1000000000"
}

Ver ejemplo

{
  "id": "00000000-0000-4000-8000-000000000000",
  "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",
  "positionId": "string",
  "parentOrderId": "string",
  "amount": "1000000000",
  "indexPrice": "1000000000",
  "recentVolume": "1000000000",
  "priceImpact": "1000000000",
  "createdAt": "2026-05-01T12:30:00.000Z",
  "realizedPnl": "1000000000",
  "rawRealizedPnl": "1000000000",
  "profitAdjustmentApplied": true,
  "sizeMode": "quote",
  "baseSize": "1000000000",
  "reservedAmount": "1000000000",
  "errorCode": "string",
  "reason": "force_close",
  "vpi": {
    "spread": "1000000000",
    "marketDepthLong": "45604631.000000000",
    "marketDepthShort": "38744214.000000000",
    "coefficientLong": "1000000000",
    "coefficientShort": "1000000000"
  }
}

[
  {
    "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",
    "order": {
      "id": "00000000-0000-4000-8000-000000000000",
      "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",
      "positionId": "string",
      "parentOrderId": "string",
      "amount": "1000000000",
      "indexPrice": "1000000000",
      "recentVolume": "1000000000",
      "priceImpact": "1000000000",
      "createdAt": "2026-05-01T12:30:00.000Z",
      "realizedPnl": "1000000000",
      "rawRealizedPnl": "1000000000",
      "profitAdjustmentApplied": true,
      "sizeMode": "quote",
      "baseSize": "1000000000",
      "reservedAmount": "1000000000",
      "errorCode": "string",
      "reason": "force_close",
      "vpi": {
        "spread": "1000000000",
        "marketDepthLong": "45604631.000000000",
        "marketDepthShort": "38744214.000000000",
        "coefficientLong": "1000000000",
        "coefficientShort": "1000000000"
      }
    }
  }
]