tsx:
What you will build
1. The data
A wallet’s league record counts every settled market it traded in that league, at any size. A win is a market where its realized P&L closed positive, not a market where it backed the winner.
2. Write the rule
The rule takes 2 sides and returns 1 of them, ornull to pass. It knows nothing about where the money figures come from, so the live run and the backtest share it.
rule.ts
3. Run it on today’s games
today.ts reads the games that start in the next 24 hours. For each moneyline, it adds up the money of S- and A-grade holders whose league record passes the rule, reads the ask, and asks the rule.
today.ts
maxPrice, so the rule passed on that game.
min_grade: "A" keeps S- and A-grade holders. paginate follows next_cursor, so a market with more than 100 holders is read in full.
The holder list is rebuilt at most once a minute per market. A market nobody has asked for recently can answer 429 with cold_read_limited. The client waits for Retry-After and tries again, up to 2 times.
To read one wallet’s record in every league, call Trader category records:
4. Backtest it on settled games
The holder list shows positions as they are now, not as they were before a past game. A backtest oftoday.ts on old games would read today’s holders, so it would use information from after each game.
as_of=kickoff on Market holders and Game holders returns a game moneyline’s holders as they were stored before kickoff: each wallet’s side, grade, and category_win_record as they stood then. as_of.population_fetched_at says when those positions were read. If that is after your decision time, the roster holds positions your rule could not have seen, so compare the two before you use it.
Rosters exist only for games that kicked off after this shipped on November 16, 2026. An older game, or one nobody read before kickoff, answers 404 with kickoff_roster_not_captured. A game that has not started, or started less than 30 seconds ago, answers kickoff_roster_pending, with Retry-After set to 30 seconds after kickoff. Neither answer falls back to today’s holders.
backtest.ts gives the same rule the input it can replay on every settled game: large trades placed before your decision time, by wallets that held an A grade or better when they traded. It cannot apply the league record filter, because those records are also counted as they stand now. On a game with a kickoff roster, read the record from the roster instead.
For each settled game, the script:
- Adds up the large-trade money on each side before the decision time, 90 minutes before kickoff.
- Takes the price of the first taker buy of the leading side after the decision time as your entry.
- Asks the rule, with that entry as the price.
- Reads the settlement and the fee curve from the game’s moneyline.
- Reads the closing line of every pick.
backtest.ts
The fee and the entry price
Polymarket charges the taker a fee on each share:rate * (p * (1 - p)) ^ exponent, where p is the price. See Polymarket’s fee page.
expand=trading_terms returns rate and exponent in fee_schedule. On NBA moneylines on November 11, 2026, they were 0.05 and 1, so a share at 0.59 paid about 1.2 cents.
The entry is a recorded taker fill, so it already paid whatever the order book asked at the time. Your own order could fill at a different price, and a large order moves the price. The closing line is Polymarket’s price series at kickoff, not a fill.
List market trades serves fills from coverage.recorded_from, which was 2026-11-01T18:00:00Z on November 11, 2026. Read it from the response and set FROM no earlier. trader.grade_at_trade exists from 2026-09-19T23:00Z; an older trade never matches min_grade_at_trade.
The first read of an old game’s moneyline can answer settlement.status: "unavailable" while 0xinsider fetches it. moneylineRow reads once more after 5 seconds. A game it still cannot read is skipped and counted, not scored as a loss.
5. Compare it with the published record
benchmark.ts reads the Pick of the Day archive for the same days and league. unit_score is a pick’s return on 1 unit: a win at a price of 0.40 is 1.5, and a loss is -1.
benchmark.ts
6. Before you trust a result
- Sample size. 6 picks is not evidence. If every pick were a coin flip at even money, 4 or more wins in 6 would still happen about 1 time in 3. Widen
FROMand run more leagues before you believe a return. - Days, not picks. In the run above, 3 of the 6 picks were on one day. Games on the same day share news, injuries, and market mood, so count the days with a pick as well as the picks.
- Entry against close. “Average close minus entry” was -1.83 cents, so the run paid more than the closing price on average. Its return came from 4 wins in 6, not from buying cheaper than the market’s final price. A positive figure over many picks is harder to get by luck.
- The fee. Compare the 2 return lines. A rule that is profitable only before the fee loses money in practice.
- Lookahead. Use only data that existed at decision time:
min_grade_at_trade, notmin_grade, and a decision time before kickoff.trader.gradeon a past trade is the wallet’s grade today. Past holders come fromas_of=kickoffonly, and only whenas_of.population_fetched_atis before your decision time. - Skipped games. Read the
skippedcounts. A rule that skips most games has a small sample, even across a long window.
Next steps
- Run the rule when trades happen instead of on a schedule, with the
large_trade_inserted_v2andmarket_settledwebhooks. See Webhooks. - See how an order is placed and capped on a Polymarket account in Auto-buy the Pick of the Day. That tool buys the published picks, not your rule’s.
- Read a wallet’s grade at a past decision time with Trader grade at a past time.
- Build a list of wallets to follow with Copy-trade signals.
Limits
- A past record does not guarantee a future result.
- The backtest replays large trades, not the holder list, so it tests a thinner version of the live input.
- Large trades history is a best-effort record:
meta.completeness.statusisbest_effort, and a gap does not prove that nobody traded. - The API does not place, cancel, or read orders.