---
title: "Get top tippees (tip recipients) leaderboard"
method: GET
path: "/v1/leaderboard/tippees"
tags: ["leaderboard"]
---

# Get top tippees (tip recipients) leaderboard

`GET /v1/leaderboard/tippees`

Get the top tippees (tip recipients) leaderboard (public, no auth).

- Ranks by total amount received (USD) in the requested window.
- Includes recipients without a Grove account (address only).
- `window` examples:
    - `24h`: tips received in the last 24 hours
    - `7d`: tips received in the last 7 days
    - `30d`: tips received in the last 30 days
    - `all`: all-time rollup (fast path, no aggregation)
- `aggregate`: Defaults to true (grove-api#617). Entries for accounts with
  multiple linked wallets are combined into a single entry with
  `linked_addresses` showing all contributing wallets, and
  `unique_counterparty_count` is a correct distinct-sender count across
  those wallets (not a per-wallet sum). Pass `aggregate=false` to get the
  legacy per-(address, token) behavior.

## Query parameters

- `window` '24h' | '7d' | '30d' | 'all' — Time window: '24h', '7d', '30d', or 'all' (all time).
- `token` string — Token symbol to filter by.
- `limit` integer — Maximum number of entries to return.
- `aggregate` boolean — Aggregate entries by Grove account (combine multiple linked wallets). Default: true — a creator with multiple receiving wallets appears once, with summed totals and a `linked_addresses` list showing every contributing wallet. Pass `aggregate=false` to opt out and receive one row per (address, token) pair instead — the pre-grove-api#617 behavior, kept as an escape hatch for admin tooling and per-wallet debugging.

## Response `200`

Successful Response

- LeaderboardResponse — Response model for tippers/tippees leaderboard.
  - `window` string, required
  - `token` string, required
  - `aggregated` boolean
  - `entries` LeaderboardEntry[], required
    - `rank` integer, required
    - `address` string, required
    - `account_id` string, nullable
    - `handle` string, nullable
    - `ens_name` string, nullable
    - `base_name` string, nullable
    - `avatar_url` string, nullable — Creator's selected avatar URL
    - `description` string, nullable — Creator's profile bio
    - `total_amount_usd` string, required
    - `total_amount_raw` string, required
    - `tip_count` integer, required
    - `unique_counterparty_count` integer, required
    - `linked_addresses` string[], nullable
    - `last_tip_destination` string, nullable
    - `last_tip_social_graph` string, nullable
    - `last_tip_context` TipContextResponse — Social graph context attached to a tip (response model). This is the output version of TipContext - no validation needed since it's read from the database. All fields are optional as tips may have partial or no context.
      - `source_post_url` string, nullable
      - `sender_username` string, nullable
      - `sender_profile_url` string, nullable
      - `sender_platform` string, nullable
      - `sender_grove_handle` string, nullable
      - `recipient_username` string, nullable
      - `recipient_profile_url` string, nullable
      - `recipient_grove_handle` string, nullable
      - `campaign` string, nullable
      - `referrer` string, nullable
      - `custom_metadata` string, nullable
      - `is_discrete_giveaway_entry` boolean
      - `is_paid_message` boolean
    - `top_tip_destination` string, nullable — Destination from the most recent tip on the highest-volume platform in the requested window.
    - `top_tip_social_graph` string, nullable — Platform name (e.g., 'x', 'reddit', 'substack') with highest USD tip volume in the requested window.
    - `top_tip_context` TipContextResponse — Social graph context attached to a tip (response model). This is the output version of TipContext - no validation needed since it's read from the database. All fields are optional as tips may have partial or no context.
      - `source_post_url` string, nullable
      - `sender_username` string, nullable
      - `sender_profile_url` string, nullable
      - `sender_platform` string, nullable
      - `sender_grove_handle` string, nullable
      - `recipient_username` string, nullable
      - `recipient_profile_url` string, nullable
      - `recipient_grove_handle` string, nullable
      - `campaign` string, nullable
      - `referrer` string, nullable
      - `custom_metadata` string, nullable
      - `is_discrete_giveaway_entry` boolean
      - `is_paid_message` boolean
    - `top_tip_amount_usd` string, nullable — Total USD tipped on the highest-volume platform in the requested window.

## 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)