fill.cost
- Version
- 0.2.1
- Desk
- Terms named on this page
What a swap cost the trader, measured from the chain against public rules: against the pool it traded in, in the router's cut and in gas. And, once a week, the public routers compared by that cost, with the number of swaps behind each figure.
Changelog
| Version | Date | Change |
|---|---|---|
0.2.1 | 2026-11-20 | A transaction's gas is shared among every swap event of its receipt, of any pool, not among the swaps of pools on file alone. Before, check_fill and a wallet's report gave a swap of a route through pools not on file too large a share of its transaction's gas. The weekly ranking samples one-swap transactions only, so none of its figures changes. |
0.2.0 | 2026-11-20 | The router's cut is measured only when the receipt holds no swap event of any pool other than the swap's own, and the input sent back to the trader is netted from what the trader paid. Version 0.1.0 counted only the swaps of pools on file, so a trade split across pools read all of the trader's input as a cut of the one leg measured: 577 of the 620 router fees above zero in production's week to 2026-11-18. The ranking of that week is corrected by its revision 2. |
0.1.0 | 2026-11-19 | First version: the cost against the pool (fee and price impact), the router's cut, gas, the all-in cost, the reference gap against the stock's Chainlink price, the sandwich pattern, the check of one transaction ( check_fill), a wallet's report and the weekly router ranking. |
What it measures
A swap's cost to the trader is how much worse its price was than the pool's price just before it, plus what a router kept on the way, plus the gas. This method measures each of those from the swap's own events and transaction, so anyone can measure them again from the chain.
It does not measure why anyone traded, whether a price was fair, or what a trade would have cost elsewhere. It names no trader's intent. It measures Uniswap v3 and v4 pools of issuer-listed stock tokens with a USDG or WETH side only: the venues Stock Tokens also trade on outside Uniswap, RFQ desks, proprietary market makers and order books, are out of scope.
Inputs
- Every Swap event of the pools in the window, read as
tape.pool-checkreads them (the same events, topics and direction of amounts), in chain order. The price a pool's swap left is in its event (sqrtPriceX96), so the price just before a swap is the one the pool's previous swap left: no read of old state is needed. A pool's first swap of a window takes the price its last swap before the window left, read from up to 2,000 blocks back; with none there, the swap is not measured. - The transactions sent to each router compared, from the explorer's list (
module=account&action=txlist), whole UTC day by whole UTC day. The transaction's sender is the trader. - The receipt of each transaction with a router swap (
eth_getTransactionReceipt): its token transfers and its gas. - The fee each swap paid the pool: a v3 pool's fee tier; on v4, the fee in the swap's own event, which a hook can set swap by swap. Measured on 2026-11-18: two v4 pools charged 3,499 and 125 parts per million where their pool rows say 3,000 and 100.
- The ETH price, in USDG, from the Uniswap v3 WETH/USDG pool with the 0.01% fee tier,
0x52e65b17fb6e5ba00ed806f37afcd2daa50271ca, the one the factory'sgetPool(WETH, USDG, 100)names: the price its last swap before a place left. For a day, that place is the day's middle block; for one transaction, the transaction itself. The pool trades every few blocks, weekends included: measured on 2026-11-19, it swapped 244, 445 and 355 times in three windows of 2,000 blocks, where a stock token's own pools went up to 14,589 blocks without a swap.
Figures, for one swap
All in parts per million of the swap's notional, the amount of its quote asset (USDG or WETH) that went in or came out. A basis point is 100 parts per million.
- Cost against the pool. The price is token1 per token0, (
sqrtPriceX96/ 2^96)^2. A trader who paid token1 for token0 paidamount1 / amount0; the cost is that over the price before, less one. A trader who sold token0 gotamount1 / amount0; the cost is one less that over the price before. Above zero is a cost to the trader. Rounded toward zero. - Pool fee and price impact. The fee is what the pool charged; price impact is the cost against the pool less the fee: what the trade's own size moved the price.
- Router fee. What the trader paid in beyond what reached the pool, plus what left the pool beyond what reached the trader, each in the swap's own tokens, from the receipt's transfers. What the trader paid in is net of the input token sent back to the trader in the same transaction: a router told to spend at most some amount takes it and returns what the pool did not use, and that return is not a cut. It is measured only when the receipt shows the trader paying the swap's input token in a transaction with one swap, counting every swap event in the receipt (a Uniswap v2 or v3 swap of any pool, a v4 swap of the PoolManager), whether its pool is measured or not. A swap paid in ETH, the middle leg of a route through other pools, or one of several swaps in a transaction has no such transfer to read: its router fee is not measured, never zero.
- Gas.
gasUsedtimeseffectiveGasPricefrom the receipt (on this chaingasUsedincludes the L1 part), shared equally among the transaction's swaps, as a share of the notional at the day's ETH price. - All-in cost. The cost against the pool, plus the router fee, plus the gas, for a swap whose three are all measured.
The reference gap
The swap's price in US dollars a token against its stock's Chainlink price at the swap's time, times the shares of the stock one token stands for, in parts per million: a buy above the reference, or a sale below it, is a cost to the trader. It is reported apart from the all-in cost, never added to it.
- When it is measured. For a stock token that Master lists as
Issuer-listed, with a Chainlink feed on file, while its market state wasOpenat the swap's time, decided by Master's own rule (master.market-state) with the swap's time in place of now and the round current then. Otherwise the field says reference closed, with the reason: not an issuer-listed token, no feed, or the market state at the swap's time (on a weekend: "The 24/5 session schedule is not running: the weekend."). The oracle's pause flag is a state of the token's contract now, not at the swap's time, so the rule is decided without it. - The round current at the swap's time is the feed's latest round updated at or before it. For a whole UTC day the batch lane has recorded (
pnpm batch fill:rounds, run each morning), it is found among that day's rounds: the round current when the day began, then every round updated during it, read withgetRoundDataand kept as one row a feed and day. For any other day, it is read at the head withlatestRoundData()and, when that round is later,getRoundData(uint80): back from the latest 1, 2, 4, ... rounds, then between the two rounds that bracket the time, until they are neighbours. A feed keeps its rounds, so no archive read is needed. One transaction's check makes at most 4 such reads a feed and the batch lane 8; past that, or before the feed's current phase, the gap is not measured, and the field says so. - The swap's price is its quote amount over its stock amount: USDG as dollars, WETH at the ETH price just before the transaction. The reference is the round's answer, at the feed's decimals, times the shares per token on file now; a change of the shares per token between the swap and the check is not taken into account.
- Its evidence is the swap's own event and the round's
getRoundDatacall at the block it was read at.
The sandwich pattern
A swap is flagged when, in the same pool, one other trader swapped the same way just before it and the other way just after it, within the same block or the next two. The flag reports a pattern of public trades. It says nothing of anyone's intent.
How this chain orders transactions limits what the flag can find. Measured on 2026-11-18, over one hour of every stock-token pool (17,032 swaps in 16,667 transactions): the pattern matched 1 swap. The count is reported as measured, zero included.
One transaction (check_fill)
GET /v1/ and the MCP tool check_fill measure one transaction's swaps with the figures above, while the caller waits. They read:
- The transaction's receipt: its swap events, its transfers, its sender and target, and its gas. The trader is the sender, or, for a transaction sent to an ERC-4337 entry point, the smart account of the user operation that made the swap.
- The chain's head and the block's time.
- The swap events of each pool the transaction swapped in, from 200 blocks before it to two blocks after it, in one request with the ETH price pool. A pool that made no swap in those 200 blocks is read further back, 2,000 blocks at a time, up to 4,200 blocks; with no swap there, its swap's cost against the pool is not measured, and the answer says so.
- The ETH price: for a whole UTC day the batch lane has recorded, the day's price, as the ranking takes it (the WETH/USDG pool's last swap before the day's middle block); for any other day, the price just before the transaction, from the same pool, read in the same request as the pools. The answer says which (
ethPrice.of). - For the sandwich pattern, only when the pool's swaps just before and just after one of the transaction's go the two ways of the pattern within two blocks: those two transactions, to name their traders.
At most 3 swaps of a transaction are measured, in log order; the others are counted. A swap in a pool that is not a stock-token pool on file is counted and not measured.
The sandwich check waits until 32 blocks after the transaction are on the chain, about three seconds: the spec's two blocks and a margin for a log endpoint a little behind the head. Until then the answer says the check waits. An answer whose log endpoint had not reached the transaction's block measures nothing against the pool and says so. Neither answer is kept by any cache; an answer whose blocks after it were on the chain does not change, and is.
Each figure of the answer names the events it rests on: the swap's own event and the pool's previous one for its costs; every swap of the pool in the two blocks on each side, with the two legs when flagged, for the sandwich check; the ETH price pool's last swap before the transaction for the ETH price.
A wallet's report
GET /v1/ and check_fill with a wallet give the newest report on file for the wallet. A report is computed in the batch lane (pnpm batch fill:wallet --address <wallet>), and every report on file stays: a correction is the next revision.
- The wallet's transactions: the newest 10,000 it sent, from the explorer's list (
module=account&action=txlist, newest first), the successful ones of the last 30 days. The wallet is the transaction's sender: a smart account's swaps, which an ERC-4337 entry point runs in a bundler's transaction, are not on the list of what it sent, so they are not in its report. When the list reaches its 10,000 rows inside the 30 days, the report says so. - Each transaction's receipt, newest first, until 200 swaps in stock-token pools are kept or the 30 days end. Each swap is measured as one transaction's check measures it (the section above), with two differences of the batch lane: a pool's previous swap is looked for up to 60,200 blocks back, and every swap of a transaction is measured.
- The summary: the swaps kept, the swaps whose three costs were all measured, and over those the median and the 90th percentile of the all-in cost; the same by router (the reviewed routers by name, every other target together as "Other targets") and by token class (the stock token's issuer, "Robinhood stock token" or "Ondo stock token", or "Not on file"); and the count of the sandwich pattern. A median is given for any number of swaps, with the number beside it.
- Every swap behind the summary is in the report, with its transaction and log index, so each one can be measured again (
packages/fill/recompute.ts). The upload is refused unless its summary is the one its swaps give.
The weekly router ranking
The routers compared, each named from a source anyone can read:
| Router | Address | Name from |
|---|---|---|
Uniswap SwapRouter02 | 0xcaf681a66d020601342297493863e78c959e5cb2 | verified on the explorer as SwapRouter02 |
Uniswap Universal Router | 0x8876789976decbfcbbbe364623c63652db8c0904 | Uniswap's address book for chain 4663 |
Uniswap Universal Router 2.1.2 | 0x204faca1764b154221e35c0d20abb3c525710498 | Uniswap's address book for chain 4663 |
How they are compared. Every swap of the week's whole UTC days in a stock-token pool, sent through one of these routers, is measured; none is sampled out. For each router: the median and the 90th percentile of the all-in cost, the medians of each part, and the number of swaps whose all-in cost is known. The rows are in order of median all-in cost, lowest first. A router with fewer than 100 measured swaps is listed as "not enough data" and is not ranked. Each size bucket (under 100 dollars, 100 to 1,000, 1,000 to 10,000, 10,000 and over, at the day's ETH price for a WETH notional) gives its own count, and a median only with 100 swaps in it. The table uses no word such as "best" or "worst".
Agent Flow
With each ranking, for each router: its swaps measured in the ranking's days and their volume in whole dollars (USDG as dollars, WETH at the day's price), and the part whose transaction was sent by a wallet that an ERC-8004 identity on file names as its agent wallet (getAgentWallet, as Register reads it). The sender comes from the explorer's list of the router's transactions kept with each day. The number of agent wallets on file is given with it. Each identity whose agent wallet sent such swaps also gets its own row, the routers with their count and volume, shown on its agent page. Known agent platforms are counted once a platform's contracts are on a reviewed list with sources; none is yet. A wallet that is an agent's but is not named by an identity is not counted, and a share is of the measured swaps only.
What the ranking does not cover
- Most swaps on these pools are sent to contracts nobody has named. In one hour of every pool on 2026-11-18, the public routers above took about 2.4% of the transactions; the two largest targets, 21.8% and 19.1%, were a contract that is not verified and a verified proxy over an implementation that is not. Such contracts trade their own balance, so a router's cut does not apply to them, and they are not ranked.
- A router's costs follow the pools and the sizes its users chose. Most of the all-in cost is the pool's own fee and price impact, so two routers whose users trade in different pools differ by that mix. The router fee is the part a router adds; on 2026-11-17 its median was zero for all three.
- The reference gap is not in the ranking. The ranking compares what the routers' trades cost against the pools and in fees; the gap against the stock's own price is reported per swap.
- Only Uniswap v3 and v4, and only pools with a USDG or WETH side.
Checking a figure
Each measured swap of a week is kept, with its transaction and log index, on the machine that runs the batch. Any one can be measured again from the chain alone:
pnpm tool packages/fill/recompute.ts --tx <hash> --rpc <endpoint> --log-rpc <endpoint serving old logs>
It reads the transaction, its receipt and each pool's previous swap again, with the same code, and prints every figure; given a kept swap (--swap), it says match or mismatch for each. A v4 pool's two tokens are given with --token0 and --token1.