Skip to main content
GET
List the caller's invite codes
The response body shown here is a static example, not live data. After you click Send, your live result appears in a separate panel headed 200 OK. The panel under the status-code tabs is a fixed sample from the spec — its field values (fees, prices, sizes, IDs, timestamps) are placeholders. Use Send, or call the endpoint, for current values.
Returns the caller’s earned invite codes with redemption status. One invite code is earned per $1M of lifetime perps trading volume (INVITE_VOLUME_PER_CODE_QUANTUMS); codes are generated automatically and appear here as volume milestones are crossed. Signed, unlike the other affiliate reads. An invite code is a bearer secret that grants perps trading access, and X-API-Key alone proves nothing (API keys are Ed25519 public keys, listable by anyone via GET /v1/apiKeys). The Ed25519 request signature proves possession of the private key, and the key must be registered to address. With no request body the signing message is timestamp + action (action inviteCodes — the path segment verbatim, casing included). The response is returned with Cache-Control: no-store.

Authorizations

X-API-Key
string
header
required

Hex-encoded Ed25519 public key (64 chars). The public key IS the API key — register it via POST /createApiKey. Required on every authenticated request, both read-only and signed.

X-Timestamp
string
header
required

Unix time in nanoseconds as a decimal string (e.g. "1713825891591000000"). Millisecond or second epochs are rejected with 401 Unauthorized. Must be within ±30,000 ms (MaxTimestampDriftMs, the drift window stays configured in milliseconds) of server wall-clock, or the request is rejected with 401 Unauthorized. Required on all mutating / credential-creating endpoints. This same value must appear as the ct field in the ordersign typed canonical payload (single-order endpoints) or in each element's ct field (batch endpoints).

X-Signature
string
header
required

Lowercase hex-encoded Ed25519 signature (128 chars).

Single-order endpoints (placeOrder, cancelOrder, modifyOrder, and other non-batch mutating routes) sign over the ordersign typed canonical payload — a compact, key-sorted JSON object built from parsed request fields using engine-native integer values:

ct must equal the X-Timestamp header value. Keys in brackets are conditional (omitted when empty). op values: 1=place, 2=cancel, 3=modify. See the ordersign package for field definitions and reference signing code.

Other signed routes (e.g. createApiKey, tokens, userPreferences) still use the legacy scheme: signing_message = X-Timestamp + ACTION + canonicalJSON(body), where ACTION is the camelCase final path segment.

Batch endpoints (batchPlaceOrders, batchCancelOrders) do NOT use this header. They authenticate with per-element typed ordersign signatures embedded in the request body (see the global auth description and the per-field signature descriptions on OrderRequest / CancelOrderRequest).

Read endpoints are authenticated by ?address= (and optionally X-API-Key) only — no signature is required. The one exception is GET /v1/affiliate/inviteCodes, which returns bearer secrets and therefore requires the full header triple; with no body its signing message is X-Timestamp + ACTION. canonicalJSON(body) is the JSON body with object keys sorted lexicographically at every level and no whitespace; the server canonicalizes the received body before verifying, so only the bytes signed over must be canonical. Required on all mutating / credential-creating endpoints.

Query Parameters

address
string
required

Ethereum address to list invite codes for (must match signer).

status
enum<string>

Return only codes in this state. Omit for both. The counts in the response stay account-wide either way, so the two states can be paged independently without losing the totals.

Available options:
available,
used
limit
integer
default:100

Page size. Values above the maximum are clamped rather than rejected.

Required range: 1 <= x <= 500
offset
integer
default:0

Number of matching codes to skip.

Required range: x >= 0

Response

The caller's invite codes and earn progress.

address
string
required

Owner's Ethereum address.

lifetimeVolume
integer<int64>
required

Lifetime perps volume in quote quantums (1e9 = $1).

inviteCodesEarned
integer
required

Total invite codes earned (one per volume milestone).

inviteCodesMaterialized
integer
required

Codes that exist and are therefore redeemable. Equals inviteCodesEarned except while a large batch of newly earned codes is still being written — see materializationPending.

inviteCodesAvailable
integer
required

Materialized codes not yet redeemed. Account-wide, independent of the page or status filter.

inviteCodesUsed
integer
required

Materialized codes already redeemed. Account-wide, independent of the page or status filter.

volumeToNextInvite
integer<int64>
required

Additional volume (quote quantums) until the next invite code is earned.

materializationPending
boolean
required

True when earned codes remain to be written. Codes are created lazily and one request writes a bounded number of them, so a trader who earned hundreds at once should call again to see the rest.

codes
object[]
required

The requested page, ordered oldest code first.

total
integer
required

Codes matching the status filter across the whole account — the pagination denominator. Not the length of codes.

limit
integer
required

Page size actually applied, after clamping.

offset
integer
required

Offset actually applied.

hasMore
boolean
required

True when more codes match the filter beyond this page.