# Obtener eventos de posición para indicadores del gráfico agrupados por velas
`GET /positions/{accountId}/{asset}/chart-events/buckets`
Eventos de posición de la cuenta en un mercado agrupados por velas de la resolución solicitada, la vela más antigua primero.
- Las velas se alinean de la misma manera en que lo hace el datafeed: una vela comienza en un múltiplo de la resolución desde la época unix, una diaria a
medianoche UTC.
- Una vela se incluye cuando su inicio se encuentra dentro de `[from, to]`; la distancia entre `from` y `to` no puede exceder 350 velas.
- Las velas sin eventos se omiten.
- Cada vela tiene un lado `buy` (aumentos de largos, disminuciones de cortos, cierres y liquidaciones) y un lado `sell` (aumentos de cortos, disminuciones de largos,
cierres y liquidaciones). Un lado contiene hasta 5 eventos más recientes, primero los más nuevos, y el número de todos sus eventos en la vela.
- Solo se cuentan los aumentos, cierres, cierres forzosos y liquidaciones; los cambios de financiación y margen no son eventos del gráfico.
- Limitado a la fase en la que se encuentra actualmente la cuenta.
## Autorización
bearer: http · bearer (obligatorio). Clave de API personal, con el prefijo `usk_`.
## Parámetros
- path: accountId (string · uuid; obligatorio). Identificador de la cuenta del trader. Debe pertenecer al solicitante.
Tipo: string · uuid
format: uuid
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})$
- path: asset (string; obligatorio). Ticker del activo base del mercado, tal como lo devuelve `GET /v2/markets`.
Tipo: string
Ejemplo: "BTC"
minLength: 1
- query: resolution (string · enum; obligatorio). Resolución de velas para agrupar eventos, mismos valores que el endpoint `/history` del datafeed.
Tipo: string · enum
Ejemplo: "60"
Valores permitidos: ["1","5","15","30","60","240","1D"]
- query: from (integer; obligatorio). Comienzo de la primera vela, marca de tiempo unix en segundos (inclusive).
Tipo: integer
Ejemplo: 1767225600
minimum: 0
maximum: 9007199254740991
- query: to (integer; obligatorio). Comienzo de la última vela, marca de tiempo unix en segundos (inclusive).
Tipo: integer
Ejemplo: 1768482000
minimum: 0
maximum: 9007199254740991
## Ejemplo · cURL
```bash
curl --request GET 'https://api.upscale.trade/positions/{accountId}/{asset}/chart-events/buckets' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer YOUR_API_KEY'
```
## Ejemplo · JavaScript
```javascript
const response = await fetch("https://api.upscale.trade/positions/{accountId}/{asset}/chart-events/buckets", {
method: "GET",
headers: {
"Accept": "application/json",
"Authorization": "Bearer YOUR_API_KEY"
},
});
console.log(response.status, await response.text());
```
## Ejemplo · Python
```python
import requests
response = requests.request(
"GET",
"https://api.upscale.trade/positions/{accountId}/{asset}/chart-events/buckets",
headers={"Accept":"application/json","Authorization":"Bearer YOUR_API_KEY"},
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`).
## Respuesta 404
**404** — No hay ninguna cuenta con este identificador, o no hay ningún mercado para este ticker.
## 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 · ChartEventBucketResponse
**default** application/json — Respuesta
Tipo: object[]
[]Esquema: ChartEventBucketResponse
[]Tipo: object
[]Campos obligatorios: time, buy, sell
[]Tipos de campos obligatorios: time (number; obligatorio), buy (object; obligatorio), sell (object; obligatorio)
- []time (number; obligatorio)
[]time ejemplo: 1767225600
[]time.Tipo: number
[]time.Comienzo de la vela, marca de tiempo unix en segundos.
- []buy (object; obligatorio)
[]buy ejemplo: {
"totalCount": 12,
"events": [
{
"asset": "BTC",
"direction": "long",
"eventName": "open",
"executedAt": 1767225599,
"price": "1000000000",
"size": "1000000000"
}
]
}
[]buy.Tipo: object
[]buy.Campos obligatorios: totalCount, events
[]buy.Tipos de campos obligatorios: totalCount (number; obligatorio), events (object[]; obligatorio)
[]buy.Lado de compra: aumentos de posiciones largas y disminuciones, cierres y liquidaciones de posiciones cortas.
- []buy.totalCount (number; obligatorio)
[]buy.totalCount ejemplo: 12
[]buy.totalCount.Tipo: number
[]buy.totalCount.Número de todos los eventos de este lado en la vela.
- []buy.events (object[]; obligatorio)
[]buy.events ejemplo: [
{
"asset": "BTC",
"direction": "long",
"eventName": "open",
"executedAt": 1767225599,
"price": "1000000000",
"size": "1000000000"
}
]
[]buy.events.Tipo: object[]
[]buy.events.Hasta los 5 eventos más recientes de este lado en la vela, los más recientes primero.
[]buy.events.[]Tipo: object
[]buy.events.[]Campos obligatorios: asset, direction, eventName, executedAt, price, size
[]buy.events.[]Tipos de campos obligatorios: asset (string; obligatorio), direction (string · enum; obligatorio), eventName (string · enum; obligatorio), executedAt (number; obligatorio), price (string · int32; obligatorio), size (string · int32; obligatorio)
- []buy.events.[]asset (string; obligatorio)
[]buy.events.[]asset ejemplo: BTC
[]buy.events.[]asset.Tipo: string
[]buy.events.[]asset.Ticker del activo base del mercado en el que ocurrió el evento.
- []buy.events.[]direction (string · enum; obligatorio)
[]buy.events.[]direction ejemplo: long
[]buy.events.[]direction.Tipo: string · enum
[]buy.events.[]direction.Dirección de la posición a la que pertenece el evento.
[]buy.events.[]direction.Valores permitidos: ["long","short"]
- []buy.events.[]eventName (string · enum; obligatorio)
[]buy.events.[]eventName ejemplo: open
[]buy.events.[]eventName.Tipo: string · enum
[]buy.events.[]eventName.Qué representa el marcador: `open` para el primer aumento de una posición, `increase` para los posteriores, `decrease` para un cierre parcial, `close` para un cierre total y `liquidation` para una liquidación.
[]buy.events.[]eventName.Valores permitidos: ["open","increase","decrease","close","liquidation"]
- []buy.events.[]executedAt (number; obligatorio)
[]buy.events.[]executedAt ejemplo: 1767225599
[]buy.events.[]executedAt.Tipo: number
[]buy.events.[]executedAt.Cuándo ocurrió el evento, marca de tiempo unix en segundos.
- []buy.events.[]price (string · int32; obligatorio)
[]buy.events.[]price ejemplo: 1000000000
[]buy.events.[]price.Tipo: string · int32
[]buy.events.[]price.Precio al que se ejecutó el evento, fp9 en bruto — cotización intercambiada sobre base intercambiada.
[]buy.events.[]price.format: int32
[]buy.events.[]price.pattern: ^(?:-?[1-9][0-9]*|0)$
- []buy.events.[]size (string · int32; obligatorio)
[]buy.events.[]size ejemplo: 1000000000
[]buy.events.[]size.Tipo: string · int32
[]buy.events.[]size.Tamaño absoluto que movió el evento, en unidades del activo base, fp9 en bruto.
[]buy.events.[]size.format: int32
[]buy.events.[]size.pattern: ^(?:-?[1-9][0-9]*|0)$
- []sell (object; obligatorio)
[]sell ejemplo: {
"totalCount": 12,
"events": [
{
"asset": "BTC",
"direction": "long",
"eventName": "open",
"executedAt": 1767225599,
"price": "1000000000",
"size": "1000000000"
}
]
}
[]sell.Tipo: object
[]sell.Campos obligatorios: totalCount, events
[]sell.Tipos de campos obligatorios: totalCount (number; obligatorio), events (object[]; obligatorio)
[]sell.Lado de venta: aumentos de posiciones cortas y disminuciones, cierres y liquidaciones de posiciones largas.
- []sell.totalCount (number; obligatorio)
[]sell.totalCount ejemplo: 12
[]sell.totalCount.Tipo: number
[]sell.totalCount.Número de todos los eventos de este lado en la vela.
- []sell.events (object[]; obligatorio)
[]sell.events ejemplo: [
{
"asset": "BTC",
"direction": "long",
"eventName": "open",
"executedAt": 1767225599,
"price": "1000000000",
"size": "1000000000"
}
]
[]sell.events.Tipo: object[]
[]sell.events.Hasta los 5 eventos más recientes de este lado en la vela, los más recientes primero.
[]sell.events.[]Tipo: object
[]sell.events.[]Campos obligatorios: asset, direction, eventName, executedAt, price, size
[]sell.events.[]Tipos de campos obligatorios: asset (string; obligatorio), direction (string · enum; obligatorio), eventName (string · enum; obligatorio), executedAt (number; obligatorio), price (string · int32; obligatorio), size (string · int32; obligatorio)
- []sell.events.[]asset (string; obligatorio)
[]sell.events.[]asset ejemplo: BTC
[]sell.events.[]asset.Tipo: string
[]sell.events.[]asset.Ticker del activo base del mercado en el que ocurrió el evento.
- []sell.events.[]direction (string · enum; obligatorio)
[]sell.events.[]direction ejemplo: long
[]sell.events.[]direction.Tipo: string · enum
[]sell.events.[]direction.Dirección de la posición a la que pertenece el evento.
[]sell.events.[]direction.Valores permitidos: ["long","short"]
- []sell.events.[]eventName (string · enum; obligatorio)
[]sell.events.[]eventName ejemplo: open
[]sell.events.[]eventName.Tipo: string · enum
[]sell.events.[]eventName.Qué representa el marcador: `open` para el primer aumento de una posición, `increase` para los posteriores, `decrease` para un cierre parcial, `close` para un cierre total y `liquidation` para una liquidación.
[]sell.events.[]eventName.Valores permitidos: ["open","increase","decrease","close","liquidation"]
- []sell.events.[]executedAt (number; obligatorio)
[]sell.events.[]executedAt ejemplo: 1767225599
[]sell.events.[]executedAt.Tipo: number
[]sell.events.[]executedAt.Cuándo ocurrió el evento, marca de tiempo unix en segundos.
- []sell.events.[]price (string · int32; obligatorio)
[]sell.events.[]price ejemplo: 1000000000
[]sell.events.[]price.Tipo: string · int32
[]sell.events.[]price.Precio al que se ejecutó el evento, fp9 en bruto — cotización intercambiada sobre base intercambiada.
[]sell.events.[]price.format: int32
[]sell.events.[]price.pattern: ^(?:-?[1-9][0-9]*|0)$
- []sell.events.[]size (string · int32; obligatorio)
[]sell.events.[]size ejemplo: 1000000000
[]sell.events.[]size.Tipo: string · int32
[]sell.events.[]size.Tamaño absoluto que movió el evento, en unidades del activo base, fp9 en bruto.
[]sell.events.[]size.format: int32
[]sell.events.[]size.pattern: ^(?:-?[1-9][0-9]*|0)$
Ejemplo
```json
[
{
"time": 1767225600,
"buy": {
"totalCount": 12,
"events": [
{
"asset": "BTC",
"direction": "long",
"eventName": "open",
"executedAt": 1767225599,
"price": "1000000000",
"size": "1000000000"
}
]
},
"sell": {
"totalCount": 12,
"events": [
{
"asset": "BTC",
"direction": "long",
"eventName": "open",
"executedAt": 1767225599,
"price": "1000000000",
"size": "1000000000"
}
]
}
}
]
```