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.

Updated Nov 22 2026

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/
FileWhat it holdsTypical size
index.jsonThe league table: one summary per stock token, sorted by real fans.Small
tokens/<symbol>.jsonEvery 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>.jsonA 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.jsonGlobal 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
curl -s --compressed https://storage.googleapis.com/tropaclub-data/public/index.json \
  | jq '.tokens[0] | {symbol, holdersTotal, realFans, attendancePct}'
fetch (Node 18+ or a browser)
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 asOf and block in index.json to see whether anything changed.
  • All four kinds of file in one run share the same asOf, except wallets/ shards, which carry no timestamp of their own. Read index.json first 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.

shared/types.ts
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#

FieldMeaning
asOfISO 8601 time of the snapshot.
blockThe 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, logoThe token’s B20 address, its ticker with the c suffix, the company name and an optional logo URL.
priceUsdThe 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.
navUsdCoinbase’s nav_price where the API publishes one (only a minority of tokens do).
multiplierThe 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.
holdersTotalWallets with a nonzero balance: “tickets sold”. It includes pools and contracts.
realFansReal fans as defined in thresholds: “fans in the ground”.
ghostsdust: people’s wallets under $10. farmerOnly: wallets that only ever received giveaways. contracts: pools plus other contracts. With realFans these add up to holdersTotal.
attendancePctrealFans / holdersTotal * 100, one decimal.
top10SharePct, top10ShareExPoolsPctThe share of supply held by the ten largest balances, with and without liquidity pools.
weeklyBuyers, newBuyers7dDistinct 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.
medianWeeklyBuyUsdThe median of each weekly buyer’s total bought that week, in USD. null with no buyers.
hasReferenceMarkWhether a Chainlink feed or a Coinbase nav_price exists for the token.

tokens/<symbol>.json fields#

FieldMeaning
asOf, symbolSnapshot 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.
aThe wallet address, lowercase.
kThe seat kind: real, dust, farmer, contract or pool.
usdCurrent value at priceUsd, rounded to cents.
firstBuyUnix seconds of the wallet’s first inbound transfer of this token, or null.
holdDaysDays of the current unbroken nonzero holding. The main ranking key.
streakWeeksConsecutive ISO weeks, ending with the latest buy, in which the wallet made a net buy. 0 if none.
entryVsMedianPctThe 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.
heldThroughGaptrue if the wallet held across at least one weekend reopen gap.

wallets/<2hex>.json fields#

FieldMeaning
(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.
bestStatThe 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.
totalUsdValue of all stock tokens the wallet holds at the snapshot prices.
firstSeenUnix seconds of the wallet’s earliest first inbound transfer across tokens.

stats.json fields#

FieldMeaning
holdersTotalUnique wallets with a nonzero balance of any stock token.
realWallets, realWallets100Unique 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.
tokensMintedThe number of tokens in index.json.
totalValueUsdValue 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.

index.json (abridged)
{
  "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"
    }
  ]
}
wallets/ab.json (abridged)
{
  "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.