Skip to main content
GET
Get affiliate info
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 own affiliate information including code, tier, commission totals, and referee count. Signed, and scoped to the caller. address must be the API key’s master Ethereum address; reading another wallet’s affiliate info is 403. The Ed25519 request signature is required because X-API-Key alone proves nothing (API keys are Ed25519 public keys, listable by anyone via GET /v1/apiKeys). With no request body the signing message is timestamp + action (action info — the path segment verbatim, casing included).

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 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) still use the legacy scheme: signing_message = X-Timestamp + ACTION + canonicalJSON(body), where ACTION is the camelCase final path segment.

Batch endpoints (batchPlaceOrders, batchCancelOrders, batchModifyOrders) 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 / ModifyOrderRequest).

Read endpoints are authenticated by ?address= (and optionally X-API-Key) only — no signature is required, except for the signed affiliate reads (see the Referral tag), which require the full header triple; with no body their 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 of the affiliate. Must match the API key's master address.

20-byte EVM address as hex: optional 0x or 0X prefix and exactly 40 hexadecimal digits. API responses normalize to lowercase a–f after 0x.

Pattern: ^(0x|0X)?[0-9a-fA-F]{40}$

Response

Affiliate info.

address
string

Lower-case 0x-prefixed 20-byte affiliate address.

code
string

Active referral code, or empty string if revoked / never created.

kickbackBps
integer

Affiliate's current kickback rate in basis points (0-5000). 0 means no kickback.

tier
integer

Current affiliate/account tier level used for referral commission rates. Use tradingFeeTier for the account's maker/taker fee BPS details.

totalCommission
integer<int64>

Lifetime (all-time) commission earned from the T1/T2/T3 downline, in quote quantums (1e9 = $1). Commission accrues on perps fills only; spot trading earns no referral commission. Snapshot of the most recent all-time commission total.

pendingCommission
integer<int64>

Commission earned since the last claim cutoff, in quote quantums. Decreases to 0 when a ClaimProcessed event covers the full outstanding balance.

volume30d
integer<int64>

Notional fill volume over the trailing 30 days, in quote quantums. null/0 if the rollup is temporarily unavailable; the endpoint degrades gracefully rather than failing /info.

totalReferredVolume30d
integer<int64>

Combined trailing-30-day perps notional fill volume of this affiliate's current T1/T2/T3 downline (the same referees counted by traderCount and listed by GET /v1/affiliate/referees), in quote quantums (1e9 = $1). Equals the sum of those rows' rollingVolume. Spot volume is not included. Read from the hourly volume rollup. 0 if the rollup is temporarily unavailable; the endpoint degrades gracefully.

totalReferredVolumeAllTime
integer<int64>

Combined all-time perps notional fill volume of this affiliate's current T1/T2/T3 downline, in quote quantums (1e9 = $1). Same referee set as totalReferredVolume30d with no time window: the lifetime fills of whoever is in the downline right now. Equals the sum of the /referees rows' volumeAllTime, and is never below totalReferredVolume30d. Spot volume is not included. Read from the per-address all-time volume rollup, so a large affiliate does not scan hourly history. Trails live fills by the rollup's refresh lag. 0 if the rollup is temporarily unavailable; the endpoint degrades gracefully.

commission30d
integer<int64>

Commission earned over the trailing 30 days, in quote quantums. Computed as the lifetime commission snapshot minus the running commission total as of the window start (boundary subtraction). 0 if the rollup is temporarily unavailable; the endpoint degrades gracefully.

traderCount
integer<int64>

Number of referees in this affiliate's T1/T2/T3 downline. Maintained when a referee binds or is moved. A missing snapshot is filled once from that downline and then read as an integer.

tradingFeeTier
object

The user's current trading fee tier (level + maker/taker BPS). Omitted when the store has not yet recorded a tier for this address (new accounts before a fee tier has been assigned).