🏆 Best Practices

In order to get the most out of your Swaps integration, we recommend optimizing your user experience using our best practices, outlined below.

The Base Flow

In setting up their swaps, users respond best to a chronological flow. In other words, the setup experience should closely reflect the swap flow.

If we want to swap $100 Ether on Base to SOL on Solana, the high-level swap flow under the hood is:

1. Identify home chain (Base) and token (Ether)
2. Identify starting swap amount ($100 = 0.06 ETH)
3. Map to away chain (Solana) and token (SOL)
4. Identify ending swap amount ($100 - 1.3% fee = $98.70 = .67 SOL)
5. Identify users EVM wallet address
6. Identify users Solana wallet address
7. Receive funds
8. Execute swap

Thus, the setup of the swap should reflect this chronological process. Let’s go through the simple two-endpoint flow whilst outlining the parameters we use, as well as when we use them:

1. Prompt user for home chain (fromNetworks) and token (fromCurrencies)
2. Identify starting swap amount (fromAmount)
3. Map to away chain (toNetworks) and token (toCurrencies)
4. Identify ending swap amount (toAmount)
5. Display ending swap amount in real time
   1. Note: real-time currency conversions are done by you
6. Prompt user to choose flow (flow)
7. Identify users EVM wallet address (fromWalletAddress), which can be used as refundWalletAddress in Execute a Swap as well.
8. When user clicks the “Swap” button, you may request the Get Swap Quote endpoint
9. You will receive a signature response, which is to be passed into the Execute a Swap endpoint via the signature parameter.
10. Prompt user to send crypto to deposit wallet address via wallet signature request. Identify users Solana wallet address (toWalletAddress from Execute a Swap).
11. Once the user sends the crypto, you may begin requesting the Execute a Swap endpoint
12. Swap complete

Note: All parameters mentioned are from the Get Swap Quote endpoint unless otherwise noted.

Improving the Core Flow with Additional Endpoints

To supercharge your Swaps integration, we have a suite of endpoints additional to the ones responsible for core functionality that can be used.

Get Currencies Info

The Get Currencies Info endpoint can be used to retrieve information on which tokens are supported on Swaps.

For optimal use, this may be queried and subsequently cached semi-frequently, as they will not change incredibly often, and they will be requested for virtually every Swaps user flow.

This will return a JSON blob full of tokens, each formatted as such:

  {
    "id": "db1832a7-8fa2-4461-bc28-3badc6a1695a",
    "name": "Bitcoin",
    "code": "btc",
    "isEnabled": true,
    "imageUrl": "https://pretty-picture-g2.s3.eu-central-1.amazonaws.com/btc_607160f243_2f3129064d.svg",
    "requiresExtraTag": false
  }

Get Networks Info

The Get Networks Info endpoint is recommended to retrieve information on Swaps-supported networks.

For optimal use, this may be queried and subsequently cached semi-frequently, as they will not change incredibly often, and they will be requested for virtually every Swaps user flow.

This will return a JSON blob of networks, each formatted as such:

  {
    "id": "84473f00-16bb-4cdb-a7f2-5c9313a53893",
    "name": "sol",
    "code": "sol",
    "addressUrl": null,
    "transactionUrl": null,
    "imageUrl": null,
    "addressRegex": null,
    "addressTagRegex": null
  }

Surfacing Swap Transaction Status to Users

You may use the Get Swap Transaction with Status endpoint to continuously update users with the latest information on their transaction.

We recommend requesting the endpoint once every fifteen seconds, as swaps typically take around 2-3 minutes to fully complete. The API response will come back in JSON as such:

{
  "id": "180244ac-9e04-4982-97a1-aab0b6abee15",
  "fromCurrencies": "sol",
  "fromAmount": "0.10000",
  "fromNetworks": "sol",
  "fromWalletAddress": "8LfqWPPedAVpz9en46qhSZRMMTH6nRxAnVjkekkNQa5b",
  "fromWalletAddressExtra": null,
  "toCurrencies": "eth",
  "toAmount": "0.00825",
  "toNetworks": "eth",
  "toWalletAddress": "0x985DFb829B20b36667D431ab9f126b1FE7100d01",
  "toWalletAddressExtra": "",
  "status": "pending",
  "depositAddress": "2HQgqtMpBXEfjbUokJ67UpPNgnL9sZs9yzkSj2htVVV9",
  "depositExtraId": null
}

Other Best Practice Considerations

• We recommend re-quoting your amounts once every ten seconds to ensure that user expectations are met. Pairing this with a visual indicator as to when the re-quote will take place is highly recommended.
• Allowing users to switch between fiat and crypto when specifying swap amount increases usability of your app and raises the chance that a given user will retain through a full swap.
• Most users think in fiat. As such, it is important to ensure that you always display corresponding dollar amounts to the crypto amounts your users are working with (within "From" box, within "To" box, etc.).
• Enabling From/To currency switching creates better UX for users who mistakenly enter the chains 'backwards' (example shown below)