Public data feed
Everything on The Ground and The Attendance is read from four kinds of static JSON file. They are public, need no key and are refreshed every six hours.
Status
The first files appear after the first scheduled run following launch. Until a run has finished, a URL below can return 404. Once published, index.json carries the time of the last snapshot in asOf.
Base URL and files#
All files live under one public Google Cloud Storage prefix:
https://storage.googleapis.com/tropaclub-data/public/| File | What it holds | Typical size |
|---|---|---|
index.json | The league table: one summary per stock token, sorted by real fans. | Small |
tokens/<symbol>.json | Every seat of one token, real fans first in rank order, then ghosts. Symbols keep their case, for example tokens/NVDAc.json. | Up to a few MB for the largest grounds |
wallets/<2hex>.json | A shard of the wallet lookup. The two hex digits are the first two after 0x in the lowercase address, so there are 256 shards. | Small |
stats.json | Global numbers: unique holders, real wallets, weekly buyers by week. | Small |
Example fetch#
Read the table, then look up one wallet. A wallet lookup has two steps: take the first two hex digits after 0x of the lowercase address, fetch that shard, then index it by the full address.
curl -s --compressed https://storage.googleapis.com/tropaclub-data/public/index.json \
| jq '.tokens[0] | {symbol, holdersTotal, realFans, attendancePct}'const BASE = 'https://storage.googleapis.com/tropaclub-data/public';
async function lookup(address: string) {
const a = address.toLowerCase();
const shard = a.slice(2, 4); // "0xab12..." -> "ab"
const res = await fetch(`${BASE}/wallets/${shard}.json`);
if (!res.ok) throw new Error(`shard ${shard}: ${res.status}`);
const wallets = await res.json(); // Record<address, WalletSummary>
return wallets[a] ?? null; // null: no stock token held
}Files are gzip-compressed on the wire. Browsers and fetch decompress them for you, and curl needs --compressed.
Caching and freshness#
- Files are served with
Cache-Control: public, max-age=300, so any cache may hold a file for up to five minutes. - The indexer replaces the files every six hours (see update cadence). Poll no more often than that. Compare
asOfandblockinindex.jsonto see whether anything changed. - All four kinds of file in one run share the same
asOf, exceptwallets/shards, which carry no timestamp of their own. Readindex.jsonfirst if you need to know which snapshot a shard belongs to. - Browser requests from other origins depend on the storage service’s cross-origin headers. If a browser blocks a request, fetch from a server instead. Cross-origin behaviour is not part of the feed’s contract yet.
Schema#
The files are written by the indexer and read by the website using one shared set of TypeScript types. This is the whole contract. Fields marked optional can be missing, and new optional fields can be added at any time, so ignore keys you do not know.
export type SeatKind = 'real' | 'dust' | 'farmer' | 'contract' | 'pool';
export interface TokenSummary {
address: `0x${string}`;
symbol: string; // e.g. "NVDAc"
name: string; // e.g. "NVIDIA"
logo?: string;
priceUsd: number | null; // DEX price used for $ values
navUsd: number | null; // Coinbase API nav_price if present
multiplier: number; // ERC-8056 uiMultiplier
holdersTotal: number; // nonzero balances ("tickets sold")
realFans: number; // >= $10, EOA/smart wallet, not farmer-only ("fans in the ground")
ghosts: { dust: number; farmerOnly: number; contracts: number };
attendancePct: number; // realFans / holdersTotal * 100
top10SharePct: number;
top10ShareExPoolsPct: number;
weeklyBuyers: number; // last 7d distinct buyer wallets (bots >50 swaps excluded)
newBuyers7d: number;
medianWeeklyBuyUsd: number | null;
hasReferenceMark: boolean; // Chainlink feed or nav_price exists
priceSource?: 'dex' | 'reference' | null;
}
export interface IndexFile {
asOf: string; // ISO time of the snapshot
block: number; // last indexed Base block
tokens: TokenSummary[]; // sorted by realFans desc
}
export interface Seat {
a: string; // lowercase address
k: SeatKind;
usd: number; // current value at priceUsd
firstBuy: number | null; // unix seconds of first inbound transfer
holdDays: number; // days of current unbroken nonzero holding
streakWeeks: number; // consecutive ISO weeks with a net buy (0 if none)
entryVsMedianPct: number | null; // avg entry price vs median real-fan entry, % (negative = cheaper)
heldThroughGap: boolean; // held across at least one weekend reopen gap
}
export interface TokenSeatsFile {
asOf: string;
symbol: string;
seats: Seat[]; // real fans first in rank order (rank = index+1), then ghosts
}
export type BestStatKey = 'earliest' | 'longestHold' | 'entryVsMedian' | 'heldThroughGap' | 'streak';
export interface WalletTokenEntry {
symbol: string;
usd: number;
kind: SeatKind;
rank: number | null; // rank among real fans (null if ghost)
of: number; // realFans for that token
bestStat: { key: BestStatKey; label: string; pct: number } | null; // "top pct%" among real fans
}
export interface WalletSummary {
tokens: WalletTokenEntry[];
totalUsd: number;
firstSeen: number | null;
}
// wallets/<first two hex chars after 0x>.json
export type WalletShard = Record<string, WalletSummary>;
export interface StatsFile {
asOf: string;
holdersTotal: number; // unique nonzero wallets across all tokens
realWallets: number; // unique real wallets >= $10 across tokens
realWallets100: number;
weeklyBuyers: { weekStart: string; buyers: number; newBuyers: number; medianBuyUsd: number }[];
tokensMinted: number;
totalValueUsd: number;
}index.json fields#
| Field | Meaning |
|---|---|
asOf | ISO 8601 time of the snapshot. |
block | The last Base block the indexer applied. Runs stay about 150 blocks behind the head. |
tokens[] | One TokenSummary per minted stock token that has any holder, sorted by realFans descending, then by holdersTotal. |
address, symbol, name, logo | The token’s B20 address, its ticker with the c suffix, the company name and an optional logo URL. |
priceUsd | The price used to value every seat, in USD per token. null when the token is unpriced. It already includes the multiplier. |
priceSource | "dex": the deepest DEX pair with at least $1,000 of liquidity. "reference": no such pair, so the underlying stock’s last price times the multiplier (else Coinbase’s nav_price). null: unpriced, all seats show usd: 0. |
navUsd | Coinbase’s nav_price where the API publishes one (only a minority of tokens do). |
multiplier | The ERC-8056 uiMultiplier. Dividends are paid as shares through increases of this number. Above 1 means the token has had a split or stock dividend. |
holdersTotal | Wallets with a nonzero balance: “tickets sold”. It includes pools and contracts. |
realFans | Real fans as defined in thresholds: “fans in the ground”. |
ghosts | dust: people’s wallets under $10. farmerOnly: wallets that only ever received giveaways. contracts: pools plus other contracts. With realFans these add up to holdersTotal. |
attendancePct | realFans / holdersTotal * 100, one decimal. |
top10SharePct, top10ShareExPoolsPct | The share of supply held by the ten largest balances, with and without liquidity pools. |
weeklyBuyers, newBuyers7d | Distinct person wallets that received the token from a DEX purchase in the last seven days, and the subset making their first DEX buy of it. Wallets with more than 50 swaps that week are excluded as bots. |
medianWeeklyBuyUsd | The median of each weekly buyer’s total bought that week, in USD. null with no buyers. |
hasReferenceMark | Whether a Chainlink feed or a Coinbase nav_price exists for the token. |
tokens/<symbol>.json fields#
| Field | Meaning |
|---|---|
asOf, symbol | Snapshot time and the token this file is about. |
seats[] | Real fans first, in rank order, so rank is the array index plus one. Ghosts follow in this order: dust, farmer, contract, pool, with larger balances first inside each kind. |
a | The wallet address, lowercase. |
k | The seat kind: real, dust, farmer, contract or pool. |
usd | Current value at priceUsd, rounded to cents. |
firstBuy | Unix seconds of the wallet’s first inbound transfer of this token, or null. |
holdDays | Days of the current unbroken nonzero holding. The main ranking key. |
streakWeeks | Consecutive ISO weeks, ending with the latest buy, in which the wallet made a net buy. 0 if none. |
entryVsMedianPct | The wallet’s average entry price against the median real fan’s, in percent. Negative means a cheaper entry. null when there are no priced buys. |
heldThroughGap | true if the wallet held across at least one weekend reopen gap. |
wallets/<2hex>.json fields#
| Field | Meaning |
|---|---|
| (object keys) | Lowercase wallet addresses. A shard holds every wallet whose address starts with those two hex digits and that holds any stock token, ghosts included. An address that is not in its shard holds none. |
tokens[] | One entry per token held, largest value first. Each has symbol, usd, kind, and for real fans rank out of of (the token’s realFans). rank is null for ghosts. |
bestStat | The wallet’s strongest claim on that token: key is one of earliest, longestHold, entryVsMedian, heldThroughGap or streak, label is display text, and pct reads as “top pct%” among real fans. null for ghosts. |
totalUsd | Value of all stock tokens the wallet holds at the snapshot prices. |
firstSeen | Unix seconds of the wallet’s earliest first inbound transfer across tokens. |
stats.json fields#
| Field | Meaning |
|---|---|
holdersTotal | Unique wallets with a nonzero balance of any stock token. |
realWallets, realWallets100 | Unique person wallets, not farmer-only, whose combined stock-token value across all tokens is at least $10, and at least $100. |
weeklyBuyers[] | One row per ISO week: weekStart (a Monday, YYYY-MM-DD), distinct buyers, how many of them were newBuyers making their first stock-token buy that week, and the medianBuyUsd. |
tokensMinted | The number of tokens in index.json. |
totalValueUsd | Value of all supply at the snapshot prices, rounded to whole dollars. |
Note one difference on purpose: realFans in index.json tests the $10 line per token, while realWallets in stats.json tests it on a wallet’s total across tokens.
Sample shapes#
Abridged examples. Field names and types are exact. The values are samples from the Nov 21 2026 count where we know them, and illustrative where we do not.
{
"asOf": "2026-11-21T16:25:00.000Z",
"block": 60439800,
"tokens": [
{
"address": "0x…",
"symbol": "NVDAc",
"name": "NVIDIA",
"priceUsd": 130.22,
"navUsd": null,
"multiplier": 1.0005,
"holdersTotal": 17685,
"realFans": 1613,
"ghosts": { "dust": 8432, "farmerOnly": 6288, "contracts": 1352 },
"attendancePct": 9.1,
"top10SharePct": 76.6,
"top10ShareExPoolsPct": 57.7,
"hasReferenceMark": true,
"priceSource": "dex"
}
]
}{
"0xab…": {
"tokens": [
{
"symbol": "NVDAc",
"usd": 42.18,
"kind": "real",
"rank": 212,
"of": 1613,
"bestStat": { "key": "longestHold", "label": "Longest holders", "pct": 13.2 }
}
],
"totalUsd": 42.18,
"firstSeen": 1786509300
}
}Versioning and stability#
- The schema above is the current and only version. Changes are additive: new optional fields can appear, and existing fields keep their names and meanings.
- If a field must change meaning, it is announced in the changelog first.
- Rankings are not stable across snapshots: hold time and balances change, so ranks move.
Licence#
The feed is free for non-commercial use: research, journalism, dashboards, bots and personal tools. When you publish a number from it, name Tropa Club and the asOf time it came from. For commercial use, including a product, a paid dashboard or resale, contact us for a commercial tier. The underlying facts are public chain data. What the feed adds is the classification and the ranking.
The feed carries no personal data beyond wallet addresses, which are already public on Base. It is provided as is, with no warranty, and it is not investment advice.