Skip to main content

Workflow

This guide describes the recommended step-by-step workflow for executing swaps through the Xplore MCP Server.

Swap Workflow​

Step 1: Resolve Chains​

Call get_supported_chains to list supported blockchain networks and map user-friendly chain names (e.g., "Ethereum", "Solana") to numeric chain IDs.

Step 2: Resolve Tokens​

Call search_tokens with the token name or symbol (e.g., "USDC", "ETH") and the relevant chainId to get the token's contract address and decimals.

tip

Always confirm the correct token with the user when multiple results are returned.

Step 3: Get a Quote​

Call get_quote with the source and destination chain IDs, token addresses, amount in smallest units, and the sender's wallet address.

  • Works for both same-chain swaps (fromChain == toChain) and cross-chain swaps
  • The response includes the estimated output amount, fees, and route details
  • Present the quote to the user before proceeding

Step 4: Create Transaction​

When the user is ready to execute, call create_transaction with the same parameters. This returns full route details with populated transaction data ready for signing and submission.

Call get_dapp_url with the chain IDs, token addresses, the human-readable amount (not in smallest units), and the recipient address (if known) to produce a URL. Share this URL with the user so they can review and execute the swap in the Router Protocol App.

Step 6: Track Transaction​

After the user submits a transaction, call check_transaction_status with the transaction hash to monitor progress. The status will be PENDING, DONE, or FAILED.

Route Discovery (Optional)​

Before quoting, you can optionally explore available routes:

  • Call get_connections to check what token pairs and routing tools are available between two chains
  • Call get_tools to see which bridges and DEX exchanges are available for routing

Tips​

  • Always resolve token addresses via search_tokens rather than guessing addresses
  • Convert amounts to smallest units (wei, lamports) for get_quote and create_transaction, but use human-readable decimals for get_dapp_url
  • Use 0x0000000000000000000000000000000000000000 as the token address for native tokens (ETH, BNB, MATIC, etc.) on EVM chains
  • Present the estimated output and fees from get_quote to the user before proceeding
  • For same-chain swaps, set toChain equal to fromChain

Example Flow​

Here's a typical interaction for swapping 1 ETH from Ethereum to USDC on Arbitrum:

  1. Get chains — get_supported_chains returns Ethereum (chain ID 1) and Arbitrum (chain ID 42161)
  2. Get tokens — search_tokens with query ETH and chainId 1 returns the native token address; search_tokens with query USDC and chainId 42161 returns the USDC contract address
  3. Get quote — get_quote with the resolved chain IDs, token addresses, fromAmount of 1000000000000000000 (1 ETH in wei), and wallet addresses
  4. Show quote — Present the estimated USDC output and fees to the user
  5. Create transaction — create_transaction with the same parameters to get the signed transaction data
  6. Generate link — get_dapp_url with amount 1 (human-readable) for the user to execute in their browser
  7. Track — check_transaction_status with the submitted transaction hash