Documents

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.

Bins, and why they exist #

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.

Fees #

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 market guard #

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.

Reading the app #

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.

Contracts #

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.

Robinhood Chain (4663)

Factory · 1 bps WETH/USDG pool: Factory0x3Bf76F2E41Ac7996c822455f4c78fa2026465C4D
Fee staking, rewards in WETH0x868ae20E6c1EA3b6Fdab5042Ea721eB51b237183
WETH · 1 bps WETH/USDG pool: Token X0x0Bd7D308f8E1639FAb988df18A8011f41EAcAD73
USDG · 1 bps WETH/USDG pool: Token Y0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168
1 bps WETH/USDG pool: Market guard0x8ea3bea963bdc6985727e9a95b8fee6d4a923c48
Deployer · Guard owner · 1 bps WETH/USDG pool: Owner · 1 bps WETH/USDG pool: Guard ownerAccount, not a contract0x37849f39B26861D9eF8e4415f016BCD7A921De89

Robinhood Chain testnet (46630), test deployment

A test network. Its tokens are mocks with no value.

Factory0xeF4d8C7fd16C2c4D6479b17D75AB04d68a8B3F29
Pool0xB40B06002a5aAd09258B03F63B68E36BE76cB5fA
Lens0x79e2abebabc8277feebafd74d74490059cc38828
Planner0x12a1a6072d85c59325d645104d8cdb03af9531bd
Market guard0x13DB04841Aa27156B9bFc8c6eebfDa472F673107
Fee staking, rewards in USDG0xa292faa09d42466f714ad7a244919036d5a4626f
YRIS token0x65df60dbef8e4bb8d0230e933e91f92c2123c246
Mock stock token0x44FF6b61Eca8B8118d1771a2061d0BE4fCAc4257
Mock USD token0x893c7b339B0435003874E5B97FbF85Fe89B108ca
Position bond vault0x8bF8cF7d073Eb2a953468cF53Fd61CaDc92d5f4B
Quoter0x53CDC14340Af9Acd37971F438c042Bc5c3468fcc
Test price feed0x9DeDE1187Bc4D06A53a91C79cd07A74C8F2a4C05
Rialto pair adapter0x2d5F9439B24b6453B0D3f3D515a59109461CdEcC
Router0x00938880200e35E8399847e1962c45e78dBfcd76
Mock token faucet0x5Ca0Da05cc010f95B5EeD330eb038E75312fC317
Zap venue registry0x492f5B0bFEA5bAC00221E6711Ab459925B9B1DAa
Deployer · Fee recipient · Test liquidity provider · Pool owner · Test traderAccount, not a contract0x37849f39B26861D9eF8e4415f016BCD7A921De89

Also created through the factory #

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.

Pool — WETH/YRIS · 250 bps bin · 1.00% fee0xcbb584e1c1259047f2fe03ccb34e8e2086c9f8ad

Superseded, still on chain #

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.

Pool — WETH/USDG (deprecated)0x90D0950065C567B9324A08A9AaE8a28890fBab16

Networks #

Ilyris runs on Robinhood Chain. These are the settings the site itself uses to talk to the chain. Reading these docs needs no wallet.

Network nameRobinhood Chain
Chain ID4663
CurrencyETH
RPC URLhttps://rpc.mainnet.chain.robinhood.com

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.

For integrators #

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.

HTTP quoting API #

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 pools
GET /poolsevery routable pool with its tokens, bin step, fee and guard
GET /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.

Audits #

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.

What audits don't cover #

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:

  • contracts or settings changed after the review, including fee and guard settings the pool owner can change at any time with no timelock;
  • the tokens a pool holds: a token whose issuer can pause transfers (USDG has a pause role) can hold up a withdrawal that pays it out;
  • the operator key: whoever holds it keeps the powers described above;
  • market risk: a position is sold along its bins as the price moves through them, and fees do not always cover that;
  • this website, your wallet, and the routers and chain it relies on.

Until then, treat every deposit as unaudited code holding real funds, and deposit only what you can afford to lose.