Aggregators and providers

Swap holds no liquidity. It asks every eligible adapter for a price in parallel, picks the best net result, and hands the user an unsigned transaction. Which adapters you enable decides your chain coverage, your fill quality, and — separately — whether you earn a fee at all.

The console is Admin → Swap → Routing → Providers, at /admin/dex/provider. Rows are seeded from a code registry, so you switch adapters on and off and order them; you cannot create or delete one.

The seven adapters

Every one of these is seeded on, deliberately: a row seeded off is a row an operator cannot switch on, and the failure it produces ("no aggregator is enabled") names nothing you could act on. This enables nothing by itself — the addon master switch and each chain's own switch are still off by default.

Keys live in .env, never in the database. The console reports whether a variable resolves; it never returns the value, and it never will. The exact names, their fallbacks, and the nine names that are read by nothing are in Environment variables.

The three fee modes, and why they are the most consequential difference

feeMode is shown on the Providers screen as Fee side and it is read-only, because it is a property of the vendor's settlement contract rather than something you configure.

Two consequences that catch people out:

• feeSide is written onto every quote and every swap row, and the accrual reader uses it to decide which token to look for. That is why KyberSwap's genuinely configurable fee side is pinned to the sell side in this build: a per-request choice would make the stored column mean "whatever was configured at the time", and a later settings change would silently reinterpret your history.
• A SELL-side fee on a native-coin sell leg has no on-chain Transfer behind it, so those accruals are recorded as ESTIMATED rather than RECEIPT. See Fees and revenue for how the two read on a revenue report.

Your fee itself is one setting — dexFeeBps, Admin → Swap → Settings → Fees → Revenue, labelled Integrator Fee, default 0, maximum 300 (3%). The maximum is the vendors' ceiling, not an arbitrary one: 1inch rejects anything above 300 bps and LI.FI takes the same range.

What each adapter needs before it will pay you

Jupiter — the fee recipient is a token account, per mint

This is the single most likely misconfiguration in the whole addon, and it is not something an address can look wrong for.

On EVM, a fee recipient is an address and the aggregator sends the fee there. On Solana an SPL token can only be held by a token account owned by a wallet, one per mint, and each must be created and rent-funded before anything can arrive. So dexChain.feeRecipient on Solana stores the owner wallet, and the fee account is derived per mint.

Passing a wallet address where Jupiter wants a token account is rejected; passing an account that does not exist is worse, because on some route shapes Jupiter proceeds and simply collects nothing. This build refuses to guess: if the account cannot be proved to exist, the quote is served at zero fee and says so, rather than sending an unverified account. That includes the case where the RPC endpoint is merely unreachable — a transient outage must not turn into revenue that looks collected and is not.

Wallets is the screen that goes and looks, per mint, and tells you which accounts are missing.

LI.FI — a fee is only paid to an enabled integrator

LI.FI pays only integrators it has enabled fee collection for, arranged with LI.FI directly at portal.li.fi. Until that is done it does not quietly under-pay you — it rejects the entire quote, HTTP 400 code 1011, whenever the request carries a fee.

So while your platform fee is above zero and the integrator is unregistered, LI.FI prices nothing on any chain. Because it is the only adapter that reaches Cronos, Rootstock and Celo, those three chains stay listed in your console with no venue able to quote them, and every attempt fails as though no route existed. Register the integrator, or switch those chains off.

Full registration walkthrough: Getting your vendor accounts.

The integrator string is a constant in the build rather than a setting, precisely because it is the key LI.FI ties fee eligibility to: an operator editing it in a form would silently stop their own revenue while every swap kept working. It is sent on every request, fee or no fee, because it is public attribution rather than a credential.

LI.FI is also the only adapter here that prices Cronos, Rootstock and Celo — three chains with no other venue — and the only one that can be asked about a transaction after the fact.

STON.fi prices only — the message is built server-side

STON.fi's /v1/swap/simulate returns a price and no transaction: no payload, no BOC, no cell. Their expectation is that the browser assembles the message with their SDK.

Doing it that way would break the guarantee the rest of this addon rests on. Every quote stores a hash of its calldata and the receipt verifier checks that the transaction which settled is the one that was quoted — if the browser builds the message, the server never sees the bytes it is supposed to be binding. So the server builds the TON swap message, using STON.fi's own SDK: their encoder, our process, and bytes that exist server-side to be hashed and later verified.

Their router has no integrator-fee hook, so TON earns nothing through this venue.

SunSwap is a bare AMM, and earns nothing

SunSwap V2 on TRON is a UniswapV2 fork — verified, not assumed: its router reports its own name as UniswapV2Router02. Prices come from pool reserves read over TronGrid, so it needs no vendor account.

Being a bare V2 router it has no integrator-fee hook at all, exactly like the EVM direct-pool venue and for exactly the same reason: swapExactTokens… has no fee parameter and nowhere to put one. See Why a direct pool earns no swap fee — the argument is identical.

TRON also charges energy, not gas, and a user with staked TRX can pay nothing for a swap. Gas estimates on TRON are deliberately null rather than a converted number that would be wrong for most users.

Three kinds of credential, not two

Whether an adapter names an environment variable does not tell you whether it needs one, which is why the registry records the two facts separately and why the Providers screen's Credential column has three states rather than two.

This distinction is load-bearing. Treating an unset variable as broken made the setup console warn about four "broken" adapters on a fresh install, three of which quoted perfectly — and a console whose out-of-the-box state is four false alarms is one an operator learns to scroll past, and then misses the real one.

The readiness report only counts a missing credential as a problem where the key is authentication, and its warning is precise: "Switched on with no credential in the environment: …. Every quote will fail authentication until the variable is set."

An unkeyed TON install is worth one extra thought: the confirmation poller calls toncenter once per pending swap, so under load a keyless install settles slowly rather than not at all.

Priority does not pick the winner

priority (lower first) does two things and neither is choosing a route:

• It orders the race and breaks ties deterministically, so the same request always races the same order.
• It is only ever compared within a chain. Jupiter at 10 never races 0x at 10, because 0x prices no Solana and Jupiter prices nothing else.

The winner is decided on net output: buy amount, minus the fee where the vendor takes it on the buy side, minus gas converted into buy-token units. The obvious rule — highest quoted output wins — is wrong in the direction that looks right on a dashboard, because a route quoting 0.3% more while costing four times the gas leaves the user with less, consistently.

When gas cannot be converted (either USD price missing on a thin token), the comparison drops to gross and records that it did, on the quote row, rather than pretending gas is free.

The four EVM aggregators added alongside 0x sit at priority 20 for one narrow reason: 0x's buy-side fee is the one this build has a fork test for, so on an exact tie it is the venue whose accrual is already proven. Every other venue wins whenever it actually prices better.

What the console lets you change

The Providers screen edits four things: Status, Priority, Chain scope (supportedChainIds) and an endpoint override (baseUrl).

Chain scope is a narrowing, never a widening — the adapter's own capability list is the outer bound, and an empty scope means "no narrowing", which is why it renders as All chains it supports rather than as a blank cell. The PUT also refuses a chain id this build's registry does not carry, because that would be a provider switched on and silently unreachable.

Four fields are read-only on purpose:

Switching a provider off takes effect immediately: the adapter cache is invalidated by the save. Without that you would watch a disabled provider keep quoting for up to thirty seconds and reasonably conclude the toggle was broken.

Coverage gaps worth knowing before you enable a chain

• Fantom Opera (250) has no aggregator in this build. LI.FI's own live chain list no longer contains it after Fantom's migration to Sonic, and no other adapter reaches it. A direct pool is the only route there.
• Linea (59144) is absent from LI.FI, even though LI.FI supports it — this build has not identified the contract LI.FI routes Linea through, so claiming it would produce a venue failure at the last step instead of a clean "no route". 0x, 1inch and KyberSwap all price Linea.

Checking that it works

Admin → Swap → Requirements is the screen to use, not a per-provider test button — there is no credential-test action on the Providers screen in this build.

Its per-chain Test probe (POST /api/admin/dex/requirements/test, gated on edit.dex.chain because it makes outbound calls) talks to the chain, confirms the endpoint answers and answers as the chain id this build expects, and then asks candidates() — the same call the quote path makes — which adapters would be asked for a price. It reports them by name. Nothing is signed and no probe costs gas.

The global half of that report is what names a switched-on adapter with no credential, an addon master switch that is off, and quote-only mode. See Requirements.

Market data is a separate provider

Prices, candles and the trade feed do not come from an aggregator. They come from a market-data source selected by dexMarketProvider (default geckoterminal, alternatives codex and mock), with dexMarketProviderFallback for when the primary fails.

Set the fallback. A chart that stops drawing is the most visible failure on the page and has nothing at all to do with whether swaps still work.