Pool routing eligibility

Not every Uniswap V3 pool on MegaETH is routable through the Kumbaya frontend. The swap UI quotes against an admission-filtered set of pools served by GET /api/v1/pools/admitted. A pool that exists on-chain - even one with healthy liquidity - will not be routed unless it clears every stage below.

This page documents what makes a pool routable, and by extension what makes a token tradeable in the Kumbaya UI. If you are integrating directly with the contracts (QuoterV2, SwapRouter02), none of this applies - these rules are a property of the hosted routing layer, not the protocol.

The three stages

A pool must pass all three to appear in /api/v1/pools/admitted and be quoted by the frontend.

1. Indexer candidate fetch

The Exchange API builds its routable universe from the Hasura indexer, not from chain scans. To enter that universe a pool must satisfy:

Requirement	Detail
Indexed	The pool must exist in the indexer. If the indexer has not seen the pool's creation event, it is invisible to routing.
TVL or liquidity	totalValueLockedETH greater than the tracked threshold (0.01 ETH by default), or a pool with non-zero liquidity whose TVL has not yet been computed. Pools below the threshold are treated as dust and dropped.
Not a pre-graduation fire pool	Fire (bonding-curve) pools are excluded until the token graduates - see below.
Top 2000 by TVL	The candidate set is capped at the 2000 highest-TVL pools per chain.

Most common reason a pool is missing: its TVL sits below the 0.01 ETH tracked threshold. Small or freshly seeded pools - common on testnet - fall out here before any other rule is evaluated.

2. Initialized state

The pool must be initialized - it must have a current tick and a non-zero sqrtPriceX96. A pool that was created but never received its first mint / initialize call is skipped.

3. Admission filter (6 rules)

Surviving pools are run through a 6-rule filter. The pool is admitted if any one rule matches. "Trusted" means a token that is verified or bluechip in the Kumbaya token registry, or a graduated fire token.

Rule	A pool is admitted when…
1	It is a Kumbaya fire pool whose token has graduated.
2–4	Both sides of the pool are trusted (verified × verified, verified × fire, fire × fire).
5	One side is the token being swapped and the other side is trusted (e.g. YOUR_TOKEN / WETH).
6	It is the direct pool for the exact pair the user is swapping.

Rules 5 and 6 depend on the swap context, so /api/v1/pools/admitted accepts optional tokenIn / tokenOut query params. Omit them and only rules 1–4 can match - a brand-new token paired against WETH will not show up unless you pass its address.

What this means for a token to be tradeable

A token is tradeable in the Kumbaya UI when it is one side of at least one admitted pool. In practice that means one of:

• The token is verified or bluechip in the registry - it routes against any other trusted token automatically (rules 2–4).

• The token has a direct pool against a trusted token (typically WETH) that is indexed, above the TVL threshold, and initialized - it routes via rule 5 once its address is passed as tokenIn / tokenOut.

• The token is a graduated fire token (rule 1).

A token with only an unverified-to-unverified pool, or only sub-threshold liquidity, is not tradeable through the hosted router even though the underlying contracts would happily execute the swap.

Fire (bonding-curve) pools

Pre-graduation fire pools are deliberately excluded from the cached candidate set for scale. They are added back per request only when the pre-graduation fire token is the user's tokenIn or tokenOut, so a token still on its bonding curve can be traded directly but will not appear as an intermediate hop. After graduation the pool joins the normal candidate set (rule 1).

Candidate trimming

Admission is necessary but not the last word. Before route search runs, the admitted set is trimmed to a bounded number of candidates ranked by TVL (top-N direct pools, top-N token-to-base pools, etc.). On a pair with many pools, a low-TVL admitted pool can still be left out of the final route search. This is a performance bound, not an eligibility rule.

Debugging a missing pool

If a pool you expect is not being routed, check in order:

1. Is it in the indexer? Query the Hasura indexer for the pool by address. No row → routing cannot see it.

2. Is its totalValueLockedETH above 0.01? If not, it was dropped at stage 1.

3. Is tick / sqrtPrice populated? Null tick → never initialized, dropped at stage 2.

4. Are you passing tokenIn / tokenOut? Without them, rules 5 and 6 cannot fire.

5. Are the tokens trusted? If neither side is verified / bluechip and you are not passing the swap context, no rule matches.

For raw request/response shapes, see Pools endpoints and the Swagger UI at exchange.kumbaya.xyz/docs.