Swap

5 endpoints.

5 endpoints

Swap

GET/swap/chainsList swap-supported chains

LI.FI-supported chains filtered to the gateway's serviceable networks. Returns 429 Too Many Requests if the rate limit is exceeded (check the Retry-After response header).

Authentication: X-API-Key

Output — example response (200)

{
  "chains": [
    {
      "networkId": "42161",
      "name": "Arbitrum One",
      "nativeCurrency": "ETH",
      "logoUrl": "https://..."
    }
  ]
}

Output — every status this endpoint answers with

Status	When
`200`	Chains
`401`	Missing or invalid credentials
`429`	Rate limit exceeded — retry after the number of seconds in the `Retry-After` response header
`500`	Internal server error

Open in Swagger

GET/swap/tokens?networkId=List swap tokens for a chain

LI.FI tokens available on the given network. Each token carries LI.FI's coinKey (nullable) — the per-variant asset identifier used by /swap/token-map. Returns 429 Too Many Requests if the rate limit is exceeded (check the Retry-After response header).

Authentication: X-API-Key

Input — query and path parameters

networkId string required: Chain id, e.g. 42161

Output — example response (200)

{
  "networkId": "42161",
  "tokens": [
    {
      "address": "0x...",
      "symbol": "USDC",
      "name": "USD Coin",
      "decimals": 6,
      "networkId": "42161",
      "coinKey": "USDC"
    }
  ]
}

Output — every status this endpoint answers with

Status	When
`200`	Tokens
`400`	Invalid request body or query parameters
`401`	Missing or invalid credentials
`429`	Rate limit exceeded — retry after the number of seconds in the `Retry-After` response header
`500`	Internal server error

Open in Swagger

GET/swap/token-map?networkId=&toNetworkId=Cross-chain same-asset token pairs for a corridor

For every source-chain token with a same-asset counterpart on the destination chain, the destination token to deliver. Matched by LI.FI coinKey with same-asset family folding (USDT / USDT0 / USDt are one family), preferring the destination network's canonical token. Resolve a cross-chain send's destination token by fromAddress lookup here instead of comparing display symbols (which drift per chain). Returns 429 Too Many Requests if the rate limit is exceeded (check the Retry-After response header).

Authentication: X-API-Key

Input — query and path parameters

networkId string required: Source chain id, e.g. 42161
toNetworkId string required: Destination chain id, e.g. 43114 (must differ)

Output — example response (200)

{
  "networkId": "42161",
  "toNetworkId": "43114",
  "pairs": [
    {
      "fromAddress": "0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9",
      "toToken": {
        "address": "0x9702230A8Ea53601f5cD2dc00fDBc13d4dF4A8c7",
        "symbol": "USDt",
        "name": "TetherToken",
        "decimals": 6,
        "networkId": "43114",
        "coinKey": "USDt"
      }
    }
  ]
}

Output — every status this endpoint answers with

Status	When
`200`	Same-asset pairs
`400`	Invalid request body or query parameters
`401`	Missing or invalid credentials
`429`	Rate limit exceeded — retry after the number of seconds in the `Retry-After` response header
`500`	Internal server error

Open in Swagger

POST/swap/quotePreview a same- or cross-chain swap

Preview the swap amounts, minimum received and fees without creating an operation. Supports same-chain and cross-chain quotes.

AmountMode=exactInput (the default) treats amount as the source token to spend. exactOutput treats it as the destination target and computes the required source-side input, returned as fromAmount — which in that mode is no longer an echo of the request.
Omitting amountMode behaves exactly as exactInput, so an existing caller sees no change.
Not available on prepare: by then the caller already has a concrete fromAmount from the last resolved quote, so prepare always executes plain exact-input.
Coded 422 when the quote-time simulation reverts deterministically, for example SWAP_AMOUNT_TOO_SMALL when the route rejects the amount as below its minimum.
429 when the rate limit is exceeded; check the Retry-After response header.

Authentication: X-API-Key

Input — request body

ownerAddress string required: Owner EOA — the gateway resolves the account from it
networkId string required: Source chain id (where the op runs)
toNetworkId string: Destination chain id (defaults to networkId; a different value makes it cross-chain)
fromToken string required: Input token address (on networkId)
toToken string required: Output token address (on toNetworkId)
amount string required: Base-unit integer string: input amount for exactInput; destination target for exactOutput
amountMode "exactInput" | "exactOutput": Quote mode; defaults to exactInput. Prepare always uses the quoted fromAmount as exact input.
slippage number: Slippage tolerance as a fraction (0.005 = 0.5%); LI.FI default when omitted

Input — example request

{
  "ownerAddress": "0x9b5fcd6f647a14ebf0f88b1c3e5a3d34b951fc6f",
  "networkId": "137",
  "toNetworkId": "42161",
  "fromToken": "0x...",
  "toToken": "0x...",
  "amount": "1000000",
  "slippage": 0.005
}

Output — example response (200)

{
  "fromAmount": "1000000",
  "toAmount": "990000",
  "fromAmountUsd": "1.00",
  "toAmountUsd": "0.99",
  "rate": "0.99",
  "minimumReceived": "0.985050",
  "minimumReceivedUsd": "0.985",
  "networkFeeUsd": "0.01",
  "lifiFeesUsd": "0.002",
  "ugtpFeeUsd": "0.051",
  "ugtpFeeStaticUsd": 0.05,
  "ugtpFeePercent": 0.1,
  "feeTokenAmount": "0.061",
  "feeTokenSymbol": "USDC",
  "feeReserveTokenAmount": "0.061",
  "slippage": 0.005,
  "estimatedTimeSeconds": 30,
  "bridge": "uniswap",
  "provider": "uniswap"
}

Output — every status this endpoint answers with

Status	When
`200`	Quote
`400`	Invalid request body or query parameters
`401`	Missing or invalid credentials
`422`	The recommended route cannot execute — the quote-time simulation of the real approve+swap calldata reverted deterministically (e.g.
`429`	Rate limit exceeded — retry after the number of seconds in the `Retry-After` response header
`500`	An unclassified failure, carrying code=QUOTE_FAILED.

Open in Swagger

POST/swap/preparePrepare a same- or cross-chain swap

Prepares the routed swap on the source networkId. Token-settled rails charge fromToken or feeToken; the self-funded rail requires native gas. When toNetworkId differs it is a cross-chain swap: the operation runs on the source chain and the route bridges to the destination. Branch on the presence of rail.

No rail field: sign userOperationHash. rail "forward_request": sign the EIP-712 signingPayload and read destinationAssetSymbol, destinationAssetDecimals, and destinationAmountRaw. rail "self_funded": the account signs the whole router transaction, pays its own gas, and there is no ugtpFee.
ugtpFee carries tokenAmount, the worst case to reserve against, and expectedTokenAmount, what the operation is expected to bill. Both include the project's markup when it is paid in the fee token.
Prepare fetches its own fresh route, so pass reviewedMinimumReceivedRaw — what the user accepted on the review screen. Given it, prepare refuses with SWAP_QUOTE_MOVED instead of signing a route nobody reviewed.
Submit via POST /transaction/submit, then poll GET /transaction/:id.
Prepared operations expire after 30 minutes by default; self-funded swap quotes expire after 5 minutes. A self-funded native transfer receives its operationId only on submit. Prepare again if a stored preparation expires.
409 on a duplicate. On the self-funded rail, 409 with code=SENDER_OPERATION_IN_FLIGHT when the account already has a native transfer in flight at a different nonce. Re-preparing AT the in-flight nonce is admitted instead: that is how a stuck transfer is re-signed at a higher fee. Coded 422 when the simulated calldata reverts deterministically: SWAP_AMOUNT_TOO_SMALL or EXECUTION_SIMULATION_REVERTED with the raw reason.
429 when the rate limit is exceeded; check the Retry-After response header.

Authentication: X-API-Key

Input — request body

ownerAddress string required: Owner EOA — the gateway resolves the account from it
networkId string required: Source chain id (where the operation runs)
toNetworkId string: Destination chain id (defaults to networkId; a different value makes it cross-chain)
fromToken string required: Input token address (on networkId)
toToken string required: Output token address (on toNetworkId)
amount string required: Input amount, base units
slippage number: Slippage tolerance as a fraction (0.005 = 0.5%); LI.FI default when omitted
feeToken string: Fee token address (defaults to fromToken)
reviewedMinimumReceivedRaw string: The minimum received the user accepted, in the destination token's base units. Given it, prepare refuses with SWAP_QUOTE_MOVED rather than signing a route the user never reviewed.

Input — example request

{
  "ownerAddress": "0x696edf2490b92a5f5714ffbf69c1f6967cb2cd6d",
  "networkId": "42161",
  "toNetworkId": "1",
  "fromToken": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
  "toToken": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
  "amount": "250000",
  "reviewedMinimumReceivedRaw": "67734528796192"
}

Output — example response (201)

{
  "operationId": "ugtp_operation_wdxo2cOMXBIQ",
  "userOperation": {
    "sender": "0x696edf2490b92a5f5714ffbf69c1f6967cb2cd6d",
    "nonce": "0x20",
    "initCode": "0x",
    "callData": "0xb61d27f6…1924 bytes: approve the router, then the bridge call",
    "accountGasLimits": "0x0000000000000000000000000000873e00000000000000000000000000043258",
    "preVerificationGas": "0xeeb8",
    "gasFees": "0x0000000000000000000000000000000000000000000000000000000001706880",
    "paymasterAndData": "0x49f26881b5ea4d3f3d451c7faa4bca1b4aebcd97…214 bytes",
    "signature": "0x"
  },
  "userOperationHash": "0x9f165e8e0f3957722ad6520328ce00333c29f7d26ca50401bf7a5da8540c08c8",
  "ugtpFee": {
    "tokenAmount": "83266",
    "feeToken": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831"
  },
  "accountType": "eoa_7702",
  "authorizationRequired": false
}

Output — every status this endpoint answers with

Status	When
`201`	Prepared operation.
`400`	Invalid input, an unsupported network, or a self-funded call that cannot execute. Inspect the response code and reason.
`401`	Missing or invalid credentials
`404`	The referenced accountId does not exist.
`409`	Duplicate operation, SENDER_OPERATION_IN_FLIGHT, or SWAP_QUOTE_MOVED. For a moved quote, fetch a new quote and obtain user approval for its minimum before preparing again.
`422`	Blocked by a security verdict, insufficient native balance, or deterministic execution failure. Inspect security or the error code before signing.
`429`	Rate limit exceeded — retry after the number of seconds in the `Retry-After` response header
`500`	Internal server error
`503`	SELF_FUNDED_ESTIMATE_UNAVAILABLE: the operation could not be measured. Retry preparation with bounded backoff.

Open in Swagger

Documentation navigation

Output — example response (200)

Output — every status this endpoint answers with

Input — query and path parameters

Output — example response (200)

Output — every status this endpoint answers with

Input — query and path parameters

Output — example response (200)

Output — every status this endpoint answers with

Input — request body

Input — example request

Output — example response (200)

Output — every status this endpoint answers with

Input — request body

Input — example request

Output — example response (201)

Output — every status this endpoint answers with