---
title: "Get trading activity of a referrer's referred clients"
method: GET
path: "/api/v1/referrals/activity"
tags: ["Referrals"]
---

# Get trading activity of a referrer's referred clients

`GET /api/v1/referrals/activity`

## Request

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

Per-level window totals plus a page of direct (L1) referrals, each carrying the L2
clients it referred. Carries no commission figures: the accrual ledger those would
come from does not exist yet.

## Query parameters

- `referrer_account` string, required
- `days` integer
- `limit` integer
- `offset` integer

## Response `200`

Referral activity summary and client page

- ReferralActivityResponse: Referral activity: per-level totals plus a page of direct referrals.
  - `clients` ReferralActivityClient[], required: A page of L1 clients, each carrying its own L2s
    - `client` string, required: Full owner address, matching `/affiliates/earnings` — an affiliate already sees its own referees unmasked there, so masking only here would be inconsistent.
    - `commission_usd` number, double, required: Commission this client generated on its own trading, at the L1 rate of each day. Excludes what its L2s generated — those carry their own figures.
    - `level` integer, required: Always 1: this list holds direct referrals, and their L2s hang off `sub_clients`.
    - `maker_volume_usd` number, double, required
    - `sub_client_count` integer, required: L2 clients that traded in the window, counted before the 25-row cap.
    - `sub_clients` ReferralActivitySubClient[], required: This L1's own referred clients that traded in the window, busiest first, capped at `sub_client_count`'s first 25 rows.
      - `client` string, required: Full owner address, matching the L1 rows.
      - `commission_usd` number, double, required: Commission this client generated, at the L2 override rate of each day.
      - `maker_volume_usd` number, double, required
      - `taker_volume_usd` number, double, required
      - `top_market` string, required: Market carrying the most of this client's volume; empty when unresolved.
      - `trades` integer, required
    - `taker_volume_usd` number, double, required
    - `top_market` string, required: Market carrying the most of this client's volume; empty when unresolved.
    - `traded` boolean, required: False when this L1 did not trade in the window and is listed only as the parent of L2s that did. Its own columns are then zero, which is a different claim from "traded zero volume" and should not be rendered as a figure.
    - `trades` integer, required
  - `referrer_account` string, required
  - `summary` ReferralActivityLevel[], required: Levels that traded in the window, level 1 first
    - `clients` integer, required: Clients who traded in the window
    - `commission_usd` number, double, required: Commission this level generated in the window, at each day's own stamped rate and penalty. Zero when the affiliate has no accrual rows — which is the state before the ledger runs, not a claim that the level earned nothing.
    - `level` integer, required: 1 = direct referral, 2 = sub-affiliate's referral
    - `maker_volume_usd` number, double, required
    - `taker_volume_usd` number, double, required
    - `trades` integer, required
  - `total_count` integer, required: L1 rows the window holds, for pagination. Counts parents, not clients: an L1 that only appears because its L2s traded still occupies a row.

## Other responses

- `400`: Invalid address
- `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/activity/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)