The token catalogue: import, probe, screen, allowlist

/admin/dex/token. Until a token is allowlisted here, nothing quotes it. dexAllowlistMode is ALLOWLIST and it is the only value this build honours — the allowlist module implements that behaviour and deliberately does not read the setting, so there is no configuration that widens the gate. A fresh install with every chain green and every provider keyed still serves no swaps until this screen has been used.

Three axes, and a refusal always names which one

A token must clear all three. They are separate columns on purpose: collapsing them means an automated screening downgrade silently overrides an operator's decision, and when a token is blocked you have to be told which of the three did it.

The quote path runs one ladder, and every rung has its own refusal reason:

Screening refusals only apply when dexScreeningEnabled is on, and SCREENING_STALE only fires for an operator who explicitly chose fail-closed.

The columns on the console

The edit form writes curation (status, listing) and presentation (sortOrder, logoUrl, notes).

chainId and address are immutable. Together they are the asset's identity — the unique index, the lookup the quote path performs, and what every dexSwap row already written refers to through this row. Editing either turns a historic swap in USDC into a swap in whatever was typed. A new asset is a new row.

Importing a token list

The source is either an inline tokens array or an https URL. Plain http is refused — a list an attacker can rewrite in transit is an attacker's list — and the document must be a Uniswap-standard { tokens: [...] } or a bare array.

A list carries its own chain id per entry, so importing an Ethereum list into Base yields nothing and says so.

The response counts inserted, updatedExisting, skippedDuplicates, refused and unverified, and repeats the rule in words so nobody reads "imported 180 tokens" as "180 tokens are now tradable".

Decimals are verified against the chain

Where the check runs:

• On import — each candidate's contract is read. A row whose on-chain decimals() disagrees with the list is counted in refused and never inserted. A row the RPC could not answer for is counted in unverified and is inserted, with the reason recorded in metadata.probe.failed, because an unreachable endpoint is your problem rather than the token's.
• On create and on update — whenever the saved row would end up ALLOWLISTED. The check is run against the resulting state, not the diff, so both ways in are covered: allowlisting a row whose decimals were never verified, and editing decimals on a row that is already allowlisted.
• On switching an allowlisted token back on — because "disabled" is exactly where a token sits while its decimals are disputed.

Two carve-outs. The native pseudo-asset has no contract, so its decimals come from the code registry. A row that is not being allowlisted is not probed at all — PENDING and DENYLISTED rows are not quotable, so an unreachable RPC must never stop you parking or blocking a token.

dexTokenProbeTimeoutMs (default 6000) bounds each probe.

The per-token routes

Probe is a diagnostic and is not audited. It refreshes metadata.probe and is explicitly not allowed to change decimals, listing or status — reconciling a disagreement is your decision, made through the edit, where it is audited. It reports an RPC failure rather than refusing, because "your endpoint is down" is one of the answers you asked for.

Screen records a verdict and nothing else. It returns 200 with "nothing is configured" when no screener is set, rather than an error that reads like the token is broken.

Status off is unconditional — the emergency stop must never fail for an RPC reason. Status on, for an allowlisted row, re-runs the decimals probe.

Delete is soft. The row survives so historic swaps still render their assets, and it stops being quotable immediately (the quote path queries without soft-deleted rows, so it answers TOKEN_NOT_LISTED). A token still bound to a pair is refused before the delete rather than left to fail at the foreign key. Delisting is normally DENYLISTED, not a delete.

The native asset

The chain's native token (ETH, BNB, POL, SOL, TRX, TON) is stored as a real row using the aggregator sentinel address:

0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee

Every major aggregator uses it, and storing it verbatim keeps the (chainId, address) unique index meaningful — exactly one native row per chain. The quote path resolves the sentinel by the isNative flag rather than by the address, so an install that seeded its native row under a different sentinel still finds the one row.

directPoolOnly

A token flagged directPoolOnly has no aggregator that will quote it — that is what the flag means. It is quotable only through a pool bound in Direct pools, and while dexDirectPoolsEnabled is off (the default) it is unquotable by anything.

It is refused under its own name, TOKEN_DIRECT_POOL_ONLY, rather than folded into a generic "no route available" — the operator action is "enable direct pools", not "enable the token", and those are different screens.

The nightly re-screen

dexTokenRescreen runs every 24 hours and re-screens dexScreeningSliceSize rows per pass, oldest riskCheckedAt first, so a large catalogue is fully covered within ceil(n / slice) runs. A keyset cursor advances past every row it visited — including ones the provider could not answer for — so a handful of dead contracts cannot sit at the front of the queue and starve everything behind them.

Screening also runs on write — every row an import inserts is screened once, after all the inserts rather than between them, and a screening failure never fails the import.

A first pass, in order