Swagger

Swap

6 endpoints.

6 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

StatusWhen
200Chains
401Missing or invalid credentials
429Rate limit exceeded — retry after the number of seconds in the `Retry-After` response header
500Internal 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

StatusWhen
200Tokens
400Invalid request body or query parameters
401Missing or invalid credentials
429Rate limit exceeded — retry after the number of seconds in the `Retry-After` response header
500Internal 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

StatusWhen
200Same-asset pairs
400Invalid request body or query parameters
401Missing or invalid credentials
429Rate limit exceeded — retry after the number of seconds in the `Retry-After` response header
500Internal server error
Open in Swagger
POST/swap/quotePreview a same- or cross-chain swap

Quote a swap without creating an operation. Same response shape as a cross-chain send quote, so one renderer serves both.

  • 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 gasless 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
Input amount, base units
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

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

Wraps the routed swap as one gasless operation on the source networkId, charging the fee from fromToken or from feeToken. 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.
  • 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.
  • The prepared operation is held server-side for a limited time (default 30 minutes). If it expires before submit, prepare again.
  • 409 on a duplicate. 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

StatusWhen
201Prepared operation.
400Invalid request body, the referenced account belongs to a different network than the request targets, or (7702-mode projects only) EIP-7702 is not…
401Missing or invalid credentials
404The referenced accountId does not exist.
409Either a duplicate user operation (same UserOp hash already materialized), or code=SWAP_QUOTE_MOVED — `reviewedMinimumReceivedRaw` was supplied and…
422Unprocessable — either blocked by an unsafe security verdict (returns the prepared operation; enforcement is monitor-only by default), or the…
429Rate limit exceeded — retry after the number of seconds in the `Retry-After` response header
500Internal server error
503Self-funded native rail only, and always retryable — nothing is known to be wrong: code=SELF_FUNDED_ESTIMATE_UNAVAILABLE (the transfer could not be…
Open in Swagger
POST/swap/plain/preparePrepare a swap the client signs and broadcasts

Same-chain swap on the PLAIN rail, for a network without chain-level EIP-7702 where the gasless rail is unavailable. Returns one UNSIGNED EIP-1559 transaction the owner EOA signs and broadcasts itself, paying its own gas in the network's native coin. There is no userOperation, no userOperationHash, and nothing to submit here — after broadcasting, report the hash to POST /transaction/register-broadcast, which is the only way the operation reaches a terminal status. Cross-chain is refused rather than silently downgraded, and so is a network that does support the gasless rail. Returns a coded 422 with INSUFFICIENT_ALLOWANCE when the input token is not approved for the router. Returns 429 Too Many Requests if the rate limit is exceeded (check the Retry-After response header).

Authentication: X-API-Key

Input — request body

ownerAddress string required
Owner EOA — the sender and the broadcaster
networkId string required
Chain id
fromToken string required
Input token address
toToken string required
Output token address
amount string required
Input amount, base units
slippage number
Slippage tolerance as a fraction (0.005 = 0.5%)

Input — example request

{
  "ownerAddress": "0x0a1758ad202a2059e8c2970b562597ca45d863c4",
  "networkId": "43114",
  "fromToken": "0x9702230A8Ea53601f5cD2dc00fDBc13d4dF4A8c7",
  "toToken": "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E",
  "amount": "1000000",
  "slippage": 0.005
}

Output — example response (201)

{
  "operationId": "ugtp_operation_...",
  "senderAddress": "0x0a1758ad202a2059e8c2970b562597ca45d863c4",
  "networkId": "43114",
  "transaction": {
    "to": "0x1231DEB6f5749EF6cE6943a275A1D3E7486F4EaE",
    "value": "0x0",
    "data": "0x..."
  },
  "fromAmount": "1000000",
  "toAmount": "998500",
  "minimumReceived": "0.9935",
  "provider": "lifi"
}

Output — every status this endpoint answers with

StatusWhen
201Prepared unsigned transaction
400Invalid request body, cross-chain requested, or the network supports gasless execution (use /swap/prepare instead).
401Missing or invalid credentials
422code=INSUFFICIENT_ALLOWANCE (the input token is not approved for the router, so the swap would need two transactions) or code=NO_ROUTE_AVAILABLE.
429Rate limit exceeded — retry after the number of seconds in the `Retry-After` response header
500Internal server error
Open in Swagger