Obtener el historial de todas las posiciones

GET/positions/{accountId}/portfolio/history

Obtener el historial de todas las posicionesTrading

Todas las posiciones de la cuenta en todos los mercados, tanto abiertas como cerradas, las más recientes primero, con el recuento total para la paginación.

Limitado a la fase en la que se encuentra actualmente la cuenta: no se devuelven las posiciones de una fase anterior.

URL base https://api.upscale.trade

Autorización

bearerhttp · bearerobligatorio

Clave de API personal, con el prefijo usk_.

Parámetros

Ruta

accountIdstring · uuidobligatorio

Identificador de la cuenta del trader. Debe pertenecer al solicitante.

Ejemplo: 00000000-0000-4000-8000-000000000000

Consulta

limitintegeropcional

Tamaño de página: cuántos registros devolver.

Predeterminado: 20

minimum: 1
maximum: 100

Ejemplo: 20

offsetintegeropcional

Cuántos registros omitir antes de la página.

Predeterminado: 0

minimum: 0
maximum: 9007199254740991

Ejemplo: 0

Ejemplos

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

const response = await fetch("https://api.upscale.trade/positions/{accountId}/portfolio/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/{accountId}/portfolio/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 hay ninguna cuenta 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 PositionsPaginatedResponse

dataobject[]obligatorio

Página solicitada de posiciones, las más recientes primero.

Elementos del array · object

idxstring · nullableobligatorio

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

Ejemplo: string

txIdstring · nullableobligatorio

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

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

Ver ejemplo

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

totalCountnumberobligatorio

Número total de posiciones que coinciden con la solicitud, en todas las páginas.

Ejemplo: 0

[
  {
    "data": [
      {
        "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"
      }
    ],
    "totalCount": 0
  }
]