Get position events for chart indicators grouped by candles

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

Get position events for chart indicators grouped by candlesTrading

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.

Base URL https://api.upscale.trade

Authorization

bearerhttp · bearerrequired

Personal API key, prefixed with usk_.

Parameters

Path

accountIdstring · uuidrequired

Trader account identifier. Must belong to the caller.

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})$

Example: 00000000-0000-4000-8000-000000000000

assetstringrequired

Base asset ticker of the market, as returned by GET /v2/markets.

minLength: 1

Example: BTC

Query

resolutionstring · enumrequired

Candle resolution to group events by, same values as the datafeed /history endpoint.

Allowed: "1" "5" "15" "30" "60" "240" "1D"

Example: 60

fromintegerrequired

Start of the first candle, unix timestamp in seconds (inclusive).

minimum: 0
maximum: 9007199254740991

Example: 1767225600

tointegerrequired

Start of the last candle, unix timestamp in seconds (inclusive).

minimum: 0
maximum: 9007199254740991

Example: 1768482000

Examples

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

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());

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)

Responses

401

Unauthorized

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).

404

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

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.

defaultResponseapplication/json

Array of ChartEventBucketResponse

timenumberrequired

Start of the candle, unix timestamp in seconds.

Example: 1767225600

buyobjectrequired

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

Object · 2 fields

totalCountnumberrequired

Number of all events of this side in the candle.

Example: 12

eventsobject[]required

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

Array items · object

assetstringrequired

Base asset ticker of the market the event happened on.

Example: BTC

directionstring · enumrequired

Direction of the position the event belongs to.

Allowed: "long" "short"

Example: long

eventNamestring · enumrequired

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.

Allowed: "open" "increase" "decrease" "close" "liquidation"

Example: open

executedAtnumberrequired

When the event happened, unix timestamp in seconds.

Example: 1767225599

pricestring · int32required

Price the event executed at, fp9 raw — exchanged quote over exchanged base.

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

Example: 1000000000

sizestring · int32required

Absolute size the event moved, in base asset units, fp9 raw.

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

Example: 1000000000

View example

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

View example

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

sellobjectrequired

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

Object · 2 fields

totalCountnumberrequired

Number of all events of this side in the candle.

Example: 12

eventsobject[]required

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

Array items · object

assetstringrequired

Base asset ticker of the market the event happened on.

Example: BTC

directionstring · enumrequired

Direction of the position the event belongs to.

Allowed: "long" "short"

Example: long

eventNamestring · enumrequired

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.

Allowed: "open" "increase" "decrease" "close" "liquidation"

Example: open

executedAtnumberrequired

When the event happened, unix timestamp in seconds.

Example: 1767225599

pricestring · int32required

Price the event executed at, fp9 raw — exchanged quote over exchanged base.

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

Example: 1000000000

sizestring · int32required

Absolute size the event moved, in base asset units, fp9 raw.

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

Example: 1000000000

View example

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

View example

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

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