Cupola · docs
Introduction
Members of the US House of Representatives must report every stock trade above $1,000 within 45 days. The reports are public: the Clerk of the House posts each one as a signed PDF. Cupola reads those reports and buys what the members bought, as tokenized shares on Solana, with the filing attached to every order.
The vault is drawn as a cupola with 100 coffers. Each coffer is a light, 1% of the vault. A purchase on a filing lights coffers in copper; USDC is bare stone.
The words
| Word | Meaning |
|---|---|
| Filing | One periodic transaction report (PTR), signed by a member and posted by the Clerk. |
| Row | One trade inside a filing: asset, owner, side, trade date, notice date, amount range. |
| The reading | The list of newest filings, read every 15 minutes. |
| Light | 1% of the vault. There are 100. |
| Lot | The lights bought on one member's filings of one stock. |
| The gallery | What the vault holds: lit coffers and bare stone. |
| The ledger | Every row as a numbered line, with its Filing ID and the reason for what the vault did. |
| Seat | A share of the vault, received for depositing USDC. |
Quick start
- Open The reading. The newest filings load from the Clerk, each row with what the vault does with it.
- Filter by side, by Tokenized on Solana or by a ticker or name. Click a member to open the signed PDF.
- Open The gallery to see which coffers are lit and by whose filings.
- Open A seat, type an amount, and copy the order sheet.
From code
The same rules run in a small module served from this site. The reading endpoint is public and cached for 15 minutes.
import { readRoll, plan } from "%ORIGIN%/lib/cupola.js";
const roll = await readRoll({ base: "%ORIGIN%", limit: 24 });
const p = plan(roll.filings);
console.log(p.lit + " of 100 lights", p.holdings.map(h => h.ticker));
curl -s "%ORIGIN%/api/roll-call?limit=12&offset=0"
<script type="module">
import { readRoll, plan } from "%ORIGIN%/lib/cupola.js";
const p = plan((await readRoll({ base: "%ORIGIN%" })).filings);
document.title = "Cupola: " + p.lit + " lights lit";
</script>Try it
Reads the newest filings right now through the endpoint and runs the rules on them.
How it works
1. Read
Every 15 minutes the endpoint downloads the Clerk's index of this year's financial disclosures ({year}FD.zip), keeps the filings of type P, newest first, and opens each signed PDF. A dependency-free reader decodes the text through each font's ToUnicode map and rebuilds the table: owner, asset, ticker, asset type, side, trade date, notice date and amount range.
2. Match
Each ticker is looked up in Jupiter's verified token list for a tokenized share on Solana (xStocks, symbol {TICKER}x). The match carries the mint, the quote in USD and the pool liquidity.
3. Decide
Every row gets one of three answers, oldest first:
| Answer | When | Lights |
|---|---|---|
| Follow | A purchase of a listed stock with a tokenized share and a pool of at least $1,000 | From the range, capped at 12 per stock |
| Release | A sale or partial sale by a member whose lot the vault holds | That member's lot leaves |
| Skip | Everything else, with the reason on the line | 0 |
4. Order
A follow becomes one order in US market hours. A seat holds a share of every lot, so a deposit is split across the lit coffers in their proportions and the rest stays in USDC.
The reading
The table lists filings grouped by the week they were filed. Each row shows the member as printed on the filing, the trade date, the filing date and how many days the notice took, the asset and its owner (self, spouse, joint, child), the side, the amount range as printed, the tokenized share and its quote, and the answer.
A notice later than 45 days after the trade is marked in red. Paper filings that were scanned have no text to read; they appear with a link to the Clerk's PDF and are skipped.
Read older filings pages back 24 filings at a time through this year and the last.
The gallery
The plan shows the cupola from below: 5 tiers of 20 coffers. Coffers light from the lowest tier inward, largest holding first. A half light shows as half a coffer. Hover a coffer for the stock, its lights and the members whose lots it holds.
When the book asks for more than 100 lights, every holding is scaled down by the same factor and the status line says so.
The ledger
Every row the vault read becomes a numbered line, oldest first. Lines are renumbered as older filings load, because order is by filing date.
| Kind | Lights | Example reason |
|---|---|---|
Follow | +½ … +6 | Sized by the range · Capped at 12 lights |
Release | −the lot | Sale filed, the lot is released |
Skip | 0 | No tokenized share on Solana · Pool under $1,000 · Government bond, not a listed stock · Sale filed, the lot is another member's |
A seat
Type an amount in USDC. The sheet splits it across the holdings in proportion to their lights, converts each part to units of the tokenized share at the quote, and keeps the bare-stone part in USDC. Copy the order sheet puts the plan on your clipboard as JSON.
{
"seat": 1000,
"staked": 0,
"orders": [ { "ticker": "MU", "mint": "Xs…", "usdc": 15, "units": 0.0207 } ],
"usdc": 935,
"fees": { "managementYear": 15, "withdrawal": 3 }
}Sizing spec
The filing prints a range, not an amount. The range sets the size of the order:
| Amount range | Lights | Share of the vault |
|---|---|---|
| $1,001 – $15,000 | ½ | 0.5% |
| $15,001 – $50,000 | 1 | 1% |
| $50,001 – $100,000 | 2 | 2% |
| $100,001 – $250,000 | 3 | 3% |
| $250,001 – $500,000 | 4 | 4% |
| $500,001 – $1,000,000 | 5 | 5% |
| Over $1,000,000 | 6 | 6% |
Constants
| Name | Value | Meaning |
|---|---|---|
TOTAL | 100 | Lights in the cupola |
CAP_PER_STOCK | 12 | No stock lights more than this |
MIN_POOL_USD | 1,000 | Minimum liquidity of the tokenized share |
LATE_DAYS | 45 | STOCK Act notice window |
HOLD_DAYS | 180 | A lot is held this long or until its member files the sale |
READ_EVERY_MIN | 15 | Cache of the reading |
Endpoint
GET /api/roll-call?limit=24&offset=0, limit up to 48. The response:
{
"read": "2026-11-17T09:18:00.000Z",
"total": 472, "offset": 0, "limit": 24, "xstocks": 1433,
"filings": [{
"member": "Lloyd Doggett", "district": "TX37", "filed": "2026-11-11",
"doc": "20035826", "url": "https://disclosures-clerk.house.gov/…/20035826.pdf",
"status": "read",
"rows": [{
"asset": "Coca-Cola Company", "ticker": "KO", "kind": "ST", "owner": "self",
"side": "Purchase", "traded": "2026-10-01", "notified": "2026-11-05",
"low": 1001, "high": 15000, "range": "$1,001 – $15,000",
"onchain": { "mint": "XsaB…", "symbol": "KOx", "price": 99.11, "liquidity": 90327 }
}]
}]
}Filing status
| status | Meaning |
|---|---|
read | Rows parsed |
scanned | A paper filing with no text layer |
empty | Text found, no table rows |
unreachable | The PDF did not open in time |
Module
| Export | Returns |
|---|---|
readRoll({ base, limit, offset }) | The endpoint's JSON |
decide(row, filing) | { act, lights, reason, late, isLate } |
plan(filings) | { lines, holdings, lit, dark, scaled } |
seat(usdc, plan) | Orders per stock, USDC part, fees |
lightsFor(low) | Lights for the low end of a range |
LIGHTS, RULES, FEES | The tables on this page |
The PDF and ZIP reader the endpoint uses is lib/ptr.js, also without dependencies.
Limits
- Ranges, not amounts. A $1,001 – $15,000 row could be either end. The size follows the range.
- House only. Senate reports sit behind a search form and are not read yet.
- Scanned paper. Some members file on paper. Those reports have no text and are skipped with a link.
- Tokenized shares. Not every stock has one, and some pools are thin. Those rows are skipped.
- Dry run. Until the vault opens, the gallery, the ledger and the seat are computed in your browser on today's data.
$CUPOLA
The vault takes its fees in shares. Half of what they redeem for buys $CUPOLA and burns it, and part of the fee on every $CUPOLA trade does the same. Staked $CUPOLA waives the management and withdrawal fees on 1,000 USDC of its holder's seat for every 100,000 $CUPOLA.
| Field | Value |
|---|---|
| Ticker | $CUPOLA |
| CA | soon |
| Buy | Buy $CUPOLA |
| Chart | Open chart |
| X | Follow |
Fees
| Fee | Rate |
|---|---|
| Minimum deposit | 10 USDC |
| Deposit | None |
| Management | 1.5% a year |
| Withdrawal | 0.3% |
FAQ
Why a cupola?
The Capitol has one, and a cupola has a hundred coffers if you count right.
Why does a sale only release one member's lot?
Each member's purchase is their own signal. When they file the sale, their signal is over. Another member still holding is still a signal.
Where is the data from?
disclosures-clerk.house.gov for the filings, Jupiter for the tokenized shares and quotes. Every row links to its PDF.
Can the reader be wrong?
It reads text, not images. A row it cannot read is not bought. Each line shows the Filing ID so it can be checked against the signed PDF.