Developer guide

Swaps and bridges

8 min read

Route execution

LI.FI routes' quotes and status are read live from the provider. Execution does not settle through the provider today: the movement is substituted in this platform's own ledger and reported as SUBSTITUTED, with no network cost measured, so a simulated leg is never presented as a real blockchain transaction. Each leg is persisted independently and crosses the same signing boundary as every other operation type. Live route execution is on the Roadmap.

What an operation executes

A swap or a transfer to another network is a ChatterPay Operation, created the same way as a transfer: POST /v1/quotes with what to send and what to receive, then POST /v1/transfers with the accepted quote's quoteId. The official SDK does the same through quote() and transfer(). The platform builds the route behind the quote, validates it against the quote's networks, assets, amounts and recipient, and executes that route from the account within the limits the deployment allows. Both requests carry the quote's terms and its identifier, and the SDK's request types have no field for a provider transaction or calldata.

A quote a provider priced carries the provider's answer in providerRoute, and POST /v1/lifi/quotes returns the aggregator's quote as the aggregator answered it. Either may include a transactionRequest, which shows what the provider proposed. A transactionRequest or other calldata sent back in a request executes nothing: the platform ignores the field and answers as if it were absent.

Same-chain swaps

A swap between two representations on the same network is not settled by the aggregator. It prices only tokens their official issuer published on each network, and none of this deployment's own representations, so nobody quotes that pair. Outside mainnet it is settled by a pool the deployment owns, seeds and prices itself.

That pool is not a market. Its rates are fixed per ordered pair and set when it is deployed: there is no curve, no liquidity provider and no price discovery, so a quote is exactly reproducible and equals what the execution pays. A quote settled by it carries settlementProvider: "deployment_pool" and swapProvider.productive: false, and no surface may present its rate as a market price. On mainnet the aggregator settles the swap with the real tokens.

The quote states what it will deliver — toAmount, in the asset being received — before it is accepted, and that figure is the floor the execution accepts: a rate that changed in between reverts on chain instead of delivering less. What is credited afterwards is read from the settlement itself, not from the quote.

Declared limitation A same-network swap executes, confirms and ends in a transaction hash, but the operation does not yet report a reconciliation of its two assets against the chain, so the Roadmap lists swaps on EVM as in progress.

When a route is eligible

LI.FI is used for an enabled swap, bridge or cross-chain combination; it is not a fallback for a direct transfer. The route, assets, networks and environment must be explicitly approved by capability manifests.

Operations each asset declares

GET /v1/assets lists, on every asset representation, the operations it can take in operations. Each entry carries:

  • operationType: direct_transfer on the asset's own network, swap on the same network, or cross_chain_transfer to another network;
  • settlementProvider: direct, deployment_pool or lifi;
  • routeExecutionMode, where a provider routes the operation: substituted states before anything is quoted that the funds will not move through the provider's route;
  • toAssetIds, for a swap or a transfer to another network: the representations the operation can deliver.

Read operations before quoting. A quote for an operation the asset does not list, or for a destination that operation does not deliver, is refused before any provider is asked. Two representations of the same symbol on the same network can list different operations. On a deployment whose transfers between networks are substituted, a transfer to another network is listed on a non-canonical-test row when the aggregator has a token to price that row in, and its destinations are the non-canonical-test rows on other networks that the aggregator can price too. A representation the aggregator has no token to route lists no cross_chain_transfer: on Arbitrum Sepolia the deployment's WETH is one, and a quote from it on POST /v1/quotes is refused with ROUTE_NOT_AVAILABLE without asking the aggregator.

On the test networks, bridges between networks use USDC, and WETH operates within one network.

Two USDC on one network

A network can list two representations with the same symbol. On Arbitrum Sepolia and Base Sepolia the catalog lists two USDC rows: the token its issuer published on that network, with canonicality: "canonical", and the token this deployment issued, with canonicality: "non-canonical-test". They are two assets. The network and the contract address identify an asset — chainId and contractAddress on the row — and the symbol only names it. Check contractAddress, never the symbol, before sending funds to or from a contract. The row of a network's own coin carries no contractAddress, because no contract backs it.

The USDC rows whose canonicality is canonical have these contract addresses, with 6 decimals:

  • Arbitrum Sepolia: 0x75faf114eafb1BDbe2F0316DF893fd58CE46AA4d
  • Base Sepolia: 0x036CbD53842c5426634e7929541eC2318f3dCF7e

The non-canonical-test row of each network publishes its own address in the same catalog. The test-balance endpoint grants only non-canonical-test tokens and answers ASSET_NOT_FUNDABLE for a canonical row: a wallet holds that USDC after receiving it from outside this platform, from the issuer's public faucet or by a transfer, and its balance reports it on its own row.

A bare symbol in toAssetId resolves among the representations that share the canonicality of the asset sent; a network's own coin counts as canonical, so from ETH a bare USDC resolves to the USDC row whose canonicality is canonical. To reach the other row, send its representation identifier as toAssetId.

USDC between Arbitrum Sepolia and Base Sepolia

What this route offers today depends on the row it starts from:

  • From the USDC row whose canonicality is canonical, the catalog lists no cross_chain_transfer, and a quote for one is refused with ROUTE_NOT_AVAILABLE. That row takes transfers on its own network. Live route execution, which this route needs, is on the Roadmap.
  • From the USDC row whose canonicality is non-canonical-test, the catalog lists cross_chain_transfer through lifi with routeExecutionMode: "substituted". The provider prices the route against the issuer's USDC and the quote reports that token in providerAssets. The movement is recorded in this platform's ledger and no cross-chain transaction exists to look up: it is a simulated route.

Refusals and what to do with each

All three are answered by POST /v1/quotes with HTTP 409, and nothing is priced or stored.

ROUTE_NOT_AVAILABLE

  • When: the asset sent does not list the requested operation in operations, or that operation does not deliver the requested destination. It is answered before any provider is asked.
  • retryable: false. It is a property of the catalog: the same request keeps failing until the catalog lists the operation.
  • details: the representation, the operation and the destination requested, and the operations the representation does list.
  • What to do: choose an operation and a destination from the operations of the asset sent.

PROVIDER_ROUTE_UNAVAILABLE

  • When: the operation is listed, and the provider that settles it answered that it has no route.
  • retryable: true. It is the provider's answer of that moment.
  • details: the provider.
  • What to do: request a new quote later. A provider that times out or answers something unrecognised is reported with a different code.

AMBIGUOUS_ASSET

  • When: toAssetId is a bare symbol and more than one representation on the destination network still matches it.
  • retryable: false. The same request with a representation identifier as toAssetId is answered.
  • details: details.candidates lists each matching representation with assetId, chainId, contractAddress and canonicality.
  • What to do: send the request again with the chosen candidate's assetId as toAssetId.

Quote and settlement

A route quote keeps ChatterPay's service fee separate from provider and network costs. The customer accepts the quote before execution begins. If the route's provider cost cannot be safely normalized to the source asset, the platform does not invent a total debit.

Multi-leg truth

Cross-chain work can contain irreversible legs. The operation records explicit partial or recovery states rather than claiming a fictional rollback.

Where a deployment executes a provider route on-chain, each bridge leg returned by GET /v1/operations/{operationId}/legs carries quoteReconciliation once its deposit is confirmed: the source amount, the delivered amount, the provider fee, the service fee and the gas, each quoted against realised, with the difference and a status of matched, within_tolerance, deviation or not_measured. A figure past the deployment's tolerance, and a deposit or a delivery that carried an amount or a recipient other than the route's, is counted as a discrepancy in the reconciliation. The reconciliation records and flags: the debits and credits keep the amounts of the accepted quote and of the fee policy. Roadmap Live route execution, which these legs need. While execution is substituted there is no provider evidence to compare, so a LI.FI leg is recorded and left unchecked rather than reported as reconciled.

Capabilities in this area

This area covers the capabilities below. The Roadmap states the current availability of each one.

  • Live read-only quote and status — The platform asks the live LI.FI service which routes exist for a pair of assets, what they cost and what state an execution is in. It only reads, so a Partner can see real prices and real route availability.

  • Cross-network swaps and bridges — A route that crosses networks is quoted from the provider's live prices and can be executed from the API and the SDK. The execution is a labelled simulation: the answer says so and its hashes link to no block explorer. Settling the route for real on a public network, with a limit per tenant, a stop switch and a check that the route about to run is the one quoted, is what completes the capability.

  • Swap-eligible assets aligned with LI.FI coverage — The list of assets that can be swapped is built from the routes the aggregator actually covers. Asking for a quote on an asset with no route is answered with that reason, instead of an empty route. It covers the assets a Partner's production deployment enables on mainnet.