---
title: "Get a referrer's referred clients with lifecycle segments"
method: GET
path: "/api/v1/referrals/clients"
tags: ["Referrals"]
---

# Get a referrer's referred clients with lifecycle segments

`GET /api/v1/referrals/clients`

## Request

- Base URL: `https://api.mainnet.aptoslabs.com/decibel`
- URL: `https://api.mainnet.aptoslabs.com/decibel/api/v1/referrals/clients`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/decibel/apis/decibel-trading-api/docs/api/v1/referrals/clients/get.ts> (a function with typed inputs; its response is checked against the schema)

Segment counts across the whole referral set, plus a filtered page of clients ordered
by window volume. Carries no commission amounts: the accrual ledger is not built yet.

## Query parameters

- `referrer_account` string, required
- `days` integer
- `limit` integer
- `offset` integer
- `segment` string
- `search` string
- `include_identities` boolean

## Response `200`

Segment counts and a page of clients

- ReferralClientsResponse
  - `clients` ReferralClient[], required
    - `amps_all_time` number, double, required: All-time Amps from the canonical audit table, every bucket, post-clawback
    - `client` string, required: Full owner address, matching `/affiliates/earnings`
    - `commission_usd` number, double, required: Commission this client generated for the affiliate inside the window, at each day's own stamped rate and penalty. Excludes anything this client's own referrals generated — that is the L2 override and belongs to the sub-affiliates screen.
    - `external_address` string: The address the client actually holds in their wallet, when we know it. Empty otherwise.
    - `joined_unix_ms` integer, required
    - `last_trade_unix_ms` integer, required: 0 when the client has never traded
    - `maker_volume_usd` number, double, required
    - `primary_subaccount` string: The subaccount the app shows the client as their "Primary address". Empty when none yet.
    - `segment` 'active' | 'at_risk' | 'dormant' | 'never_traded', required: Where a client sits in the lifecycle, by how recently it last traded. `NeverTraded` is its own bucket rather than folded into `Dormant`: on real data it is the overwhelming majority (16k of 17k referrals for one mainnet affiliate), and merging it would hide the affiliate's actual problem, which is activation rather than retention. The four buckets partition the referral set, so they sum to the total.
    - `source_code` string, required: Code this client redeemed
    - `subaccounts` string[]: Every subaccount the owner holds, primary included. `search` matches any of them.
    - `taker_volume_usd` number, double, required
    - `trades` integer, required: Trades inside the requested window
    - `wallet_name` string: Wallet the client signed in with, as the stream spells it: `metamask (ethereum)`. Empty when unknown.
  - `referrer_account` string, required
  - `segments` ClientSegments, required: How many clients sit in each lifecycle bucket. Always the whole referral set, never the filtered page, so the four counts sum to the affiliate's referral total.
    - `active` integer, required
    - `at_risk` integer, required
    - `dormant` integer, required
    - `never_traded` integer, required
  - `total_count` integer, required: Clients matching the current filter, for pagination

## Other responses

- `400`: Invalid address or unknown segment
- `500`: Database error

## Changes

- **2026-11-03** `bb095628df0a`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/decibel/apis/decibel-trading-api/changes/api/v1/referrals/clients/get.md)

---

[API](https://skmtc.dev/decibel/apis/decibel-trading-api.md) - [All operations](https://skmtc.dev/decibel/apis/decibel-trading-api/llms.txt) - [OpenAPI document](https://skmtc.dev/decibel/apis/decibel-trading-api/revisions/ee1bcb5822bd?raw)