GET /account/referrals
Account referrals summary
Account referrals summary.
operationId: fetchAccountReferrals
Declared server:
https://api.testnet.nexus.xyz/v1. See Networks.
Not reachable through CCXT. Referral program metadata. CCXT has no unified method for a venue's own referral program.
Authentication: agentAuth, hmacAuth.
The authenticated account's own referral code and how many accounts used it. The account id is taken from the authenticated credentials, not a parameter — same convention as GET /account/fees.
HMAC API key authentication. Send three headers:
X-API-Key: your key ID (e.g.nx_a1b2c3...)X-Timestamp: current time in unix millisecondsX-Signature:hex(hmac_sha256(secret, timestamp + "\n" + METHOD + "\n" + path + "\n" + query + "\n" + sha256_hex(body)))
Timestamp must be within 30 seconds of server time.
The key is network-scoped; the signature is not. The canonical string above has no network component, so the same signed request is byte-identical on every host. What stops a testnet key from authenticating against mainnet is that the key does not exist in that host's key store — sign only for the host that minted the key, and never replay a signed payload against another network. Presented to the wrong host, a key is refused with the same opaque 401 as an unknown key and must not be retried there. See “API keys are bound to one network” in the API description.
Account referrals summary.
The authenticated account's own referrals summary (ENG-14757): its own referral code, plus how many accounts used it. referred_count is every account that redeemed the code; active_referred_count is the subset that has also traded at least once (a qualifying account_activity row) — referral-edge existence alone is never a qualifying signal for any metric beyond a raw count. Any metric-shaped surface (a headline count, a leaderboard, a reward-adjacent badge) must render active_referred_count, never referred_count — per PRD A-7, an unqualified referral count must never be presented as "a real referred user." referred_count exists for a literal "codes redeemed" display only, if that is ever shown separately from the qualified figure.
This account's own 22-character referral code. null if no code has ever been minted for this account — a real, permanent state for any account that completed registration before ENG-13624 shipped ensure_code_and_bind on POST /agents/register, since nothing on this read path mints a code retroactively.
9f2c3a1b4d5e6f708192a3Every account that redeemed this account's code, regardless of trading activity. A raw count, not a metric — see this schema's description before rendering it as one.
The subset of referred_count that has also traded at least once. This is the field any metric-shaped UI must use per PRD A-7 (a referral count read as a metric requires qualifying activity), not referred_count.
Authentication failed. All 401 responses return the same opaque body to prevent information leakage. A credential minted on a different network is one of the causes it hides — by design, so that a key id cannot be probed for existence on another network. Do not retry it against another host.
BAD_GATEWAY — the accounts-directory backend is reachable but the summary request to it failed. Retryable; not evidence the referral relationship itself is wrong.
REFERRAL_STORE_NOT_CONFIGURED — this deployment has no accounts-directory backend configured. Not a per-account condition; every call fails the same way until the deployment is configured.
GET /v1/account/referrals HTTP/1.1
Host: api.testnet.nexus.xyz
X-API-Key: YOUR_API_KEY
Accept: */*
{
"code": "9f2c3a1b4d5e6f708192a3",
"referred_count": 3,
"active_referred_count": 1
}Test it cannot sign this request. X-Signature is an HMAC computed per call: see Authentication, or use an SDK.
API version 0.9.122
Last updated