On chain swap
How to execute on chain swap using Magpie APIs
Last updated
How to execute on chain swap using Magpie APIs
Last updated
There are two methods to execute a swap: gasless and self-execution.
The user executes the transaction and covers gas costs themselves.
Magpie executes the transaction on behalf of the user, covering the gas fees, so the user doesn’t need to hold or pay gas in the native currency.
In this step, you will retrieve a quote that contains details of the swap, including the estimated output amount, swap route, and other necessary transaction parameters.
Endpoint: /aggregator/quote
Method: GET
Required Parameters
fromTokenAddress: Address of the token you want to swap from.
If you want to use a native token, please use this address 0x0000000000000000000000000000000000000000
toTokenAddress: Address of the token you want to swap to.
If you want to use a native token, please use this address 0x0000000000000000000000000000000000000000
amount: The amount of the fromToken in the smallest unit (e.g., wei for ETH).
slippage: Allowed slippage percentage (e.g., 0.005 for 0.5%).
fromAddress: Wallet address initiating the swap.
toAddress: Wallet address receiving the swapped tokens.
gasless: Set true to let Magpie handle gas costs (gasless mode), or false if you will cover the gas cost.
enableRFQ: Optional parameter to enable RFQ protocols. Default is false
Affiliate Fee: API consumer can implement their own affiliate fees and define their affiliate address, the fees will be deducted from their user from the from asset (asset sold by their user) and distributed to the affiliate address in the same transaction. They can set an affiliate fee by including affiliateAddress and affiliateFee in the quote request. affiliateFee is the percentage fee, such as 1 for 1%.
This will return a quote-id and details like toTokenAmount (estimated output) and fees.
If you are swapping a token that is not the native token, you must first grant approval for the transaction. This requires calling the approve function on the token contract associated with the fromTokenAddress that you intend to swap.
When retrieving a quote via the endpoint, the response includes targetAddress. This address must be used as the spender when granting approval.
Based on the gasless option chosen in Step 1, there are two paths for transaction execution:
Self-Execution (gasless = false): The user retrieves transaction data and broadcasts the transaction themselves.
Gasless Transaction (gasless = true): Magpie executes the transaction on behalf of the user, covering the gas fees.
If gasless is set to false, you will need to execute the transaction on-chain by following these steps:
Endpoint: /aggregator/transaction
Method: GET
quoteId: Use the quote-id from Step 1 to retrieve the transaction data.
If gasless is set to true, Magpie will execute the transaction on behalf of the user.
Endpoint: /user-manager/execute-swap
Method: POST
networkName: The target network, where the transaction takes place.
quoteId: The quote-id from Step 1 is required to execute the swap.
swapSignature: Signed quote using EIP-712
permitSignature: Signed approval using EIP-2612
permitDeadline: The time at which the signature expires (unix time)
To generate a swapSignature using Ethers v5, follow these steps:
Obtain Parameters: Retrieve the message parameter from the response of quote API.
Generate the Signature: const signature = await signer._signTypedData(domain, types, message);
Magpie handles the swap and covers the gas fees. No additional action or gas payment is required from the user.
After initiating a swap, you can track its status using the following endpoints:
Get Swap Details
Endpoint: /user-manager/swap
Method: GET
Use this endpoint to retrieve the details of a completed swap.
Get Swap Status
Endpoint: /user-manager/status-counts
Method: GET
This endpoint provides the count of swaps in pending, error, or other states based on the wallet address.
Additional Endpoint: Get Distributions
You can check the route and distribution of the swap using the quote-id from Step 1.Endpoint: /aggregator/distributionsMethod: GETAvailable Networks: Magpie supports swaps on networks like Ethereum, Polygon, Avalanche, and others (BSC, Arbitrum, zkSync, etc.).
Example Request:
