# Get position events for chart indicators grouped by candles

`GET /positions/{accountId}/{asset}/chart-events/buckets`

Position events of the account on one market grouped by candles of the requested resolution, oldest candle first.

- Candles are aligned the same way the datafeed does it: a candle starts at a multiple of the resolution since the unix epoch, a daily one at
  UTC midnight.
- A candle is included when its start lies inside `[from, to]`; the distance between `from` and `to` may not exceed 350 candles.
- Candles without events are omitted.
- Each candle has a `buy` side (long increases, short decreases, closes and liquidations) and a `sell` side (short increases, long decreases,
  closes and liquidations). A side holds up to 5 latest events, newest first, and the number of all its events in the candle.
- Only increases, closes, force closes and liquidations are counted; funding and margin changes are not chart events.
- Limited to the phase the account is currently in.

## Authorization

bearer: http · bearer (required). Personal API key, prefixed with `usk_`.

## Parameters

- path: accountId (string · uuid; required). Trader account identifier. Must belong to the caller.

Type: 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; required). Base asset ticker of the market, as returned by `GET /v2/markets`.

Type: string

Example: "BTC"

minLength: 1

- query: resolution (string · enum; required). Candle resolution to group events by, same values as the datafeed `/history` endpoint.

Type: string · enum

Example: "60"

Allowed values: ["1","5","15","30","60","240","1D"]

- query: from (integer; required). Start of the first candle, unix timestamp in seconds (inclusive).

Type: integer

Example: 1767225600

minimum: 0

maximum: 9007199254740991

- query: to (integer; required). Start of the last candle, unix timestamp in seconds (inclusive).

Type: integer

Example: 1768482000

minimum: 0

maximum: 9007199254740991

## Example · 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'
```

## Example · 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());
```

## Example · 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)
```

## Response 401

**401**  — Unauthorized

## Response 403

**403**  — The account belongs to another user (`account_access_denied`), or the request is authenticated with an API key while `api_trading` is disabled on the account (`api_trading_not_enabled`).

## Response 404

**404**  — No account with this identifier, or no market for this ticker.

## Response 429

**429**  — Rate limit of the API key exceeded (`api_key_rate_limit_exceeded`). `Retry-After` says when to come back; the body carries the bucket (`read` / `write`), the window that tripped, its limit and `retryAt`.

## Response default · ChartEventBucketResponse

**default** application/json — Response

Type: object[]

[]Schema: ChartEventBucketResponse

[]Type: object

[]Required fields: time, buy, sell

[]Required field types: time (number; required), buy (object; required), sell (object; required)

- []time (number; required)

[]time example: 1767225600

[]time.Type: number

[]time.Start of the candle, unix timestamp in seconds.

- []buy (object; required)

[]buy example: {
  "totalCount": 12,
  "events": [
    {
      "asset": "BTC",
      "direction": "long",
      "eventName": "open",
      "executedAt": 1767225599,
      "price": "1000000000",
      "size": "1000000000"
    }
  ]
}

[]buy.Type: object

[]buy.Required fields: totalCount, events

[]buy.Required field types: totalCount (number; required), events (object[]; required)

[]buy.Buy side: increases of long positions and decreases, closes and liquidations of short positions.

- []buy.totalCount (number; required)

[]buy.totalCount example: 12

[]buy.totalCount.Type: number

[]buy.totalCount.Number of all events of this side in the candle.

- []buy.events (object[]; required)

[]buy.events example: [
  {
    "asset": "BTC",
    "direction": "long",
    "eventName": "open",
    "executedAt": 1767225599,
    "price": "1000000000",
    "size": "1000000000"
  }
]

[]buy.events.Type: object[]

[]buy.events.Up to 5 latest events of this side in the candle, newest first.

[]buy.events.[]Type: object

[]buy.events.[]Required fields: asset, direction, eventName, executedAt, price, size

[]buy.events.[]Required field types: asset (string; required), direction (string · enum; required), eventName (string · enum; required), executedAt (number; required), price (string · int32; required), size (string · int32; required)

- []buy.events.[]asset (string; required)

[]buy.events.[]asset example: BTC

[]buy.events.[]asset.Type: string

[]buy.events.[]asset.Base asset ticker of the market the event happened on.

- []buy.events.[]direction (string · enum; required)

[]buy.events.[]direction example: long

[]buy.events.[]direction.Type: string · enum

[]buy.events.[]direction.Direction of the position the event belongs to.

[]buy.events.[]direction.Allowed values: ["long","short"]

- []buy.events.[]eventName (string · enum; required)

[]buy.events.[]eventName example: open

[]buy.events.[]eventName.Type: string · enum

[]buy.events.[]eventName.What the marker stands for: `open` for the first increase of a position, `increase` for later ones, `decrease` for a partial close, `close` for a full one and `liquidation` for a liquidation.

[]buy.events.[]eventName.Allowed values: ["open","increase","decrease","close","liquidation"]

- []buy.events.[]executedAt (number; required)

[]buy.events.[]executedAt example: 1767225599

[]buy.events.[]executedAt.Type: number

[]buy.events.[]executedAt.When the event happened, unix timestamp in seconds.

- []buy.events.[]price (string · int32; required)

[]buy.events.[]price example: 1000000000

[]buy.events.[]price.Type: string · int32

[]buy.events.[]price.Price the event executed at, fp9 raw — exchanged quote over exchanged base.

[]buy.events.[]price.format: int32

[]buy.events.[]price.pattern: ^(?:-?[1-9][0-9]*|0)$

- []buy.events.[]size (string · int32; required)

[]buy.events.[]size example: 1000000000

[]buy.events.[]size.Type: string · int32

[]buy.events.[]size.Absolute size the event moved, in base asset units, fp9 raw.

[]buy.events.[]size.format: int32

[]buy.events.[]size.pattern: ^(?:-?[1-9][0-9]*|0)$

- []sell (object; required)

[]sell example: {
  "totalCount": 12,
  "events": [
    {
      "asset": "BTC",
      "direction": "long",
      "eventName": "open",
      "executedAt": 1767225599,
      "price": "1000000000",
      "size": "1000000000"
    }
  ]
}

[]sell.Type: object

[]sell.Required fields: totalCount, events

[]sell.Required field types: totalCount (number; required), events (object[]; required)

[]sell.Sell side: increases of short positions and decreases, closes and liquidations of long positions.

- []sell.totalCount (number; required)

[]sell.totalCount example: 12

[]sell.totalCount.Type: number

[]sell.totalCount.Number of all events of this side in the candle.

- []sell.events (object[]; required)

[]sell.events example: [
  {
    "asset": "BTC",
    "direction": "long",
    "eventName": "open",
    "executedAt": 1767225599,
    "price": "1000000000",
    "size": "1000000000"
  }
]

[]sell.events.Type: object[]

[]sell.events.Up to 5 latest events of this side in the candle, newest first.

[]sell.events.[]Type: object

[]sell.events.[]Required fields: asset, direction, eventName, executedAt, price, size

[]sell.events.[]Required field types: asset (string; required), direction (string · enum; required), eventName (string · enum; required), executedAt (number; required), price (string · int32; required), size (string · int32; required)

- []sell.events.[]asset (string; required)

[]sell.events.[]asset example: BTC

[]sell.events.[]asset.Type: string

[]sell.events.[]asset.Base asset ticker of the market the event happened on.

- []sell.events.[]direction (string · enum; required)

[]sell.events.[]direction example: long

[]sell.events.[]direction.Type: string · enum

[]sell.events.[]direction.Direction of the position the event belongs to.

[]sell.events.[]direction.Allowed values: ["long","short"]

- []sell.events.[]eventName (string · enum; required)

[]sell.events.[]eventName example: open

[]sell.events.[]eventName.Type: string · enum

[]sell.events.[]eventName.What the marker stands for: `open` for the first increase of a position, `increase` for later ones, `decrease` for a partial close, `close` for a full one and `liquidation` for a liquidation.

[]sell.events.[]eventName.Allowed values: ["open","increase","decrease","close","liquidation"]

- []sell.events.[]executedAt (number; required)

[]sell.events.[]executedAt example: 1767225599

[]sell.events.[]executedAt.Type: number

[]sell.events.[]executedAt.When the event happened, unix timestamp in seconds.

- []sell.events.[]price (string · int32; required)

[]sell.events.[]price example: 1000000000

[]sell.events.[]price.Type: string · int32

[]sell.events.[]price.Price the event executed at, fp9 raw — exchanged quote over exchanged base.

[]sell.events.[]price.format: int32

[]sell.events.[]price.pattern: ^(?:-?[1-9][0-9]*|0)$

- []sell.events.[]size (string · int32; required)

[]sell.events.[]size example: 1000000000

[]sell.events.[]size.Type: string · int32

[]sell.events.[]size.Absolute size the event moved, in base asset units, fp9 raw.

[]sell.events.[]size.format: int32

[]sell.events.[]size.pattern: ^(?:-?[1-9][0-9]*|0)$

Example



```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"
        }
      ]
    }
  }
]
```