---
title: "Get your referral network and referee earnings"
method: GET
path: "/v1/referrals"
tags: ["referrals"]
---

# Get your referral network and referee earnings

`GET /v1/referrals`

Get the authenticated user's referral dashboard showing:

- **referral_code**: Your shareable referral code (e.g., "GRV-ABC123")
- **stats**: Aggregate metrics about your referral network
  - `total_referees`: Number of accounts you've referred
  - `total_referee_earnings_usd`: Total tips earned by your referees (as tippees)
  - `avg_referee_earnings_usd`: Average tips earned per referee
- **referees**: Paginated list of your referees with their individual earnings

Each referee shows:
- `display_name`: Their handle (if set) or truncated wallet address
- `display_type`: Whether display_name is a "handle" or "wallet"
- `referred_at`: When they joined
- `earnings_usd`: Total tips they've received
- `tip_count`: Number of tips they've received

**Privacy**: Only handles or wallet addresses are shown. No emails or phone numbers.

Authentication: `Authorization: Bearer <CLIENT_JWT>`

Query parameters:
- `limit`: Maximum referees to return per page (default: 50, max: 100)
- `offset`: Number of referees to skip for pagination (default: 0)

## Query parameters

- `limit` integer — Maximum referees to return
- `offset` integer — Number of referees to skip for pagination

## Headers

- `authorization` string, nullable — Bearer JWT issued by Grove that identifies the account.

## Response `200`

Successful Response

- ReferralsResponse — Response model for GET /v1/referrals. Returns the authenticated user's referral dashboard: - Their shareable referral code - Aggregate stats about their referral network - Paginated list of referees with earnings
  - `referral_code` string, required — This account's shareable referral code (e.g., GRV-ABC123)
  - `stats` ReferralStats, required — Aggregate statistics for a referrer's network.
    - `total_referees` integer, required — Total number of accounts referred
    - `total_referee_earnings_usd` string, required — Total tips earned by all referees (as tippees)
    - `avg_referee_earnings_usd` string, required — Average tips earned per referee
  - `referees` RefereeEntry[] — List of referees with their earnings
    - `display_name` string, required — Handle if available, otherwise truncated wallet address
    - `display_type` string, required — Type of display_name: 'handle' or 'wallet'
    - `handle` string, nullable — Raw handle for profile linking (e.g., 'alice' → grove.city/alice)
    - `referred_at` string, required — When the referee joined (ISO 8601)
    - `earnings_usd` string, required — Total tips received by this referee
    - `tip_count` integer, required — Number of tips received
  - `pagination` ReferralPagination, required — Pagination info for referral list.
    - `limit` integer, required — Maximum results per page
    - `offset` integer, required — Current offset
    - `total` integer, required — Total number of referees

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/grove/apis/grove-api.md) · [All operations](https://skmtc.net/grove/apis/grove-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/grove/grove-api/versions/f286b48a8105/schema)