Value the connected account at every hour or day of a range: wallet CC, trading balance and tokens in CC, and in USD from the first recorded CC/USD round.
GET /api/v1/wallet/valuation/history. Value the connected account at every hour or day of a range: wallet CC, trading balance and tokens in CC, and in USD from the first recorded CC/USD round.
Request
GET /api/v1/wallet/valuation/history
Authentication is required. Supported credentials: a customer API key with read scope in X-API-Key or a signed-in customer session token in Authorization: Bearer …. Send one credential type only; never both.
Parameters
| Name | In | Type | Required | Constraints | Description |
|---|---|---|---|---|---|
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)))$ | Start of the series. Default: to minus 30 days (1h) or 365 days (1d). |
interval | query | string | Yes | allowed: "1h", "1d" | Bucket length: UTC hours or UTC days. |
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)))$ | End of the series. Default and upper bound: now (a later value is clamped). |
X-Service-Act-As | header | string | No | min length: 3; max length: 512 | Service-principal path only (local and devnet stages; refused by configuration on mainnet). With an OAuth client-credentials bearer token from the validator, names the allow-listed Party the client acts as. Missing: 400 SERVICE_ACT_AS_REQUIRED; not allow-listed: 403 SERVICE_PARTY_NOT_ALLOWED. Ignored for customer session tokens. |
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 INTERVAL to the path and required query values before running this example. URL-encode path values as needed.
curl --fail-with-body --silent --show-error \
--get \
--url "https://launch-api.supanova.app/api/v1/wallet/valuation/history" \
--header "X-API-Key: $SUPANOVA_API_KEY" \
--data-urlencode "interval=$INTERVAL"Responses
200
The valuation 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 |
|---|---|---|---|---|
coverage | object · Schema 1 | Yes | — | — |
from | 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)))$ | — |
interval | string | Yes | allowed: "1h", "1d" | — |
partyId | string | Yes | — | The account the series values (as in /wallet/valuation). |
points | array of object · Schema 2 | Yes | max items: 744 | — |
to | 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)))$ | — |
walletConnectionId | string | Yes | format: uuid; pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ | The verified wallet connection the party came from. |
Additional fields are not allowed.
400
Malformed range, from not before to, or more than 744 points. Also: VALIDATION_FAILED, AMBIGUOUS_CREDENTIALS, SERVICE_ACT_AS_REQUIRED.
| 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: AUTHENTICATION_REQUIRED, INVALID_AUTHORIZATION_HEADER, INVALID_ACCESS_TOKEN, SESSION_REVOKED, 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. Owner routes accept only a customer API key: an internal master key answers API_KEY_ROUTE_NOT_ALLOWED. Codes: ACCOUNT_RESTRICTED, ANONYMOUS_ACCOUNT_NOT_ALLOWED, API_KEY_ROUTE_NOT_ALLOWED, SERVICE_PARTY_NOT_ALLOWED, SERVICE_PRINCIPAL_NOT_ALLOWED, SIGNUP_NOT_INVITED, 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
No verified wallet connection exists.
| 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
Not a PQS-backed ledger environment, or HISTORY_BUSY: history reads run one at a time and this one waited 10 s; retry after the Retry-After seconds. Also: AUTHENTICATION_UNAVAILABLE, AUTHORIZATION_UNAVAILABLE.
| 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.coverage
Type: object.
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
ccFrom | 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)))$ | Oldest ledger history the query store keeps; balances before it are not recorded. |
pricedTokens | integer | Yes | minimum: 0; maximum: 9007199254740991 | — |
unpricedTokens | integer | Yes | minimum: 0; maximum: 9007199254740991 | Tokens held in the range with no price at some point; counted as zero there. |
usdFrom | one or more variants · Schema 3 | Yes | — | First recorded CC/USD round; valueUsd and ccUsd are null before it. |
Additional fields are not allowed.
Schema 2
Response 200.points
Type: array of object.
max items: 744
Array items: object · Schema 4.
Schema 3
Response 200.coverage.usdFrom
Type: one or more variants.
First recorded CC/USD round; valueUsd and ccUsd are null before it.
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 4
Response 200.points item
Type: object.
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
degraded | true | No | — | Present only when a running balance came out negative (an archive whose creation the query store no longer has, e.g. after pruning). That component is counted as zero, so the point understates the account. |
ccUsd | one or more variants · Schema 5 | Yes | — | USD per CC at t (the Splice open mining round in effect); null before usdFrom. |
t | 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)))$ | Bucket END (exclusive end of the hour or day). Every value of the point is the latest state of the bucket: the account as it stood at t, after every change before t. The newest bucket, which ends after now, holds the current state. |
tokensCc | string | Yes | pattern: ^(?:0|[1-9]\d{0,27})(?:\.\d{1,10})?$ | Token holdings at the token price at t (last hourly close, carried forward; the current pool price for a token that never traded). |
tradingBalanceCc | string | Yes | pattern: ^(?:0|[1-9]\d{0,27})(?:\.\d{1,10})?$ | Launchpad trading balance. |
valueCc | string | Yes | pattern: ^(?:0|[1-9]\d{0,27})(?:\.\d{1,10})?$ | walletCc + tradingBalanceCc + tokensCc. |
valueUsd | one or more variants · Schema 6 | Yes | — | valueCc x ccUsd; null before usdFrom. |
walletCc | string | Yes | pattern: ^(?:0|[1-9]\d{0,27})(?:\.\d{1,10})?$ | The owner's unlocked Amulets, each net of its holding fee at the round in effect at t. |
Additional fields are not allowed.
Schema 5
Response 200.points item.ccUsd
Type: one or more variants.
USD per CC at t (the Splice open mining round in effect); null before usdFrom.
At least one of these variants must match:
- Variant 1: string. pattern:
^(?:0|[1-9]\d{0,27})(?:\.\d{1,10})?$ - Variant 2: null.
Schema 6
Response 200.points item.valueUsd
Type: one or more variants.
valueCc x ccUsd; null before usdFrom.
At least one of these variants must match:
- Variant 1: string. pattern:
^(?:0|[1-9]\d{0,27})(?:\.\d{1,10})?$ - Variant 2: null.
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.