GET /leaderboards/top-buyers

Get users ranked by purchase volume within a specified time period.

GET/v1/leaderboards/top-buyers

Authentication

Required: No
Payment: No

Query Parameters

Parameter	Type	Required	Description
`page_size`	number	No	Results per page (default: 20)
`period`	string	No	Time period: `1d`, `7d`, `30d`, `all` (default: `all`)

Response

Status: 200 OK

{
  "data": [
    {
      "rank": "1",
      "user_id": "user-uuid",
      "username": "contentcollector",
      "wallet_address": "0x8Ba1f109551bD432803012645Hac136c8cb2bc43",
      "total_purchases": "850",
      "total_spent": "50000000000",
      "unique_entries_purchased": "620",
      "unique_feeds_purchased_from": "45",
      "joined_at": 1692000000
    }
  ],
  "period": "all"
}

Example Requests

# Top buyers all-time
curl "https://api.grapevine.fyi/v1/leaderboards/top-buyers"
 
# Top buyers this month
curl "https://api.grapevine.fyi/v1/leaderboards/top-buyers?period=30d"
 
# Top 10 buyers today
curl "https://api.grapevine.fyi/v1/leaderboards/top-buyers?period=1d&page_size=10"

Response Fields

Field	Description
`rank`	Position in the leaderboard
`user_id`	Unique user/wallet identifier
`username`	Display name (null if not set)
`wallet_address`	Ethereum wallet address
`total_purchases`	Number of purchases made
`total_spent`	Total amount spent (in wei)
`unique_entries_purchased`	Distinct entries purchased
`unique_feeds_purchased_from`	Distinct feeds purchased from
`joined_at`	Account creation timestamp

Notes

Ranked by total amount spent (highest first)
Amounts are in wei (USDC has 6 decimals)
Period filters purchases made within the timeframe