How a swap aggregator is built: quotes, normalisation, routing and execution, explained for builders

The architecture behind any aggregator — on-chain DEX routers and cross-chain instant swaps alike: pulling quotes from sources, reducing them to a comparable net output, choosing a route by size, executing safely, and handling the failure cases that matter in production. What is the same across both models and what is different.

Two kinds of aggregator, one shape

"Aggregator" covers two different products that share an architecture:

On-chain DEX aggregators (1inch, Odos, Jupiter on Solana) route a token-to-token trade through AMM pools on one chain and execute it in a single transaction the user signs.
Cross-chain swap aggregators / instant swaps (the model SyntheticSwap uses) route a coin-to-coin conversion across unrelated chains to liquidity sources, executing off-chain and settling with two on-chain transfers.

Both have the same five layers: source adapters, quote normalisation, route selection, execution, and monitoring. Here is what each layer does and where the two models diverge.

Layer 1 — Source adapters

Every source speaks its own language. A DEX pool exposes reserves and a swap function; a liquidity provider exposes an API with a quote endpoint, limits, and an order endpoint. The adapter's job is to turn each of these into one interface: given input asset, output asset and amount, what would this source deliver, and can it deliver at all right now?

Practical concerns that dominate this layer in production:

Availability. Sources go down or pause pairs. An adapter must fail fast and let routing continue without it.
Limits. Every source has a minimum and maximum per pair; the adapter must expose them so the router does not select a source that will reject the order.
Fee semantics. Does the quoted output already subtract the payout fee? Is the fee in the input asset or the output asset? Getting this wrong is the most common cause of "estimate did not match".
Asset identity. "USDT" is not one asset. The adapter must map each source's naming to a canonical (asset, network) pair — USDT on TRON and USDT on Ethereum are different things with different fees and confirmations. SyntheticSwap's pair pages carry the network in the URL (/swap/usdt-erc20/usdt-trc20) for exactly this reason.

Layer 2 — Normalisation

The router cannot compare a rate with a rate. It compares net output: the amount of the output asset the user would actually receive after every fee the source charges. Normalisation converts each adapter's response to that single figure, plus metadata: the source's limits, the confirmations it will require, the expected payout fee, and a validity window.

On-chain aggregators add gas here — the transaction cost of executing the route, which varies with the route's length and the chain's current fee level. Cross-chain aggregators add the payout network fee, which is fixed per output chain and matters most for small amounts.

Layer 3 — Route selection

With comparable quotes in hand, selection is where the product differs from a naive "pick the best rate":

Size-aware. Quotes are requested at the actual amount. A source that is best at $100 may be worst at $50,000 because of depth. On-chain routers model this via pool reserves (constant-product or stable-swap curves); cross-chain routers ask each source for a quote at size.
Split routes. On-chain aggregators can split one trade across several pools in one transaction to reduce price impact. Cross-chain routers generally select one source per order because each source needs its own deposit address; splitting is offered to the user as two swaps.
Multi-hop. On-chain, A → B may be cheaper as A → USDC → B; the router searches paths. Cross-chain, the sources themselves usually route internally, and the aggregator compares final outputs.
Constraints. Filter out sources whose limits exclude the amount, whose pair is paused, or whose quote is stale.

The output of this layer is one route (or a split plan) and one net output figure — the number the user sees.

Layer 4 — Execution

This is where the two models diverge most.

On-chain: the aggregator builds a transaction that calls its router contract with the chosen path; the user signs it; the contract executes atomically — either the whole route succeeds and the user receives at least the minimum output they accepted, or it reverts. Slippage tolerance is enforced in the contract. MEV protection means submitting through a private relay rather than the public mempool.

Cross-chain: there is no atomic transaction across Bitcoin and Monero. Execution is a state machine:

Create the order with the selected source; obtain a deposit address unique to the order.
Watch the deposit chain for a transaction to that address; count confirmations against the chain's requirement (2 for Bitcoin, 15 for Ethereum, 1 for USDT on TRON).
At the required count, execute the trade with the source at the then-current rate for the amount received (floating) or at the locked rate (fixed).
Send the payout; record its transaction hash; expose it on the status page.
Handle exceptions: amount below minimum → refund minus fee; amount different from order → recalculate; wrong asset sent → escalate.

The confirmation counts are not tunable for speed — they are what makes step 3 safe against reorganisations and replaced transactions.

Layer 5 — Monitoring and transparency

An aggregator that cannot show its work is a black box. The minimum production instrumentation:

Per-source quote latency, error rate and win rate (how often each source is selected).
Estimate-vs-actual output per order, to catch fee-semantics bugs at the adapter layer.
Deposit-to-payout time distribution per chain, to detect chain congestion and stuck orders.

Exposed to users, the same data becomes a feature. SyntheticSwap's pair pages show the all-in output for a sample amount against the CoinGecko mid-rate — a direct readout of Layer 3's result — and the confirmation-based time estimate from Layer 4.

Where builders go wrong

Trusting a source's "rate" field. Always compute net output yourself from the source's own fee rules and verify against executed orders.
Treating tickers as identity. Network must be part of the asset key from day one.
Optimising for the demo amount. Route selection that is only tested at $100 fails at $10,000.
Ignoring the refund path. Below-minimum deposits and fee-deducted amounts are daily events; the flow for them is part of the product, not an edge case.
Shipping coverage before routing quality. A hundred pairs with one source each is worse than twenty pairs with three sources each.

Frequently asked questions

Is an instant swap "just a front-end for one provider"? It can be — that is the failure mode this article describes. A real aggregator has Layer 1 adapters for several sources and a Layer 3 that chooses between them per request.

Why can't cross-chain swaps be atomic? Because Bitcoin, Monero and TRON do not share a virtual machine. Atomic swaps via hash time-locked contracts exist for some pairs but are impractical for Monero and for most users; the state-machine model is the working solution.

How do aggregators make money? A spread on the net output, and sometimes a share of the source's fee. The honest ones show the net output and let users compare.

What is the hardest layer? Adapters. Routing is a well-understood optimisation; keeping twenty sources' fee semantics, limits and outages correct is the daily work.