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

dataobject[]obligatorio

Requested page of positions, newest first.

Elementos del array · object

idxstring · nullableobligatorio

Position identifier.

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

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

Position size in base asset units, fp9 raw.

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

Ejemplo: 1000000000

notionalstring · fp9obligatorio

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

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

Ejemplo: 1000000000

marginstring · fp9obligatorio

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

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

Ejemplo: 1000000000

pnlstring · fp9 · nullableobligatorio

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

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

Ejemplo: 1000000000

fundingstring · fp9 · nullableobligatorio

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

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

Ejemplo: 1000000000

feestring · fp9obligatorio

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

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

Ejemplo: 1000000000

feeRatestring · fp9obligatorio

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

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

Ejemplo: 1000000000

exchangedQuotestring · fp9obligatorio

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

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

Ejemplo: 1000000000

exchangedBasestring · fp9obligatorio

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

Realised pnl of the most recent event, fp9 raw.

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

Ejemplo: 1000000000

rawPnlInEventstring · fp9obligatorio

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

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.

Ejemplo: string

feeInEventstring · fp9obligatorio

Fee charged by the most recent event, fp9 raw.

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

Ejemplo: 1000000000

fundingInEventstring · fp9obligatorio

Funding settled by the most recent event, fp9 raw.

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

Ejemplo: 1000000000

roestring · fp9obligatorio

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

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

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

Ejemplo: string

Ver ejemplo

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

totalCountnumberobligatorio

Total number of positions matching the request, across all pages.

Ejemplo: 0

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