This article is supposed to be a primer on designing a bridge API that integration partners can work with. This article doesn’t aim to educate on how to build RESTful APIs, but we recommend to take a deep look into all the different parts that improve the quality of an API from compression, caching, versioning, following best practices.

As a bridge aggregation protocol we’ve seen and assed many bridge APIs and feel to be in a good position to suggest the following endpoints.

Context

LI.FI integrates all bridges in a backend, requests quotes for the user and parses them in the same way. The user gets a transaction to execute and checks a status endpoint in the LI.FI API which again will forward information of the bridge.

On-Chain the user sends a transaction to the LI.FI Diamond contract, which forwards tokens and parameters to the bridge. The contract needs to be able to verify that the receiver, receiving chain and be update the amount of tokens that will be bridged.

Refunds have to be made to the users wallet, never to the LI.FI contract.

Route discovery

Our system periodically checks which assets, chains, routes are available. This information is used in our routing to decide which tools to query for pricing information. Response times for those endpoints are not that important as they are used in worker jobs.

• get available routes between chains, including

  • supported tokens
  • min/max transfer size, available liquidity
  • estimated duration
  • fees

  Suggested URI: /routes

• (optional) get bridge configs

  • fee parameters / calculation
  • confirmations per chain required / duration
  • used contract addresses
  • ABIs

  Suggested URI: /config

Quoting

Live price of a

• get quote for a specific transfer Similar to our quote endpoint: https://apidocs.li.fi/reference/get_v1-quote We request with:

  • fromChain
  • toChain
  • fromToken
  • toToken
  • toAddress (receiver)
  • fromAmount
  • slippage (0.005 represents 0.5%)

  And expect a response containing:

  • toAmount (expected output)

  • toAmountMin (minimal output possible because of slippage)

  • executionDuration (how many seconds will the transfer take after the source transactions is mined)

  • gasEstimate (how many gas units does the interaction with your contract require)

  • feeCosts (array of costs)

    // Example: fee is deducted from sent amount
    {
      "name": "Relayer fee",
      "description": "The fee taken by the relayer",
      "chainId": 1,
      "tokenAddress": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    	"amount": "86770",
    	"included": true // is the fee deducted automatically from the amount the user is passing?
    }
    
    // Example: additional native fee sent along with the transaction
    {
    	"name": "LayerZero fees",
    	"description": "Infrastructure fee paid in native token",
    	"chainId": 1,
    	"tokenAddress": "0x0000000000000000000000000000000000000000",
    	"amount": "352992055059579",
    	"included": false
    }
    
    

  • parameters needed to be passed to your contract (not the compiled callData)

  • (optional) deadline (if the rate expires after some time)

  Suggested URI: GET /quote

Transfer Status

After an executed a transfer on-chain we will index it and check your API for the bridging status. We periodically call this endpoint to check if the funds were received on the destination chain.

• get status of submitted transfer based on submitted transaction hash on the source chain Gathers information for our https://apidocs.li.fi/reference/get_v1-status endpoint

  Expected Response:

  • status
  • substatus (see https://docs.li.fi/introduction/user-flows-and-examples/status-tracking)
  • receiving:
    • txHash
    • chainId
    • tokenAddress
    • tokenAmount

  Suggested URI: GET /transaction/{txHash}

Other optional endpoints

• optional: get overall bridge status (uptime, changes, planned maintenance, …) Suggested URI: /health