How Ilyris works, and the addresses to verify it against. Every address, bin step and fee below can be read on-chain, and where this page and the chain disagree, the chain is right.
Start with bins and fees for how a pool works, contracts for the addresses, integrators for routing, and audits for what has and has not been reviewed.
Liquidity sits in discrete price steps rather than along a continuous curve. Each bin holds reserves at one fixed price, so a trade that stays inside a bin has zero price impact — the price does not move because there is no curve to move along. Price only changes when a trade exhausts a bin and crosses into the next.
Bin n sits at price = (1 + binStep/10000)^n. Bin step is
chosen per pool, not by the protocol: WETH/USDG has a 1 bp pool (each step
0.01%; /app opens it) and a 10 bps one (each step 0.10%), and WETH/YRIS uses
250 bps (each step 2.50%). Discover shows each pool's.
The base token sits at and above the active bin, the quote token at and below —
and which token is which is decided by address order, not by what you would
call the pair.
The swap fee is charged once on the way in, before any bin is touched:
netIn = amountIn × (1e9 − rate) / 1e9. Charging per bin would compound it
across a multi-bin trade. The fee is per pool: WETH/USDG charges
1 bp (0.01%), WETH/YRIS 100 bps (1%). Discover lists each pool's base
fee, read live. The rate a swap actually pays can be higher than the base — a
volatility surcharge is added on top after recent price movement. The total is capped
at 10%; with the settings in place in October 2026 it can reach 1.51% on WETH/USDG and
6% on WETH/YRIS. The pool owner can change a pool's fee settings at any time, with no
timelock, so read swapFeeBps() and getTotalFeeRate() on the
pool.
A deposit that arrives imbalanced relative to the bin it lands in also pays a composition fee, on the imbalance only. Without it, depositing one-sided into a bin and immediately withdrawing would be a free swap at the bin price, paid for by the LPs already there.
Fees accrue per position through a share accumulator and are claimed separately, so claiming never touches principal. The protocol's share (10% of each fee as of October 2026; the owner can raise it to at most 50%) is skimmed before anything reaches LPs and is held outside bin reserves — the two can never draw on each other.
The guard is an operator switch, not a market-hours clock. It can pause swaps,
pause new deposits, and run corporate-action freezes of up to 24 hours each; of the
live pools, only WETH/USDG has one. The installed guard makes no external calls:
its decision is public state (swapsPaused(), frozen()), not an
oracle nobody can see. The pool owner can replace a pool's guard at any time, so read
the pool's marketGuard() first.
It cannot block a withdrawal. That is structural, not policy: the guard is not consulted on the removal path at all, and the pool owner has no function that can stop liquidity leaving. Two things outside the guard can: a withdrawal pays out both tokens, so one that pays a token its issuer has paused (USDG has a pause role) reverts until the pause is lifted; and a pool created with a transfer policy can gate removals, which none of the pools listed here has.
⚠ Integrators: quoteExactIn and quoteExactOut do
not consult the guard — only the swap functions do. A simulator built from
quotes alone will happily price a swap that reverts. Read the pool's
marketGuard(), then swapsPaused() and frozen() on
that guard; freezeEnd() alone also reports a freeze that has not started.
Switching pools. The pair name at the top left is a menu of every pool you can trade, including the superseded factory's. Deprecated pools are tagged; the two empty WETH/YRIS pools created at an inverted price are not offered at all.
Which way the price runs. A pool stores one price — quote token per base token — and the factory picks which is which by address order, so on some pairs the native number reads backwards. The ⇄ control beside the range, the position book and the liquidity chart flips the display; it is a labelling change only, remembered per pool. Ranges are measured in bins, so flipping cannot alter which bins a deposit touches. Bar colour always names a token and never moves; bid/ask follows the direction you are reading.
Creating a pool. Get the starting price right. Only a swap moves
activeId, so a pool created at the wrong price stays wrong until someone
places liquidity at the correct price and trades into it, and anything resting near the
wrong price is sold at that price first. The factory key is (tokenX, tokenY, bin step,
policy, guard), so that exact combination stays taken for good. The create form
therefore states the price as a sentence with no units to misread —
"1 WETH = 24,038,448 YRIS" — and will not submit until you confirm it.
Reading your PnL. The figure is your profit or loss, in US dollars or in ETH — pick with the switch beside it. It is what you hold now and the fees still owed to you, at today's pool price, plus everything you have withdrawn and every fee you have claimed, less everything you deposited — each deposit, withdrawal and claim valued at this pool's own price when it happened, read from the pool's trade history. Deposits made before a pool's first trade are valued at the price the pool was created with, read from its creation transaction. The percentage is against the most you have had in the pool at any one time. When the pool last traded more than a day ago, a line under the figure says so: the figure rests on that price.
USD and ETH. On WETH/USDG both are exact: USD counts USDG as $1 and ETH counts WETH as ETH, so switching values every deposit and withdrawal in the other unit, and a result can be a gain in one and a loss in the other. On a pool with no dollar token, such as WETH/YRIS, the figure is worked out in ETH, and its dollar view is that figure at today's ETH price, read from the WETH/USDG pool and marked ≈: it moves with ETH's price and never changes sign. A pool with neither WETH nor a dollar token is counted in its own two tokens.
When a figure is withheld. If your deposit and withdrawal history does not match your position on chain bin for bin — usually a transaction that confirmed moments ago — the figure shows a dash and is re-checked automatically. If the pool's trade history, or the price it was created with, cannot be read, the figure shows a dash and the read is tried again automatically a couple of times; after that, reloading the page reads it again. On a pool that has traded too often for its whole trade history to be read here, the figure stays a dash. It also stays a dash when you deposited before a pool's first trade and the price the pool was created with cannot be found — on a pool from the superseded factory, or one created through a contract wallet. Known gaps: a zap deposit is valued at the price after its own swap, and that swap's fee and price impact are not counted; fees still owed in a bin you have emptied are left out.
Swap, on every page. Swap in the top bar (on a phone, the Swap tab at the bottom
of the screen) opens KyberSwap's swap widget on the page you are on. It quotes and
routes across all of KyberSwap's liquidity on Robinhood
Chain, the Ilyris pools included, so it also trades tokens Ilyris has no pool for.
Ilyris adds no fee to it: you pay only what the pools on the route charge. Approvals it
asks for are for KyberSwap's router,
0x6131B5fae19EA4f9D964eAc0408E4408b66337b5, and the page passes your wallet
nothing else: a swap through that router that pays out to your connected account, an
approval naming it, or WETH's own wrap and unwrap. Its token list includes the Robinhood
stock tokens that KyberSwap could buy, and sell back, for small amounts at a round-trip
loss under 3% (most under 1%) when the list was made. Before it swaps into or out of a
tokenized stock, or approves one, it asks you to confirm that you are not a US person or
resident (Terms, section 5), once per token in each browser (each visit, if the browser
blocks site storage); cancelling sends nothing to your wallet. It asks as you pick a
stock from its list, so the question never sits between a quote and your wallet. A stock
it only recognises when you press Swap or Approve — one pasted in by address, say — is
held back there: nothing is sent, and you press it again once you have confirmed, for a
fresh quote. It knows a tokenized stock by lists of Robinhood's own and of those bridged
onto the chain, by a name that says so, or by what the token reports on chain; one that
is not Robinhood's own, another issuer's or a copy, is flagged as such. Tokens that
merely share a stock's ticker are not asked about, since they are not stocks; copies
that use a listed stock's exact ticker are left out of the list. A swap between two
other tokens can still be routed through a pool that holds one, inside the same
transaction, without you ever holding it, and that is not asked about. Stock amounts are
in on-chain token units, which can differ from the share count Robinhood shows: by under
1% for the listed stocks in October 2026, though for a fund that pays out by raising
that multiplier, such as SGOV, the gap grows each month. The widget defaults to an
unlimited approval ("Infinite Allowance"); pick "Exact Allowance" under the Approve
button to approve only the amount being swapped.
Only trust addresses listed here or verified on Blockscout. An address in a message, a reply or a search result is not an Ilyris contract because it says so.
The tables below are drawn from the deployment manifest this site is built with, the same file the app reads its addresses from, so they cannot drift from what the app uses. Verify each on Blockscout. Discover lists the factory's pools, read live from the chain. The two empty WETH/YRIS pools created at an inverted price are left out on purpose; superseded pools are listed and tagged deprecated.
A test network. Its tokens are mocks with no value.
Live, and not part of the deployment manifest: WETH/YRIS was created through the factory after deployment. Every other pool created on the factory, such as WETH/SI, is listed on Discover, apart from the two empty inverted WETH/YRIS pools noted above.
These are listed so an LP with funds in one can find it, not because anything should be deposited into them. The factory was replaced; its pools remain withdrawable and are tagged deprecated in Discover.
Ilyris runs on Robinhood Chain. These are the settings the site itself uses to talk to the chain. Reading these docs needs no wallet.
Adding the network asks your wallet to show it a network with the settings above; it connects nothing and sends nothing, and your wallet asks you to approve it first.
BinPoolLens.getPoolState(pool, radius) is one-call discovery:
tokens, decimals, bin step, active bin and its price, the resolved fee rate
(totalFeeRate, 1e9 precision, volatility surcharge already applied) and the
guard address. MAX_SCAN is 512 and the check is
radius * 2 + 1 > MAX_SCAN, so the usable radius is 0–255 and 256 reverts
ScanTooWide().
It does not price a swap, and its reserves are not the pool's reserves.
reserveX/reserveY are summed over
activeId ± radius only; scannedFrom, scannedTo
and populatedBins say what was counted, and liquidity outside that window
is invisible with no error and no flag. Measured on WETH/YRIS on 13 October 2026 (L2
block 87,271,495): at radius = 10 the lens reports 585,037 YRIS,
while a single 0.03 WETH sell pays out 749,664 YRIS and ends 4 bins beyond
scannedFrom; the pool's 121 bins held 34.0M YRIS. The swap's own output is
more than the lens called the reserves. If populatedBins equals the window
width you are clipping, but a smaller count does not prove you are not: a book with
nothing above the active bin fills at most radius + 1 (11 of 21 here). Use
getBins to see where the liquidity actually ends.
Pricing needs the bins. A swap walks bin by bin and spends each bin's own reserve
at that bin's own price, so no formula over an aggregate reproduces it. Two honest
routes: getBins(pool, from, to) returns every populated bin, or
quoteExactInWithGas / quoteExactOutWithGas return the amount
out (for exact-out, the amount in), feeAmount, finalId,
binsCrossed and a gas estimate in one call. getBins caps its
range at MAX_SCAN and reverts ScanTooWide() rather than
truncate silently; the quote functions walk as many bins as the trade needs and revert
InsufficientLiquidity() if the book runs out.
A pool may have no guard. marketGuard is the zero address on
WETH/YRIS, and an eth_call to an address with no code succeeds with
empty return data rather than reverting. Decode that as "no guard installed, so not
pausable right now", not as a failed read — a bare 0x will otherwise reach
your decoder and throw, which
is exactly how it broke ours.
Swap the pool directly. No router is deployed on chain 4663 and the manifest has
no router entry — a deployment fact, not an architectural one.
BinRouter.sol exists in the repo and is deployed on testnet, so do
not carry that address, or the TypeScript SDK's
buildRouterExactInputCall, into a mainnet integration. There is no Permit2,
no permit and no swap callback, so there is no shared allowance target:
approve each pool you trade and call swapExactIn /
swapExactOut on it.
The pool pulls, and only pulls. It takes the input from msg.sender
via transferFrom and never reads its own balance for credit. A V2-style
transfer-then-swap therefore does not work: the pool still pulls the full
amountIn, so the call either reverts for lack of balance or allowance or
charges you a second time. The pre-transfer is not detected. Tokens sent to a
pool are never credited and never recoverable: there is no skim,
sync or rescue path. Settlement is exact-delta on both legs, so
fee-on-transfer tokens revert TransferFailed(). Rebasing tokens are
unsupported: some revert the same way, others pass and then drift from the pool's books
with no way to reconcile. For
exact-output, approve maxAmountIn — only the actual amountIn
is pulled.
Gas hints are a routing input, not a limit. BASE_SWAP_GAS (130,000)
and PER_EXTRA_BIN_GAS (41,500) are readable on the lens and applied by
estimateSwapGas(binsCrossed) — but getPoolState does not
return binsCrossed, so that number comes from
quoteExactInWithGas or your own walk. The figure is execution gas only: it
excludes the 21,000 intrinsic, calldata, cold-account access and the guard's staticcall
(about 8,000 on WETH/USDG). It is a model, not a measurement. Simulated on WETH/USDG on
13 October 2026, a one-bin swap came to about 150,000–163,000 gas in total against a
130,000 hint, and a five-bin swap to about 253,000–262,000 against 296,000: each extra
bin costs about 25,000, not 41,500. The pool's first-ever swap, which crossed five bins
that had never traded, used 372,159. Rank routes with it; never send it as a gas limit.
Call eth_estimateGas.
Most aggregators do not need this: they read the chain directly. KyberSwap routes Ilyris pools that way, built on the section above; 0x and ParaSwap do not route Ilyris yet. This API exists for integrators whose pipeline requires an HTTP quote source rather than a contract call.
Base URL https://ilyris-quote-api.ilyris.workers.dev —
no API key, no auth, CORS open. Chain 4663 only. Unavailable as of 13 October
2026: every data request answers 503 upstream_unavailable because the
RPC behind it is failing. Quote on-chain through the lens until that is fixed.
GET /healthliveness plus the number of routable poolsGET /poolsevery routable pool with its tokens, bin step, fee and guardGET /quotetokenIn, tokenOut, amountIn (wei, decimal string)
A quote returns amountOut, feeAmount,
binsCrossed, gasEstimate, the pool to approve and call (the
first that can fill the trade), and the guard's swapsPaused flag, not its
corporate-action freeze. It is priced from a per-block snapshot of the bins with the
same math as quoteExactInWithGas on the lens — the call our own front end
prices with — and falls back to that call when a trade runs past the snapshot;
pricedFrom and blockNumber say which. It matches the lens to
the wei at the block it reports, and the snapshot can be up to a second old.
Two pools are deliberately excluded from /pools and from routing.
They were created at an inverted starting price and hold nothing; WETH deposited
anywhere near their price is sold for almost nothing on the first trade. Do not route
to them if you find them by enumerating the factory yourself.
Errors say what was wrong with the request. A size the book cannot fill returns
422 insufficient_liquidity rather than a raw revert string — on this lens a
quote reads only the pool, not the guard or any oracle, so depth is the usual reason a
quote fails. An unknown pair returns 404 no_pool; a malformed address
returns 400 naming the field. 503 upstream_unavailable means
our RPC upstream is down, not that your request was wrong; retry later.
Rate: provisioned for 100 req/s per client, and measured well above it — 7,000
consecutive requests at 428 req/s drew zero throttling. A rate limiter exists as a
backstop against abuse, but it is Cloudflare's per-colo limiter rather than a hard
ceiling; when it does trigger you get 429 with a Retry-After
header rather than a silent drop. Ask if you need more and it will be raised.
Latency: about 0.2 s warm, up to ~1 s on a cold edge isolate.
If you get a 403 from a script, check your user-agent. The endpoint sits behind
Cloudflare, whose bot rules reject Python-urllib with error 1010. Go,
node-fetch, axios, python-requests, okhttp and curl all pass — this only
bites Python's standard-library client, and it is not us refusing you.
⚠ A quote is not a guarantee, and the gas figure is not a limit. Quotes do not
consult the market guard but swaps do, so check tradable in the response;
it reflects swapsPaused only, so also read the guard's frozen()
before sending. gasEstimate is execution gas only and is a model: on
WETH/USDG it runs below the total gas of a one- or two-bin swap and above it from three
bins up. Rank routes with it and call eth_estimateGas for a limit.
The contracts are unaudited. An audit is planned once the protocol is feature-complete.
Unaudited. Extensively tested — a full Solidity suite, invariant tests that unwind every position to prove solvency, and wei-exact parity between the contract and the off-chain simulators — but tests are not an audit. Treat every deposit accordingly.
One operator key owns every pool and the market guard. Beyond the fee and guard powers above, it can redirect the protocol's share and hand ownership to another address in a single step, with no timelock. It has no function that touches reserves or positions.
The source is the documentation for anything not covered here: the contracts and this interface are commented to explain why they are built the way they are, not just what they do.
Even once it is audited, an audit is a review of the code at one point in time, not a guarantee. It does not cover:
Until then, treat every deposit as unaudited code holding real funds, and deposit only what you can afford to lose.