Read the lifetime weighted-average cost position per instrument of the account’s verified wallet Party.
GET /api/v1/me/positions. Read the lifetime weighted-average cost position per instrument of the account’s verified wallet Party.
Request
GET /api/v1/me/positions
Authentication is required. Supported credentials: a signed-in customer session token in Authorization: Bearer …. This route does not accept customer API keys.
Parameters
| Name | In | Type | Required | Constraints | Description |
|---|---|---|---|---|---|
instrumentAdmin | query | string | No | min length: 1; max length: 512 | — |
instrumentId | query | string | No | min length: 1; max length: 512 | — |
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
curl --fail-with-body --silent --show-error \
--request GET \
--url "https://launch-api.supanova.app/api/v1/me/positions" \
--header "Authorization: Bearer $SUPANOVA_SESSION_TOKEN"Responses
200
Positions with accounting method, completeness, reconciliation and as-of offset.
| 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 |
|---|---|---|---|---|
items | array of object · Schema 1 | Yes | — | — |
meta | object · Schema 2 | Yes | — | — |
Additional fields are not allowed.
400
instrumentAdmin and instrumentId must come together. 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
A valid product account is required. Also: AUTHENTICATION_REQUIRED, INVALID_AUTHORIZATION_HEADER, INVALID_ACCESS_TOKEN, SESSION_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: ACCOUNT_RESTRICTED, ANONYMOUS_ACCOUNT_NOT_ALLOWED, API_KEY_ROUTE_NOT_ALLOWED, SERVICE_PARTY_NOT_ALLOWED, SERVICE_PRINCIPAL_NOT_ALLOWED, SIGNUP_NOT_INVITED.
| 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
A PQS-backed position read is not configured for this environment. 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.items
Type: array of object.
Array items: object · Schema 3.
Schema 2
Response 200.meta
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)))$ | Ledger time of the newest transaction the read saw. |
asOfOffset | string | Yes | pattern: ^\d{1,19}$ | Ledger offset of the query store watermark the read saw. |
ccUsdQuote | one or more variants · Schema 4 | Yes | — | — |
dataMode | "projected" | Yes | — | — |
disclaimer | string | Yes | min length: 1; max length: 1024 | — |
historyComplete | boolean | Yes | — | The whole ledger history of the Party was read, without a window or row cap. |
method | "weighted-average-cost" | Yes | — | — |
networkId | string | Yes | pattern: ^canton:[-_a-zA-Z0-9]{1,32}$ | — |
partyId | one or more variants · Schema 5 | Yes | — | — |
schemaVersion | "1" | Yes | — | — |
Additional fields are not allowed.
Schema 3
Response 200.items item
Type: object.
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
instrumentId | object · Schema 6 | Yes | — | — |
ticker | one or more variants · Schema 7 | Yes | — | — |
slug | one or more variants · Schema 8 | Yes | — | — |
quantity | object · Schema 9 | Yes | — | — |
reconciliation | object · Schema 10 | Yes | — | — |
accounting | object · Schema 11 | Yes | — | — |
valuation | object · Schema 12 | Yes | — | — |
Additional fields are not allowed.
Schema 4
Response 200.meta.ccUsdQuote
Type: one or more variants.
At least one of these variants must match:
- Variant 1: object · Schema 13.
- Variant 2: null.
Schema 5
Response 200.meta.partyId
Type: one or more variants.
At least one of these variants must match:
- Variant 1: string. min length:
3; max length:512 - Variant 2: null.
Schema 6
Response 200.items item.instrumentId
Type: object.
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
admin | string | Yes | min length: 1; max length: 512 | — |
id | string | Yes | min length: 1; max length: 512 | — |
Additional fields are not allowed.
Schema 7
Response 200.items item.ticker
Type: one or more variants.
At least one of these variants must match:
- Variant 1: string. min length:
1; max length:32 - Variant 2: null.
Schema 8
Response 200.items item.slug
Type: one or more variants.
At least one of these variants must match:
- Variant 1: string. min length:
1; max length:128 - Variant 2: null.
Schema 9
Response 200.items item.quantity
Type: object.
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
held | string | Yes | pattern: ^(?:0|[1-9]\d*)(?:\.\d+)?$ | Current holdings, available plus locked. |
available | string | Yes | pattern: ^(?:0|[1-9]\d*)(?:\.\d+)?$ | — |
locked | string | Yes | pattern: ^(?:0|[1-9]\d*)(?:\.\d+)?$ | — |
Additional fields are not allowed.
Schema 10
Response 200.items item.reconciliation
Type: object.
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
matched | boolean | Yes | — | The replayed history (fills and transfers) reproduces the held quantity. |
replayedQuantity | string | Yes | pattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$ | — |
fillNetQuantity | string | Yes | pattern: ^-?(?:0|[1-9]\d*)(?:\.\d+)?$ | Bought minus sold, lifetime. |
transferInQuantity | string | Yes | pattern: ^(?:0|[1-9]\d*)(?:\.\d+)?$ | — |
transferOutQuantity | string | Yes | pattern: ^(?:0|[1-9]\d*)(?:\.\d+)?$ | — |
Additional fields are not allowed.
Schema 11
Response 200.items item.accounting
Type: object.
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
complete | boolean | Yes | — | True only when the full ledger history was read, it reproduces the held quantity, and every token of the current position has a known cost. |
incompleteReason | one or more variants · Schema 14 | Yes | — | — |
costBasisCc | one or more variants · Schema 15 | Yes | — | Remaining cost of the held tokens, buy fees included; null when unknown. |
buyFeesInBasisCc | one or more variants · Schema 16 | Yes | — | — |
averageEntryCc | one or more variants · Schema 17 | Yes | — | costBasisCc / held; null when unknown or nothing is held. |
positionOpenedAt | one or more variants · Schema 18 | Yes | — | — |
lastMovementAt | one or more variants · Schema 18 | Yes | — | — |
counts | object · Schema 19 | Yes | — | — |
Additional fields are not allowed.
Schema 12
Response 200.items item.valuation
Type: object.
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
priceCc | one or more variants · Schema 20 | Yes | — | Current market price, CC per token. |
currentValueCc | one or more variants · Schema 16 | Yes | — | — |
unrealizedPnlCc | one or more variants · Schema 21 | Yes | — | currentValueCc - costBasisCc, before sale fees and slippage; null without a complete basis or a price. |
unrealizedPnlPercent | one or more variants · Schema 22 | Yes | — | — |
usd | one or more variants · Schema 23 | Yes | — | Every CC figure at the one current rate in meta.ccUsdQuote; no historical FX. |
Additional fields are not allowed.
Schema 13
Response 200.meta.ccUsdQuote variant 1
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)))$ | When this backend fetched the rate. |
rateUsdPerCc | string | Yes | pattern: ^(?:0|[1-9]\d{0,27})(?:\.\d{1,10})?$ | USD per CC. |
roundNumber | integer | Yes | minimum: 0; maximum: 9007199254740991 | — |
source | string | Yes | min length: 1; max length: 100 | — |
stale | boolean | Yes | — | — |
Additional fields are not allowed.
Schema 14
Response 200.items item.accounting.incompleteReason
Type: one or more variants.
At least one of these variants must match:
- Variant 1: string. allowed:
"transfer-in-without-cost","removal-exceeds-history","history-before-query-store","quantity-mismatch" - Variant 2: null.
Schema 15
Response 200.items item.accounting.costBasisCc
Type: one or more variants.
Remaining cost of the held tokens, buy fees included; null when unknown.
At least one of these variants must match:
- Variant 1: string. pattern:
^(?:0|[1-9]\d*)(?:\.\d+)?$ - Variant 2: null.
Schema 16
Response 200.items item.accounting.buyFeesInBasisCc
Type: one or more variants.
At least one of these variants must match:
- Variant 1: string. pattern:
^(?:0|[1-9]\d*)(?:\.\d+)?$ - Variant 2: null.
Schema 17
Response 200.items item.accounting.averageEntryCc
Type: one or more variants.
costBasisCc / held; null when unknown or nothing is held.
At least one of these variants must match:
- Variant 1: string. pattern:
^(?:0|[1-9]\d*)(?:\.\d+)?$ - Variant 2: null.
Schema 18
Response 200.items item.accounting.positionOpenedAt
Type: one or more variants.
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 19
Response 200.items item.accounting.counts
Type: object.
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
buys | integer | Yes | minimum: 0; maximum: 9007199254740991 | — |
sells | integer | Yes | minimum: 0; maximum: 9007199254740991 | — |
transfersIn | integer | Yes | minimum: 0; maximum: 9007199254740991 | — |
transfersOut | integer | Yes | minimum: 0; maximum: 9007199254740991 | — |
Additional fields are not allowed.
Schema 20
Response 200.items item.valuation.priceCc
Type: one or more variants.
Current market price, CC per token.
At least one of these variants must match:
- Variant 1: string. pattern:
^(?:0|[1-9]\d*)(?:\.\d+)?$ - Variant 2: null.
Schema 21
Response 200.items item.valuation.unrealizedPnlCc
Type: one or more variants.
currentValueCc - costBasisCc, before sale fees and slippage; null without a complete basis or a price.
At least one of these variants must match:
- Variant 1: string. pattern:
^-?(?:0|[1-9]\d*)(?:\.\d+)?$ - Variant 2: null.
Schema 22
Response 200.items item.valuation.unrealizedPnlPercent
Type: one or more variants.
At least one of these variants must match:
- Variant 1: string. pattern:
^-?(?:0|[1-9]\d*)(?:\.\d+)?$ - Variant 2: null.
Schema 23
Response 200.items item.valuation.usd
Type: one or more variants.
Every CC figure at the one current rate in meta.ccUsdQuote; no historical FX.
At least one of these variants must match:
- Variant 1: object · Schema 24.
- Variant 2: null.
Schema 24
Response 200.items item.valuation.usd variant 1
Type: object.
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
rateUsdPerCc | string | Yes | pattern: ^(?:0|[1-9]\d*)(?:\.\d+)?$ | — |
priceUsd | one or more variants · Schema 16 | Yes | — | — |
currentValueUsd | one or more variants · Schema 16 | Yes | — | — |
costBasisUsd | one or more variants · Schema 16 | Yes | — | — |
averageEntryUsd | one or more variants · Schema 16 | Yes | — | — |
unrealizedPnlUsd | one or more variants · Schema 22 | Yes | — | — |
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.