π Best Practices
Supercharging your Swaps experience beyond the core capabilities.
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:
- Identify home chain (Base) and token (Ether)
- Identify starting swap amount ($100 = 0.06 ETH)
- Map to away chain (Solana) and token (SOL)
- Identify ending swap amount ($100 - 1.3% fee = $98.70 = .67 SOL)
- Identify users EVM wallet address
- Identify users Solana wallet address
- Receive funds
- 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:
- Prompt user for home chain (
fromNetworks
) and token (fromCurrencies
) - Identify starting swap amount (
fromAmount
) - Map to away chain (
toNetworks
) and token (toCurrencies
) - Identify ending swap amount (
toAmount
) - Display ending swap amount in real time
- Note: real-time currency conversions are done by you
- Prompt user to choose flow (
flow
) - Identify users EVM wallet address (
fromWalletAddress
), which can be used asrefundWalletAddress
in Execute a Swap as well. - When user clicks the βSwapβ button, you may request the
Get Swap Quote
endpoint - You will receive a signature response, which is to be passed into the Execute a Swap endpoint via the
signature
parameter. - Prompt user to send crypto to deposit wallet address via wallet signature request. Identify users Solana wallet address (
toWalletAddress
from Execute a Swap). - Once the user sends the crypto, you may begin requesting the Execute a Swap endpoint
- 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)

Updated about 1 month ago