LI.FI Relayer API
The Relayer API from LI.FI — 3 operation(s) for relayer.
OpenAPI Specification
openapi: 3.0.0
info:
title: LI.FI Earn advanced Relayer API
description: Enterprise DeFi yield discovery and tracking API
version: 0.1.0
contact: {}
servers:
- url: https://earn.li.fi
description: Production
security:
- x-lifi-api-key: []
tags:
- name: Relayer
paths:
/v1/relayer/status/{taskId}:
get:
responses:
'200':
$ref: '#/components/responses/RelayerStatusResponse'
description: 'Cross chain relay transfers might take a while to complete. Waiting on the transaction on the sending chain doesn''t help here. For this reason we build a simple endpoint that let''s you check the status of your transfer.
Important: The endpoint returns a `200` successful response even if the transaction can not be found. This behavior accounts for the case that the transaction hash is valid but the transaction has not been mined yet.
While non of the parameters `fromChain`, `toChain` and `bridge` are required, passing the `fromChain` parameter will speed up the request and is therefore encouraged.
If you want to learn more about how to use this endpoint please have a look at our [guide](/introduction/user-flows-and-examples/status-tracking).'
tags:
- Relayer
/v1/relayer/quote:
get:
parameters:
- example: DAI
name: fromChain
description: The sending chain. Can be the chain id or chain key
schema:
type: string
in: query
required: true
- example: POL
name: toChain
description: The receiving chain. Can be the chain id or chain key
schema:
type: string
in: query
required: true
- example: '0x4ecaba5870353805a9f068101a40e0f32ed605c6'
name: fromToken
description: The token that should be transferred. Can be the address or the symbol
schema:
type: string
in: query
required: true
- example: '0x2791bca1f2de4661ed88a30c99a7a9449aa84174'
name: toToken
description: The token that should be transferred to. Can be the address or the symbol
schema:
type: string
in: query
required: true
- example: '0x552008c0f6870c2f77e5cC1d2eb9bdff03e30Ea0'
name: fromAddress
description: The sending wallet address
schema:
type: string
in: query
required: true
- example: '0x552008c0f6870c2f77e5cC1d2eb9bdff03e30Ea0'
name: toAddress
description: The receiving wallet address. If none is provided, the fromAddress will be used
schema:
type: string
in: query
required: false
- example: '1000000'
name: fromAmount
description: The amount that should be sent including all decimals (e.g. 1000000 for 1 USDC (6 decimals))
schema:
type: string
in: query
required: true
- name: order
description: 'Which kind of route should be preferred **FASTEST**: This sorting criterion prioritizes routes with the shortest estimated execution time. Users who value speed and want their transactions to be completed as quickly as possible should choose the fastest routes. **CHEAPEST**: This criterion focuses on minimizing the cost of the transaction, whether in token amount or USD amount (USD amount minus gas cost). Users looking for the most economical option should choose the cheapest routes.'
schema:
enum:
- FASTEST
- CHEAPEST
type: string
in: query
- example: 0.005
name: slippage
description: The maximum allowed slippage for the transaction as a decimal value. 0.005 represents 0.5%.
schema:
maximum: 1
minimum: 0
type: number
in: query
- example: fee-demo
name: integrator
description: A string containing tracking information about the integrator of the API
schema:
type: string
in: query
- example: 0.02
name: fee
description: The percent of the integrator's fee that is taken from every transaction. 0.02 represents 2%. The maximum fee amount should be less than 100%.
schema:
maximum: 1
exclusiveMaximum: true
minimum: 0
type: number
in: query
- name: referrer
description: A string containing tracking information about the referrer of the integrator
schema:
type: string
in: query
required: false
- example: hop,cbridge
name: allowBridges
description: List of bridges that are allowed for this transaction. Retrieve the current catalog from the `/v1/tools` endpoint. Also values `all`, `none`, `default` and `[]` are acceptable and mean all tools of the current type (`all`), no tools (for `none` and `[]` cases) and default tool's settings on the current stage.
schema:
type: array
items:
$ref: '#/components/schemas/QuoteBridgesEnum'
in: query
- name: allowExchanges
description: List of exchanges that are allowed for this transaction. Retrieve the current catalog from the `/v1/tools` endpoint. Also values `all`, `none`, `default` and `[]` are acceptable and mean all tools of the current type (`all`), no tools (for `none` and `[]` cases) and default tool's settings on the current stage.
schema:
type: array
items:
$ref: '#/components/schemas/QuoteExchangesEnum'
in: query
- example: relay
name: denyBridges
description: List of bridges that are not allowed for this transaction. Retrieve the current catalog from the `/v1/tools` endpoint. Also values `all`, `none`, `default` and `[]` are acceptable and mean all tools of the current type (`all`), no tools (for `none` and `[]` cases) and default tool's settings on the current stage.
schema:
type: array
items:
$ref: '#/components/schemas/QuoteBridgesEnum'
in: query
- name: denyExchanges
description: List of exchanges that are not allowed for this transaction. Retrieve the current catalog from the `/v1/tools` endpoint. Also values `all`, `none`, `default` and `[]` are acceptable and mean all tools of the current type (`all`), no tools (for `none` and `[]` cases) and default tool's settings on the current stage.
schema:
type: array
items:
$ref: '#/components/schemas/QuoteExchangesEnum'
in: query
- name: preferBridges
description: List of bridges that should be preferred for this transaction. Retrieve the current catalog from the `/v1/tools` endpoint. Also values `all`, `none`, `default` and `[]` are acceptable and mean all tools of the current type (`all`), no tools (for `none` and `[]` cases) and default tool's settings on the current stage.
schema:
type: array
items:
$ref: '#/components/schemas/QuoteBridgesEnum'
in: query
- name: preferExchanges
description: List of exchanges that should be preferred for this transaction. Retrieve the current catalog from the `/v1/tools` endpoint. Also values `all`, `none`, `default` and `[]` are acceptable and mean all tools of the current type (`all`), no tools (for `none` and `[]` cases) and default tool's settings on the current stage.
schema:
type: array
items:
$ref: '#/components/schemas/QuoteExchangesEnum'
in: query
- name: allowDestinationCall
description: Whether swaps or other contract calls should be allowed as part of the destination transaction of a bridge transfer. Separate swap transactions on the destination chain are not affected by this flag. By default, parameter is `true`.
schema:
type: boolean
in: query
- name: fromAmountForGas
description: The amount of the token to convert to gas on the destination side.
schema:
type: string
in: query
required: false
- name: maxPriceImpact
description: The price impact threshold above which routes are hidden. As an example, one should specify 0.15 (15%) to hide routes with more than 15% price impact. The default is 10%.
schema:
type: number
in: query
- name: swapStepTimingStrategies
description: Timing setting to wait for a certain amount of swap rates. In the format `minWaitTime-${minWaitTimeMs}-${startingExpectedResults}-${reduceEveryMs}`. Please check [docs.li.fi](https://docs.li.fi) for more details.
schema:
type: array
items:
type: string
example: minWaitTime-600-4-300
in: query
required: false
- name: routeTimingStrategies
description: Timing setting to wait for a certain amount of routes to be generated before chosing the best one. In the format `minWaitTime-${minWaitTimeMs}-${startingExpectedResults}-${reduceEveryMs}`. Please check [docs.li.fi](https://docs.li.fi) for more details.
schema:
type: array
items:
type: string
example: minWaitTime-600-4-300
in: query
required: false
- name: skipSimulation
description: Parameter to skip transaction simulation. The quote will be returned faster but the transaction gas limit won't be accurate.
schema:
type: boolean
in: query
required: false
- name: x-lifi-api-key
description: Authentication header, register in the LI.FI Partner Portal (https://portal.li.fi/ ) to get your API Key.
schema:
type: string
in: header
responses:
'200':
$ref: '#/components/responses/RelayerQuoteResponse'
'400':
$ref: '#/components/responses/InvalidQuoteRequest'
'404':
$ref: '#/components/responses/QuoteNotFound'
summary: Get a quote for a relayed token transfer
description: 'This endpoint can be used to request a quote for a transfer of one token to another, cross chain or not.
The endpoint returns a `Step` object which contains information about the estimated result as well as a `transactionRequest` which can directly be sent to your wallet.
The estimated result can be found inside the `estimate`, containing the estimated `toAmount` of the requested `Token` and the `toAmountMin`, which is the guaranteed minimum value that the transfer will yield including slippage.
If you want to learn more about how to use this endpoint please have a look at our [guide](/introduction/user-flows-and-examples/requesting-route-fetching-quote).'
tags:
- Relayer
/v1/relayer/relay:
post:
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/RelayRequestSchema'
required: true
responses:
'200':
$ref: '#/components/responses/RelayResponse'
summary: Send a signed permit2 transaction to be dispatched by a transaction relayer
description: Submits a gasless transaction to the relayer for execution on-chain.
tags:
- Relayer
components:
schemas:
RelayWithnessType:
title: Root Type for RelayWithnessType
description: ''
type: object
properties:
LiFiCall:
type: array
items:
$ref: '#/components/schemas/RelayWitnessParameters'
example:
LiFiCall:
- type: address
name: diamondAddress
- type: bytes32
name: diamondCalldataHash
RelayQuoteData:
title: Root Type for RelayQuoteData
description: ''
type: object
properties:
quote:
$ref: '#/components/schemas/RelayQuote'
properties:
tokenOwner:
type: string
chainId:
format: int32
type: integer
permit:
type: object
properties:
permitted:
type: object
properties:
token:
type: string
amount:
type: string
spender:
type: string
nonce:
type: string
deadline:
format: int32
type: integer
witness:
type: object
properties:
witnessType:
type: object
properties:
LiFiCall:
type: array
items:
type: object
properties:
type:
type: string
name:
type: string
witnessTypeName:
type: string
witness:
type: object
properties:
diamondAddress:
type: string
diamondCalldataHash:
type: string
permitData:
type: object
properties:
domain:
type: object
properties:
name:
type: string
chainId:
format: int32
type: integer
verifyingContract:
type: string
types:
type: object
properties:
PermitWitnessTransferFrom:
type: array
items:
type: object
properties:
type:
type: string
name:
type: string
TokenPermissions:
type: array
items:
type: object
properties:
type:
type: string
name:
type: string
LiFiCall:
type: array
items:
type: object
properties:
type:
type: string
name:
type: string
values:
type: object
properties:
permitted:
type: object
properties:
token:
type: string
amount:
type: string
spender:
type: string
nonce:
type: string
deadline:
format: int32
type: integer
witness:
type: object
properties:
diamondAddress:
type: string
diamondCalldataHash:
type: string
step:
type: object
approvalTxs:
type: array
items:
$ref: '#/components/schemas/ContractTransactionSchema'
example:
quote:
tokenOwner: '0xb9c0dE368BECE5e76B52545a8E377a4C118f597B'
chainId: 137
permit:
permitted:
token: '0xc2132D05D31c914a87C6611C10748AEb04B58e8F'
amount: '1000000'
spender: '0x6307119078556Fc8aD77781DFC67df20d75FB4f9'
nonce: '19'
deadline: 1738149521625
witness:
witnessType:
LiFiCall:
- type: address
name: diamondAddress
- type: bytes32
name: diamondCalldataHash
witnessTypeName: LiFiCall
witness:
diamondAddress: '0x1231DEB6f5749EF6cE6943a275A1D3E7486F4EaE'
diamondCalldataHash: '0x78c758554f4213645a8ebcaa5c5c3eb7e6db4b90cf37df4adb54fb92a7fb2a78'
permitData:
domain:
name: Permit2
chainId: 137
verifyingContract: '0x000000000022D473030F116dDEE9F6B43aC78BA3'
types:
PermitWitnessTransferFrom:
- type: TokenPermissions
name: permitted
- type: address
name: spender
- type: uint256
name: nonce
- type: uint256
name: deadline
- type: LiFiCall
name: witness
TokenPermissions:
- type: address
name: token
- type: uint256
name: amount
LiFiCall:
- type: address
name: diamondAddress
- type: bytes32
name: diamondCalldataHash
values:
permitted:
token: '0xc2132D05D31c914a87C6611C10748AEb04B58e8F'
amount: '1000000'
spender: '0x6307119078556Fc8aD77781DFC67df20d75FB4f9'
nonce: '19'
deadline: 1738149521625
witness:
diamondAddress: '0x1231DEB6f5749EF6cE6943a275A1D3E7486F4EaE'
diamondCalldataHash: '0x78c758554f4213645a8ebcaa5c5c3eb7e6db4b90cf37df4adb54fb92a7fb2a78'
step: {}
approvalTxs: []
RelayRequestSchema:
description: ''
required:
- tokenOwner
- chainId
- callData
type: object
properties:
tokenOwner:
description: ''
type: string
chainId:
description: ''
type: number
permit:
$ref: '#/components/schemas/RelayPermitSchema'
description: ''
signedPermitData:
description: ''
type: string
callData:
description: ''
type: string
QuoteExchangesEnum:
type: string
description: 'Exchange tool identifier or keyword. Retrieve current exchange keys from the `/v1/tools` endpoint. Supported keywords: `all`, `none`, `default`, `[]`.'
RelayTransactionStatusResponse:
title: Root Type for RelayTransactionStatusResponse
description: ''
required:
- data
type: object
properties:
status:
type: string
data:
$ref: '#/components/schemas/RelayTransactionStatus'
properties:
status:
type: string
message:
type: string
metadata:
type: object
properties:
chainId:
format: int32
type: integer
txHash:
type: string
transactionStatus:
type: object
properties:
transactionId:
type: string
sending:
type: object
properties:
txHash:
type: string
txLink:
type: string
amount:
type: string
token:
type: object
properties:
address:
type: string
chainId:
format: int32
type: integer
symbol:
type: string
decimals:
format: int32
type: integer
name:
type: string
coinKey:
type: string
logoURI:
type: string
priceUSD:
type: string
chainId:
format: int32
type: integer
gasPrice:
type: string
gasUsed:
type: string
gasToken:
type: object
properties:
address:
type: string
chainId:
format: int32
type: integer
symbol:
type: string
decimals:
format: int32
type: integer
name:
type: string
coinKey:
type: string
logoURI:
type: string
priceUSD:
type: string
gasAmount:
type: string
gasAmountUSD:
type: string
amountUSD:
type: string
timestamp:
format: int32
type: integer
receiving:
type: object
properties:
txHash:
type: string
txLink:
type: string
amount:
type: string
token:
type: object
properties:
address:
type: string
chainId:
format: int32
type: integer
symbol:
type: string
decimals:
format: int32
type: integer
name:
type: string
coinKey:
type: string
logoURI:
type: string
priceUSD:
type: string
chainId:
format: int32
type: integer
gasPrice:
type: string
gasUsed:
type: string
gasToken:
type: object
properties:
address:
type: string
chainId:
format: int32
type: integer
symbol:
type: string
decimals:
format: int32
type: integer
name:
type: string
coinKey:
type: string
logoURI:
type: string
priceUSD:
type: string
gasAmount:
type: string
gasAmountUSD:
type: string
amountUSD:
type: string
timestamp:
format: int32
type: integer
example:
status: ok
data:
status: DONE
message: All done
metadata:
chainId: 137
txHash: '0x1425098ed5ecc5192070ac32a69dd924268b9df5e7a69764142473e9d022321a'
transactionStatus:
transactionId: '0xaddfdf22eeacd02f006e04bbb58f683394807664f62e150b078db0598ab64daa'
sending:
txHash: '0x1425098ed5ecc5192070ac32a69dd924268b9df5e7a69764142473e9d022321a'
txLink: https://polygonscan.com/tx/0x1425098ed5ecc5192070ac32a69dd924268b9df5e7a69764142473e9d022321a
amount: '1000000'
token:
address: '0xc2132D05D31c914a87C6611C10748AEb04B58e8F'
chainId: 137
symbol: USDT
decimals: 6
name: USDT
coinKey: USDT
logoURI: https://raw.githubusercontent.com/trustwallet/assets/master/blockchains/ethereum/assets/0xdAC17F958D2ee523a2206206994597C13D831ec7/logo.png
priceUSD: '0.99989'
chainId: 137
gasPrice: '85184881231'
gasUsed: '361568'
gasToken:
address: '0x0000000000000000000000000000000000000000'
chainId: 137
symbol: POL
decimals: 18
name: Polygon Ecosystem Token
coinKey: POL
logoURI: https://static.debank.com/image/matic_token/logo_url/matic/6f5a6b6f0732a7a235131bd7804d357c.png
priceUSD: '0.4506'
gasAmount: '30800127136930208'
gasAmountUSD: '0.0139'
amountUSD: '0.9999'
timestamp: 1736518025
receiving:
txHash: '0x1425098ed5ecc5192070ac32a69dd924268b9df5e7a69764142473e9d022321a'
txLink: https://polygonscan.com/tx/0x1425098ed5ecc5192070ac32a69dd924268b9df5e7a69764142473e9d022321a
amount: '820847'
token:
address: '0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359'
chainId: 137
symbol: USDC
decimals: 6
name: USD Coin
coinKey: USDC
logoURI: https://static.debank.com/image/coin/logo_url/usdc/e87790bfe0b3f2ea855dc29069b38818.png
priceUSD: '1.000100010001'
chainId: 137
gasPrice: '85184881231'
gasUsed: '361568'
gasToken:
address: '0x0000000000000000000000000000000000000000'
chainId: 137
symbol: POL
decimals: 18
name: Polygon Ecosystem Token
coinKey: POL
logoURI: https://static.debank.com/image/matic_token/logo_url/matic/6f5a6b6f0732a7a235131bd7804d357c.png
priceUSD: '0.4506'
gasAmount: '30800127136930208'
gasAmountUSD: '0.0139'
amountUSD: '0.8209'
timestamp: 1736518025
RelayAccessList:
description: ''
type: object
properties:
address:
description: ''
type: string
storageKeys:
description: ''
type: array
items:
type: string
Token:
title: Root Type for Token
description: Representation of a Token
required:
- address
- chainId
- decimals
- name
- symbol
type: object
properties:
address:
description: Address of the token
type: string
decimals:
format: number
description: Number of decimals the token uses
type: number
symbol:
description: Symbol of the token
type: string
chainId:
format: number
description: Id of the token's chain
type: number
coinKey:
description: Identifier for the token
type: string
name:
description: Name of the token
type: string
logoURI:
description: Logo of the token
type: string
priceUSD:
description: Token price in USD
type: string
example:
address: '0x8f3cf7ad23cd3cadbd9735aff958023239c6a063'
symbol: DAI
decimals: 18
chainId: 137
name: (PoS) Dai Stablecoin
coinKey: DAI
priceUSD: '1'
logoURI: https://static.debank.com/image/matic_token/logo_url/0x8f3cf7ad23cd3cadbd9735aff958023239c6a063/549c4205dbb199f1b8b03af783f35e71.png
IncludedSwapSteps:
title: Root type for included swaps or protocol steps in the status response
description: The included steps contain tool name and details, sending and receiving token data and amounts.
type: object
properties:
tool:
description: The tool used for this step
type: string
toolDetails:
description: The details of the tool used for this step. E.g. `1inch` or `feeProtocol`
type: object
properties:
key:
description: The tool key
type: string
name:
description: The tool name
type: string
logoURI:
description: The tool logo URL
type: string
fromAmount:
description: The amount that was sent to the tool
type: string
fromToken:
description: The token that was sent to the tool
type: string
toAmount:
description: The amount that was received from the tool
type: string
toToken:
description: The token that was received from the tool
type: string
bridgedAmount:
description: The amount that was sent to the bridge
type: string
Metadata:
title: Root type for Transaction Metadata
description: The metadata of the transaction which includes integrator data, etc.
type: object
properties:
integrator:
description: Integrator ID
type: string
QuoteBridgesEnum:
type: string
description: 'Bridge tool identifier or keyword. Retrieve current bridge keys from the `/v1/tools` endpoint. Supported keywords: `all`, `none`, `default`, `[]`.'
RelayResponse:
title: Root Type for RelayResponse
description: ''
type: object
properties:
status:
type: string
data:
$ref: '#/components/schemas/RelayResponseData'
properties:
taskId:
type: string
example:
status: ok
data:
taskId: string
Estimate:
title: Root Type for Estimate
description: An estimate for the current transfer
required:
- fromAmount
- approvalAddress
- toAmount
- toAmountMin
- tool
- executionDuration
type: object
properties:
tool:
description: The tools that is being used for this step
type: string
fromAmount:
description: The amount that should be transferred including all decimals
type: string
fromAmountUSD:
description: The amount that should be transferred in USD equivalent
type: string
toAmount:
description: The estimated resulting amount of the `toToken` including all decimals
type: string
toAmountMin:
description: The minimal outcome of the transfer including all decimals
type: string
toAmountUSD:
description: The estimated resulting amount of the `toToken` in USD equivalent
type: string
approvalAddress:
description: The contract address for the approval
type: string
feeCosts:
description: Fees included in the transfer
type: array
items:
$ref: '#/components/schemas/FeeCost'
gasCosts:
description: Gas costs included in the transfer
type: array
items:
$ref: '#/components/schemas/GasCost'
executionDuration:
description: The time needed to complete the following step
type: number
data:
description: Arbitrary data that depends on the the used tool
type: object
properties:
bid:
type: object
properties:
user:
type: string
router:
# --- truncated at 32 KB (138 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/lifi/refs/heads/main/openapi/lifi-relayer-api-openapi.yml