curl --request GET \
--url https://api.arcus.xyz/v1/affiliate/referees \
--header 'X-API-Key: <api-key>' \
--header 'X-Signature: <api-key>' \
--header 'X-Timestamp: <api-key>'import requests
url = "https://api.arcus.xyz/v1/affiliate/referees"
headers = {
"X-API-Key": "<api-key>",
"X-Timestamp": "<api-key>",
"X-Signature": "<api-key>"
}
response = requests.get(url, headers=headers)
print(response.text)const options = {
method: 'GET',
headers: {
'X-API-Key': '<api-key>',
'X-Timestamp': '<api-key>',
'X-Signature': '<api-key>'
}
};
fetch('https://api.arcus.xyz/v1/affiliate/referees', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.arcus.xyz/v1/affiliate/referees",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"X-API-Key: <api-key>",
"X-Signature: <api-key>",
"X-Timestamp: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.arcus.xyz/v1/affiliate/referees"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("X-Timestamp", "<api-key>")
req.Header.Add("X-Signature", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.arcus.xyz/v1/affiliate/referees")
.header("X-API-Key", "<api-key>")
.header("X-Timestamp", "<api-key>")
.header("X-Signature", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.arcus.xyz/v1/affiliate/referees")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'
request["X-Timestamp"] = '<api-key>'
request["X-Signature"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"referees": [
{
"address": "<string>",
"code": "<string>",
"boundAt": 123,
"tier": 2,
"rollingVolume": 123,
"commissionBps": 123,
"kickbackBps": 123,
"feesEarned": 123,
"volumeAllTime": 123
}
],
"nextCursor": "<string>"
}{
"error": "Invalid request body",
"code": "GEO_RESTRICTED"
}{
"error": "Invalid request body",
"code": "GEO_RESTRICTED"
}{
"error": "Invalid request body",
"code": "GEO_RESTRICTED"
}{
"error": "rate limited",
"reason": "account_empty",
"retryAfterMs": 850,
"clientId": "my-order-42"
}{
"error": "Invalid request body",
"code": "GEO_RESTRICTED"
}{
"error": "Invalid request body",
"code": "GEO_RESTRICTED"
}Get referees
Returns one page of the caller’s T1/T2/T3 downline, newest-first by each row’s boundAt.
curl --request GET \
--url https://api.arcus.xyz/v1/affiliate/referees \
--header 'X-API-Key: <api-key>' \
--header 'X-Signature: <api-key>' \
--header 'X-Timestamp: <api-key>'import requests
url = "https://api.arcus.xyz/v1/affiliate/referees"
headers = {
"X-API-Key": "<api-key>",
"X-Timestamp": "<api-key>",
"X-Signature": "<api-key>"
}
response = requests.get(url, headers=headers)
print(response.text)const options = {
method: 'GET',
headers: {
'X-API-Key': '<api-key>',
'X-Timestamp': '<api-key>',
'X-Signature': '<api-key>'
}
};
fetch('https://api.arcus.xyz/v1/affiliate/referees', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.arcus.xyz/v1/affiliate/referees",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"X-API-Key: <api-key>",
"X-Signature: <api-key>",
"X-Timestamp: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.arcus.xyz/v1/affiliate/referees"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("X-API-Key", "<api-key>")
req.Header.Add("X-Timestamp", "<api-key>")
req.Header.Add("X-Signature", "<api-key>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.arcus.xyz/v1/affiliate/referees")
.header("X-API-Key", "<api-key>")
.header("X-Timestamp", "<api-key>")
.header("X-Signature", "<api-key>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.arcus.xyz/v1/affiliate/referees")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'
request["X-Timestamp"] = '<api-key>'
request["X-Signature"] = '<api-key>'
response = http.request(request)
puts response.read_body{
"referees": [
{
"address": "<string>",
"code": "<string>",
"boundAt": 123,
"tier": 2,
"rollingVolume": 123,
"commissionBps": 123,
"kickbackBps": 123,
"feesEarned": 123,
"volumeAllTime": 123
}
],
"nextCursor": "<string>"
}{
"error": "Invalid request body",
"code": "GEO_RESTRICTED"
}{
"error": "Invalid request body",
"code": "GEO_RESTRICTED"
}{
"error": "Invalid request body",
"code": "GEO_RESTRICTED"
}{
"error": "rate limited",
"reason": "account_empty",
"retryAfterMs": 850,
"clientId": "my-order-42"
}{
"error": "Invalid request body",
"code": "GEO_RESTRICTED"
}{
"error": "Invalid request body",
"code": "GEO_RESTRICTED"
}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
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).
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:
placeOrder: {"ad":"0x…","ai":N,[,"c":"…"],"ct":N,"g":N,"m":N,"op":1,"p":N,"q":N,"r":0|1,"s":N,"t":N,"v":1}
cancelOrder: {"ad":"0x…","ai":N,[,"c":"…"],"ct":N,[,"id":"…"],"m":N,"op":2,"v":1}
modifyOrder: {"ad":"0x…","ai":N,[,"c":"…"],"ct":N,"g":N,[,"id":"…"],"m":N,"op":3,"p":N,"q":N,"r":0|1,"s":N,"t":N,"v":1} (exactly one of id / c)
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
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.
^(0x|0X)?[0-9a-fA-F]{40}$Was this page helpful?