Get bounded public USD candles for a token: each fill at the CC/USD rate of its time, with rate changes as price events.
GET /api/v1/tokens/{slug}/candles/usd. Get bounded public USD candles for a token: each fill at the CC/USD rate of its time, with rate changes as price events.
Request
GET /api/v1/tokens/{slug}/candles/usd
The schema permits anonymous access. Supported credentials: a customer API key with read scope in X-API-Key. Deployment policy can require a key for market-data routes.
Parameters
| Name | In | Type | Required | Constraints | Description |
|---|---|---|---|---|---|
slug | path | string | Yes | min length: 1; max length: 64; pattern: ^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$ | — |
from | query | string | No | format: date-time; pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ | — |
interval | query | string | No | default: 1h; allowed: "1m", "5m", "1h", "4h", "1d" | — |
to | query | string | No | format: date-time; pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ | — |
X-Request-Id | header | string | No | min length: 8; max length: 128; pattern: ^[A-Za-z0-9._:-]+$ | Optional client correlation identifier. The server always generates a separate authoritative request ID and retains a valid supplied value only as secondary audit correlation metadata. |
cURL
Set SLUG to the path and required query values before running this example. URL-encode path values as needed.
curl --fail-with-body --silent --show-error \
--request GET \
--url "https://launch-api.supanova.app/api/v1/tokens/${SLUG}/candles/usd" \
--header "X-API-Key: $SUPANOVA_API_KEY"Responses
200
Public USD candle series.
| Header | Type | Description |
|---|---|---|
X-Request-Id | string | Server-generated request correlation identifier to retain for support and reconciliation. |
Content type: application/json
Type: object.
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
candles | array of object · Schema 1 | Yes | max items: 500 | — |
meta | object · Schema 2 | Yes | — | — |
Additional fields are not allowed.
400
Invalid token slug or candle window. Also: VALIDATION_FAILED, AMBIGUOUS_CREDENTIALS.
| Header | Type | Description |
|---|---|---|
X-Request-Id | string | Server-generated request correlation identifier to retain for support and reconciliation. |
Content type: application/json
Standard envelope: error.code, error.message, optional error.details, and requestId. See error handling and the full code registry.
401
Credentials are missing, malformed, expired or revoked. Codes: API_KEY_INVALID, API_KEY_REVOKED.
| Header | Type | Description |
|---|---|---|
X-Request-Id | string | Server-generated request correlation identifier to retain for support and reconciliation. |
Content type: application/json
Standard envelope: error.code, error.message, optional error.details, and requestId. See error handling and the full code registry.
403
The credential may not call this route. Codes: API_KEY_IP_NOT_ALLOWED, PRODUCT_ACCOUNT_RESTRICTED.
| Header | Type | Description |
|---|---|---|
X-Request-Id | string | Server-generated request correlation identifier to retain for support and reconciliation. |
Content type: application/json
Standard envelope: error.code, error.message, optional error.details, and requestId. See error handling and the full code registry.
404
Token not found.
| Header | Type | Description |
|---|---|---|
X-Request-Id | string | Server-generated request correlation identifier to retain for support and reconciliation. |
Content type: application/json
Standard envelope: error.code, error.message, optional error.details, and requestId. See error handling and the full code registry.
429
The caller exceeded an IP or principal request budget.
| Header | Type | Description |
|---|---|---|
Retry-After | integer | Whole seconds to wait before retrying a rate-limited request. |
X-Request-Id | string | Server-generated request correlation identifier to retain for support and reconciliation. |
Content type: application/json
Standard envelope: error.code, error.message, optional error.details, and requestId. See error handling and the full code registry.
503
The stage projection or the CC/USD rate history is not configured.
| Header | Type | Description |
|---|---|---|
X-Request-Id | string | Server-generated request correlation identifier to retain for support and reconciliation. |
Content type: application/json
Standard envelope: error.code, error.message, optional error.details, and requestId. See error handling and the full code registry.
default
Machine-readable API error. The HTTP status identifies the error class.
| Header | Type | Description |
|---|---|---|
X-Request-Id | string | Server-generated request correlation identifier to retain for support and reconciliation. |
Content type: application/json
Standard envelope: error.code, error.message, optional error.details, and requestId. See error handling and the full code registry.
Nested schemas
Field links above lead to the complete nested object, array, and variant definitions below. Required fields are scoped to their containing object.
Schema 1
Response 200.candles
Type: array of object.
max items: 500
Array items: object · Schema 3.
Schema 2
Response 200.meta
Type: object.
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
provenance | object · Schema 4 | Yes | — | — |
schemaVersion | "1" | Yes | — | — |
denomination | "USD" | Yes | — | — |
fx | object · Schema 5 | Yes | — | — |
marketCapBasis | "fully_diluted" | Yes | — | Market cap is the price times the fixed total supply (supply.totalSupply). |
method | "fill-and-rate-event-union" | Yes | — | Fills and rate changes walked in time order; each fill converted at its own rate before OHLC aggregation; a rate change alone emits a candle with zero volume. |
seriesStart | one or more variants · Schema 6 | Yes | — | First bucket covered: the requested window clipped to fx.coverageStart. |
supply | one or more variants · Schema 7 | Yes | — | Market cap at a candle: its USD price times this fixed total supply. |
Additional fields are not allowed.
Schema 3
Response 200.candles item
Type: object.
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
close | string | Yes | pattern: ^(?:0|[1-9]\d{0,27})(?:\.\d{1,60})?$ | — |
high | string | Yes | pattern: ^(?:0|[1-9]\d{0,27})(?:\.\d{1,60})?$ | — |
low | string | Yes | pattern: ^(?:0|[1-9]\d{0,27})(?:\.\d{1,60})?$ | — |
open | string | Yes | pattern: ^(?:0|[1-9]\d{0,27})(?:\.\d{1,60})?$ | — |
time | string | Yes | format: date-time; pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ | — |
volume | string | Yes | pattern: ^(?:0|[1-9]\d{0,27})(?:\.\d{1,10})?$ | CC volume of the fills in the candle. |
volumeUsd | string | Yes | pattern: ^(?:0|[1-9]\d{0,27})(?:\.\d{1,10})?$ | USD volume: each fill priced at the rate in effect when it traded. |
Additional fields are not allowed.
Schema 4
Response 200.meta.provenance
Type: object.
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
asOf | string | Yes | format: date-time; pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ | — |
dataMode | string | Yes | allowed: "projected", "simulated" | — |
disclaimer | string | Yes | min length: 1 | — |
label | string | Yes | min length: 1 | — |
networkId | string | Yes | pattern: ^canton:[-_a-zA-Z0-9]{1,32}$ | — |
visibility | string | Yes | allowed: "aggregated-from-entitled-views", "public-by-design" | — |
Additional fields are not allowed.
Schema 5
Response 200.meta.fx
Type: object.
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
coverageStart | one or more variants · Schema 8 | Yes | — | When the oldest observed round opened. No USD value exists before it; nothing is back-filled from a later quote. Null: no round observed yet. |
rates | array of object · Schema 9 | Yes | max items: 5000 | The rate in effect at the series start, then every rate change inside it. |
source | "splice-open-mining-round" | Yes | — | Splice super validators amuletPrice; a validator reference, not a traded price. |
sourceDetail | string | Yes | min length: 1; max length: 100 | — |
Additional fields are not allowed.
Schema 6
Response 200.meta.seriesStart
Type: one or more variants.
First bucket covered: the requested window clipped to fx.coverageStart.
At least one of these variants must match:
- Variant 1: string. format:
date-time; pattern:^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ - Variant 2: null.
Schema 7
Response 200.meta.supply
Type: one or more variants.
Market cap at a candle: its USD price times this fixed total supply.
At least one of these variants must match:
- Variant 1: object · Schema 10.
- Variant 2: null.
Schema 8
Response 200.meta.fx.coverageStart
Type: one or more variants.
When the oldest observed round opened. No USD value exists before it; nothing is back-filled from a later quote. Null: no round observed yet.
At least one of these variants must match:
- Variant 1: string. format:
date-time; pattern:^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ - Variant 2: null.
Schema 9
Response 200.meta.fx.rates
Type: array of object.
max items: 5000
The rate in effect at the series start, then every rate change inside it.
Array items: object · Schema 11.
Schema 10
Response 200.meta.supply variant 1
Type: object.
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
basis | "fixed-total-supply" | Yes | — | — |
totalSupply | string | Yes | pattern: ^(?:0|[1-9]\d{0,27})(?:\.\d{1,10})?$ | — |
Additional fields are not allowed.
Schema 11
Response 200.meta.fx.rates item
Type: object.
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
effectiveAt | string | Yes | format: date-time; pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ | The round's opensAt: the rate applies from here until the next round opens. |
rateUsdPerCc | string | Yes | pattern: ^(?:0|[1-9]\d{0,27})(?:\.\d{1,10})?$ | USD per CC (amuletPrice). |
roundNumber | integer | Yes | minimum: 0; maximum: 9007199254740991 | — |
Additional fields are not allowed.
Source contract
This page is generated from the checked-in customer OpenAPI snapshot. Download JSON, download YAML, or compare the live API reference. Snapshot provenance records the retrieval date and checksum.