TL;DR: I built a free tool that audits your Polymarket trading bot's actual on-chain P&L vs what your bot's database thinks it earned. My own bot recorded +$34 profit while the chain said -$90. The gap is fill slippage your bot is probably hiding from you.
pip install pnl-truthteller. Open source, MIT, takes a wallet address, returns a report.
The lie my bot was telling me
I run a Polymarket crash-recovery bot. It logs every trade to SQLite. Every "close position" event writes realized_pnl to a row. Add up the column → bot says +$34.31 profit across 320 trades.
Looked at the wallet on Polygonscan. The chain says -$90.72.
That's a $125 gap on $80 of capital. Not a rounding error. Not a fee miscount. Hidden slippage — the difference between the price the bot thought it filled at when it called post_order(), and the actual fill once the CLOB matched, partially-filled, swept dust, and updated the book.
Most Polymarket bots write their P&L the moment post_order returns OK, not when fills settle. Over 320 trades that delusion compounds.
What I built
pnl-truthteller is a Python CLI that reads any Polymarket wallet's actual fills from the CLOB API, groups them by token + direction, and tells you the real P&L. Three input modes:
# Mode 1: just give it a wallet address (zero setup)
pnl-truthteller --wallet 0xYourPolymarketProxy --output report.md
# Mode 2: feed it your bot's SQLite (if you log raw_response)
pnl-truthteller --sqlite ~/bot/trades.db --output report.md
# Mode 3: JSONL (custom integrations)
pnl-truthteller --trades trades.jsonl --fills fills.jsonl --output report.md
The output is a markdown report you can paste into your trading journal: per-token P&L, fill count, average slippage per side, how much you paid in dust+spread.
The pattern generalizes
I tested this on a random Polymarket trader's wallet (0x1417..., pulled from the public CLOB feed). Same pattern:
| Source | Trades | DB-equivalent P&L | On-chain P&L | Hidden slippage |
|---|---|---|---|---|
| My bot | 320 | $+34.31 | $-90.72 | $-125.03 |
| Random stranger | 65 | $+32.36 | $-30.29 | $-62.66 |
Both samples are in the examples/ folder of the repo.
The pattern is consistent. If you trade Polymarket programmatically and your bot writes P&L from order placement (not from settled fills), your books are likely off by 5-15% on the loss side.
Why most bots have this bug
The CLOB matching engine fills in stages:
- Your bot calls
post_order(token, size, price) - Polymarket returns a JSON like
success: true, orderID: 0x..., status: matched, makingAmount: ... - Your bot writes the order as filled at the requested price
- But — the actual fill happened across multiple matched takers at slightly worse prices, sometimes with FOK rejections requiring re-submission, sometimes with dust ladders that eat 1-3 cents per side
The makingAmount in the response is what you actually filled, not what you requested. If your bot stores price from the request rather than makingAmount / takingAmount from the response, your DB is silently wrong.
pnl-truthteller reads the on-chain truth and shows you exactly where the gap is.
Install
pip install pnl-truthteller
Repo | PyPI | MIT licensed | Read-only (your wallet address is the only input)
253 downloads in the last 30 days. Found by quants searching pypi for "polymarket slippage." If you trade prediction markets, this might already be in your dep tree before you know about it.
What if you want more than the audit?
The audit tells you what went wrong. Two follow-ups that might help:
Build better backtests against the real market — I sell the historical Polymarket dataset I use for my own bot research: 10.8M+ price snapshots across 13,963 markets, 15-min frequency, orderbook depth, 43+ days of data. $9 on Gumroad. Same data behind every example in this repo.
Look at a working crash-recovery bot template — the 280-trade, 80% win-rate bot I wrote about in an earlier post is now a buyable template. Includes the SQLite schema, the CLOB executor, and the post-trade reconciliation logic that surfaced the $125 gap above. $39 on Gumroad.
Or just use the free tool and learn from your own data. That's why it's MIT.
Contributing
GitHub Discussions are now enabled on the repo. If you've audited a Polymarket wallet and want to share what you found (anonymized), open a discussion. I'd like to compile a public "common slippage patterns" registry over time.
Issues + PRs welcome.
If you found this useful, the easiest signal is a star on the GitHub repo. It helps the next quant searching pypi find it.
Top comments (0)