---
title: "Get top tippers leaderboard"
method: GET
path: "/v1/leaderboard/tippers"
tags: ["leaderboard"]
---

# Get top tippers leaderboard

`GET /v1/leaderboard/tippers`

Get the top tippers leaderboard (public, no auth).

- Ranks by total amount tipped (USD) in the requested window.
- Always returns the tipper's Grove custodial address.
- `window` examples:
    - `24h`: tips in the last 24 hours
    - `7d`: tips in the last 7 days
    - `30d`: tips in the last 30 days
    - `all`: all-time rollup (fast path, no aggregation)
- `aggregate`: When true, entries for accounts with multiple linked wallets
  are combined into a single entry with `linked_addresses` showing all wallets.

## 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 — If true, aggregate entries by account (combine multiple linked wallets).

## 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/revisions/f286b48a8105/schema)