Token Swaps

The swap system allows you to exchange one token for another. You can swap tokens on the same chain or perform cross-chain swaps. This guide covers how to get swap quotes and execute swaps.

Overview

The swap system provides:

  • Token Swaps - Exchange one token for another
  • Cross-Chain Swaps - Swap tokens across different chains
  • Quote System - Get quotes before executing swaps
  • Automatic Execution - Execute swaps with transaction signing

Prerequisites

Before making swaps, ensure you have:

  • Completed authentication and have a valid access token
  • Created a wallet
  • Have sufficient balance of the token you want to swap

Get Swap Quote

Get a quote for swapping tokens. This shows you the expected output amount, exchange rate, and fees before executing the swap.

Get swap quote

curl -X POST https://api.example.com/api/swap/quote \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: {tenant-id}" \
  -d '{
    "amountIn": "1.0",
    "tokenIn": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "chainIdIn": 137,
    "tokenOut": "0x7ceb23fd6fc0adc59cf2b2c9c0c0c0c0c0c0c0c0",
    "chainIdOut": 137
  }'

Required Fields:

  • amountIn - Amount of input token to swap (humanized format, e.g., "1.0" for 1 token)
  • tokenIn - Input token contract address
  • chainIdIn - Chain ID where input token is located
  • tokenOut - Output token contract address
  • chainIdOut - Chain ID where output token will be received

Response:

{
  "status": 200,
  "message": "Swap quote retrieved successfully",
  "data": {
    "quote": {
      "quoteId": "quote-id-123",
      "amountIn": "1.0",
      "amountOut": "2.0",
      "tokenIn": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
      "tokenOut": "0x7ceb23fd6fc0adc59cf2b2c9c0c0c0c0c0c0c0c0",
      "chainIdIn": 137,
      "chainIdOut": 137,
      "userOperationHash": "0xabcdef...",
      "exchangeRate": "2.0",
      "fee": "0.5"
    },
    "tokenInPrice": {
      "usd": 1.0,
      "brl": 5.0
    },
    "tokenOutPrice": {
      "usd": 2000.0,
      "brl": 10000.0
    }
  }
}

Response Fields:

  • quote - Swap quote details
    • quoteId - Unique quote identifier
    • amountIn - Input amount
    • amountOut - Expected output amount
    • tokenIn - Input token address
    • tokenOut - Output token address
    • chainIdIn - Input chain ID
    • chainIdOut - Output chain ID
    • userOperationHash - Hash for executing the swap
    • exchangeRate - Exchange rate
    • fee - Transaction fee percentage
  • tokenInPrice - Input token price (USD and BRL)
  • tokenOutPrice - Output token price (USD and BRL)

Execute Swap

Execute a swap using a quote ID obtained from the quote endpoint.

Execute swap

curl -X POST https://api.example.com/api/swap/execute \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: {tenant-id}" \
  -d '{
    "quoteId": "quote-id-123",
    "chainInId": 137
  }'

Required Fields:

  • quoteId - Quote ID from the quote endpoint (this is the userOperationHash)
  • chainInId - Chain ID where the input token is located

Response:

{
  "status": 200,
  "message": "Swap executed successfully",
  "data": {
    "signature": "0x...",
    "message": "..."
  }
}

Response Fields:

  • signature - Transaction signature data
  • message - Signed message

Note: The swap transaction is signed automatically. Use the signature data to execute the transaction on-chain.

Swap Flow

  1. Get Quote - Call the quote endpoint to get swap details and expected output
  2. Review Quote - Check the exchange rate, fees, and expected output amount
  3. Execute Swap - Use the quote ID to execute the swap
  4. Transaction Signed - The system automatically signs the transaction
  5. Complete - Use the signature to execute the transaction on-chain

Cross-Chain Swaps

You can swap tokens across different chains:

curl -X POST https://api.example.com/api/swap/quote \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: {tenant-id}" \
  -d '{
    "amountIn": "1.0",
    "tokenIn": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "chainIdIn": 137,
    "tokenOut": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "chainIdOut": 1
  }'

This example swaps USDC on Polygon (chain 137) to USDC on Ethereum (chain 1).

Amount Format

Amounts should be provided in humanized format (decimal number as string). The API automatically converts the humanized amount to the token's smallest unit based on the token's decimals:

  • ETH and most tokens: Provide amount as decimal (e.g., "1.0" for 1 ETH, "0.5" for 0.5 ETH)
  • USDC/USDT: Provide amount as decimal (e.g., "1000.0" for 1000 USDC)
  • Other tokens: Provide amount as decimal string

Examples:

  • 1 ETH = "1.0"
  • 1000 USDC = "1000.0"
  • 0.5 ETH = "0.5"

Fees

Swap fees are deducted from the input amount:

  • Transaction Fee - A percentage fee (configurable per tenant)
  • Gas Fee - Network gas fees (deducted from amount)
  • Exchange Rate - Includes all fees in the calculation

The quote shows the final amount you'll receive after all fees.

Error Handling

Wallet Not Found

{
  "status": 404,
  "message": "Wallet not found"
}

This error occurs when you haven't created a wallet yet.

Invalid Chain

{
  "status": 400,
  "message": "Invalid chain in"
}

or

{
  "status": 400,
  "message": "Invalid chain out"
}

This error occurs when the chain ID is not supported.

Invalid Amount

{
  "status": 400,
  "message": "Amount in must be greater than 0"
}

This error occurs when the amount is missing or less than or equal to 0.

Token Required

{
  "status": 400,
  "message": "Token in and token out is required"
}

This error occurs when token addresses are missing.

Same Token

{
  "status": 400,
  "message": "Token in and token out cannot be the same"
}

This error occurs when trying to swap the same token on the same chain.

Token Not Found

{
  "status": 404,
  "message": "Token in not found on the list"
}

or

{
  "status": 404,
  "message": "Token out not found on the list"
}

This error occurs when the token address is not supported.

Insufficient Balance

{
  "status": 400,
  "message": "Insufficient balance to swap"
}

This error occurs when you don't have enough balance of the input token.

No Quotes Found

{
  "status": 404,
  "message": "No quotes found"
}

This error occurs when no swap routes are available for the requested pair.

Error Signing Transaction

{
  "status": 500,
  "message": "Error signing transaction"
}

This error occurs when there's an issue signing the swap transaction.

Complete Flow Example

Here's a complete example of swapping tokens:

# 1. Get swap quote
curl -X POST https://api.example.com/api/swap/quote \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: {tenant-id}" \
  -d '{
    "amountIn": "1.0",
    "tokenIn": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "chainIdIn": 137,
    "tokenOut": "0x7ceb23fd6fc0adc59cf2b2c9c0c0c0c0c0c0c0c0",
    "chainIdOut": 137
  }'

# 2. Execute swap using quoteId from step 1
curl -X POST https://api.example.com/api/swap/execute \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -H "x-tenant-id: {tenant-id}" \
  -d '{
    "quoteId": "quote-id-from-step-1",
    "chainInId": 137
  }'

# 3. Use signature data to execute transaction on-chain

Important Notes

  1. Quote Expiration: Quotes may expire after a certain time. Execute swaps promptly after getting a quote.

  2. Balance Validation: The system validates your balance before providing a quote. Ensure you have sufficient balance.

  3. Price Information: Quotes include current token prices in USD and BRL for reference.

  4. Cross-Chain Support: You can swap tokens across different chains. The system handles bridge operations automatically.

  5. Gas Fees: Gas fees are deducted from the swap amount. The quote shows the final amount you'll receive.

  6. Transaction Fees: A percentage fee is applied to swaps. The fee is included in the quote.

  7. Same Chain Swaps: You can swap tokens on the same chain for faster execution.

  8. Token Validation: Only supported tokens can be swapped. Check the tokens list for available tokens.

  9. Automatic Signing: Swap transactions are automatically signed. You receive signature data to execute on-chain.

  10. Exchange Rates: Exchange rates are calculated based on current market conditions and may vary.

  11. Quote ID: The quoteId is actually the userOperationHash. Use it directly in the execute endpoint.

  12. Amount Format: Always provide amounts in humanized format (decimal string). The API automatically handles conversion to the token's smallest unit based on token decimals.

Security Considerations

  1. Verify Quotes: Always review the quote before executing to ensure amounts and rates are correct.

  2. Check Balances: Verify you have sufficient balance before getting quotes.

  3. Monitor Transactions: Track your swap transactions to ensure they complete successfully.

  4. Price Impact: Large swaps may have price impact. Consider splitting large swaps into smaller ones.

  5. Slippage: Exchange rates may change between quote and execution. The quote provides an estimate.

  6. Network Conditions: Cross-chain swaps may take longer depending on network conditions.

Was this page helpful?