Skip to main content
GET
Get referees
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 one page of the caller’s T1/T2/T3 downline, newest-first by each row’s boundAt. limit defaults to 1000 and is clamped there. Pass parent to page the part of that same downline under one referee: a T1 parent yields their T2 and T3, a T2 parent yields their T3, and a T3 parent has none left inside the three-level book. The header totals (trader count, referred volume, fees earned) are on GET /v1/affiliate/info, not a sum of this page. They cover the same T1/T2/T3 downline as these rows, so across every page rollingVolume sums to totalReferredVolume30d, volumeAllTime to totalReferredVolumeAllTime, and feesEarned to totalCommission (up to rollup lag, and less any commission from referees who have since moved out of the downline). traderCount is the full downline. All figures are perps only. Optional from/to (epoch ms) bound boundAt. Use nextCursor for the next page of the same parent. A cursor from one parent is not valid for another. Signed, and scoped to the caller. address must be the API key’s master Ethereum address; listing another affiliate’s referees 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 referees — 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}$
parent
string

Page the T1/T2/T3 downline under this referee instead of the whole book. A T1 parent yields T2 and T3. A T2 parent yields T3. A T3 parent yields an empty page. The parent must sit in the caller's three-level downline.

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}$
from
integer<int64>

Start boundAt filter (epoch ms, inclusive).

Required range: x >= 0
to
integer<int64>

End boundAt filter (epoch ms, inclusive).

Required range: x >= 0
limit
integer
default:1000

Maximum T1/T2/T3 rows to return. Default and maximum are both 1000; requests above the maximum are silently clamped.

Required range: 1 <= x <= 1000
cursor
string

Opaque cursor returned as nextCursor from the previous page. Encodes (boundAt, tier, address) and avoids duplicate/skip behavior for rows with identical timestamps. Valid only for the same parent (or the same omitted parent) as the page that produced it.

Response

List of referees.

referees
object[]
nextCursor
string

Opaque cursor for the next page, encoded from the last returned row's (boundAt, tier, address). Omitted when there is no next page.