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 corresponding maker/taker fee BPS details.

totalCommission
integer<int64>

Lifetime commission earned, in quote quantums (1e9 = $1).

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 notional fill volume of all of this affiliate's direct (T1) referees, in quote quantums (1e9 = $1). Read from the hourly volume rollup. 0 if the rollup is temporarily unavailable; the endpoint degrades gracefully.

totalReferredVolumeAllTime
integer<int64>

Combined all-time notional fill volume of all of this affiliate's current direct (T1) referees, in quote quantums (1e9 = $1). Same definition as totalReferredVolume30d but with no time window: the lifetime fills of whoever is a T1 referee right now. Read from the per-address all-time volume rollup. 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.

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 the first AccountFeeTierUpdate).