GET /stats/referrals
Referral programme aggregate
Referral programme aggregate.
operationId: fetchReferralStats · Rate-limit cost: 5
Declared server:
https://api.testnet.nexus.xyz/v1. See Networks.
Not reachable through CCXT. Venue-wide growth analytics. CCXT models market and account data, not referral programmes.
Authentication: none. This endpoint is public.
Venue-wide referral figures: codes minted, referral edges bound, how many referred accounts went on to trade, and the conversion ratio between the last two.
Aggregate only, by construction. Every field is a venue total. The response type has no field that can carry an account id, an address, a referral code, or a per-account figure, and the endpoint takes no parameters — there is nothing to scope it to. That is what makes it public where GET /account/referrals, which answers about one caller, is not.
The denominator excludes a set, and says so. Registering an agent is the only path that mints a referral code, so an account that has only ever logged in holds none. accounts_without_code is that whole set: it includes every account predating the programme, but it is not that frozen legacy backlog and must not be charted as one — it grows whenever a wallet arrives and never registers. conversion_ratio is active_referred / edges_bound, which the codeless set enters on neither side, and accounts_without_code reports its size outright rather than leaving a reader to infer the omission. Do not divide codes_minted by any account total you obtained elsewhere — GET /stats/balance-distribution's account_count included — and call the result a conversion rate.
Nothing here degrades to zero. conversion_ratio and latest_edge_at are null on a venue with no edges, because a 0.0000 ratio would assert that edges exist and none converted. accounts_without_code is null with accounts_without_code_error set when that one count could not be computed, and the rest of the aggregate is still served. A backend that is unreachable is a 502 or 503, never a page of zeros.
conversion_ratio is a decimal STRING, like every other ratio and monetary figure in this contract. network names the chain network this indexer serves and testnet is the same fact as a boolean, both derived from auth.network rather than asserted; note restates all of this in prose.
Venue-wide referral aggregate
Venue-wide referral programme aggregate. Aggregate only — it carries no account id, address, referral code, or per-account figure by construction.
Referral codes in existence. One per account that has registered since the programme shipped — NOT the account total, which also includes the codeless cohort reported by accounts_without_code.
Referral edges bound. An edge is immutable once written and one account can hold at most one, so this is also the number of distinct referred accounts.
The subset of edges_bound whose referred account has since traded. Always less than or equal to edges_bound.
active_referred / edges_bound as a decimal string, four decimal places. null when edges_bound is zero — there is nothing to divide, and "0.0000" would assert that edges exist and none converted.
0.3006Accounts that have never registered an agent, which includes every account predating the programme. Registering an agent is the only path that mints a code, while an account row is also created on first login and on first credential — so this is NOT a frozen legacy cohort, and it grows whenever a wallet arrives and never registers. Published so the gap between this figure and codes_minted is visible rather than inferred. null when it could not be computed, in which case accounts_without_code_error says so and the rest of the aggregate is still accurate.
Machine-readable reason accounts_without_code is null. Omitted when the cohort count succeeded — the same shape OpenInterest.quote_error carries, so a consumer that branches on presence and one that branches on a null value are both right.
COHORT_COUNT_UNAVAILABLEWhen the most recent edge was bound. null on a venue with no edges — never a zero timestamp.
When this aggregate was observed, read from the accounts database clock rather than the serving replica's, so it describes the data rather than the process.
The chain network THIS indexer serves, taken from its required auth.network configuration rather than asserted by the handler. Known values: mainnet (real funds), testnet (play funds), local. An open string rather than an enum, so a network added later cannot break deserialization — but treat an identifier you do not recognize as real funds.
testnettrue on every network whose funds are not real — the boolean reading of network. local and testnet both report true, so network is the field that tells them apart.
The caveats above, in prose, for a consumer that publishes the figure.
BAD_GATEWAY — the accounts backend is reachable but the aggregate request to it failed. Retryable. Never read it as an empty programme.
REFERRAL_STORE_NOT_CONFIGURED — this deployment has no accounts backend configured, so the figure does not exist here. Every call fails the same way until the deployment is configured.
GET /v1/stats/referrals HTTP/1.1
Host: api.testnet.nexus.xyz
Accept: */*
{
"codes_minted": 4812,
"edges_bound": 1337,
"active_referred": 402,
"conversion_ratio": "0.3006",
"accounts_without_code": 915,
"latest_edge_at": "2026-09-16T11:04:22Z",
"as_of": "2026-09-16T16:00:03Z",
"network": "testnet",
"testnet": true,
"note": "Illustrative testnet data. Venue-wide referral aggregate — counts only, never a per-account figure, an address, or a referral code. `accounts_without_code` counts accounts that have never registered an agent, which includes every account predating the programme; `conversion_ratio` is `active_referred / edges_bound`, so that cohort appears in neither half of it."
}API version 0.9.131
Last updated