$npx -y skills add moonpay/skills --skill moonpay-swap-tokensSwap tokens on the same chain or bridge tokens across chains. Use when the user wants to swap, bridge, or move tokens.
| 1 | # Swap or bridge tokens |
| 2 | |
| 3 | ## Goal |
| 4 | |
| 5 | Swap tokens on the same chain, or bridge tokens across chains. Two commands: |
| 6 | |
| 7 | - **`mp token swap`** — same chain, different tokens |
| 8 | - **`mp token bridge`** — cross chain |
| 9 | |
| 10 | Both build via swaps.xyz, sign locally, broadcast, and register for tracking. |
| 11 | |
| 12 | ## Commands |
| 13 | |
| 14 | ### Swap (same chain) |
| 15 | |
| 16 | ```bash |
| 17 | mp token swap \ |
| 18 | --wallet <wallet-name> \ |
| 19 | --chain <chain> \ |
| 20 | --from-token <token-address> \ |
| 21 | --from-amount <amount> \ |
| 22 | --to-token <token-address> |
| 23 | ``` |
| 24 | |
| 25 | Supports exact-out: use `--to-amount` instead of `--from-amount`. |
| 26 | |
| 27 | ### Bridge (cross chain) |
| 28 | |
| 29 | ```bash |
| 30 | mp token bridge \ |
| 31 | --from-wallet <wallet-name> \ |
| 32 | --from-chain <chain> \ |
| 33 | --from-token <token-address> \ |
| 34 | --from-amount <amount> \ |
| 35 | --to-chain <chain> \ |
| 36 | --to-token <token-address> \ |
| 37 | --to-wallet <wallet-name> # optional, defaults to from-wallet |
| 38 | ``` |
| 39 | |
| 40 | Supports exact-out: use `--to-amount` instead of `--from-amount`. |
| 41 | |
| 42 | ## Examples |
| 43 | |
| 44 | ### Same-chain swap (SOL → USDC on Solana) |
| 45 | |
| 46 | ```bash |
| 47 | mp token swap \ |
| 48 | --wallet main --chain solana \ |
| 49 | --from-token So11111111111111111111111111111111111111111 \ |
| 50 | --from-amount 0.1 \ |
| 51 | --to-token EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v |
| 52 | ``` |
| 53 | |
| 54 | ### Cross-chain bridge (ETH → USDC.e on Polygon) |
| 55 | |
| 56 | ```bash |
| 57 | mp token bridge \ |
| 58 | --from-wallet funded --from-chain ethereum \ |
| 59 | --from-token 0x0000000000000000000000000000000000000000 \ |
| 60 | --from-amount 0.003 \ |
| 61 | --to-chain polygon \ |
| 62 | --to-token 0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174 |
| 63 | ``` |
| 64 | |
| 65 | ### ERC20 swap (auto-approves if needed) |
| 66 | |
| 67 | ```bash |
| 68 | mp token swap \ |
| 69 | --wallet funded --chain polygon \ |
| 70 | --from-token 0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174 \ |
| 71 | --from-amount 5 \ |
| 72 | --to-token 0x0000000000000000000000000000000000000000 |
| 73 | ``` |
| 74 | |
| 75 | ## Supported chains |
| 76 | |
| 77 | solana, ethereum, base, polygon, arbitrum, optimism, bnb, avalanche, bitcoin (bridges only) |
| 78 | |
| 79 | ## How it works |
| 80 | |
| 81 | 1. Resolves wallet name → address |
| 82 | 2. Builds unsigned transaction via swaps.xyz (handles decimal conversion) |
| 83 | 3. If ERC20 token needs approval, sends an approve transaction first, then re-builds |
| 84 | 4. Signs locally — private key never leaves the machine |
| 85 | 5. Broadcasts to the network |
| 86 | 6. Registers for tracking |
| 87 | |
| 88 | `token swap` calls `token bridge` under the hood with `from-chain` = `to-chain`. |
| 89 | |
| 90 | ## Tips |
| 91 | |
| 92 | - If the user provides token names/symbols, resolve to addresses with `mp token search --query "USDC" --chain solana` |
| 93 | - Check balances first with `mp token balance list --wallet <address> --chain <chain>` |
| 94 | - Native tokens use `0x0000000000000000000000000000000000000000` (EVM) or `So11111111111111111111111111111111111111111` (Solana) |
| 95 | |
| 96 | ## Related skills |
| 97 | |
| 98 | - **moonpay-discover-tokens** — Search for token addresses |
| 99 | - **moonpay-check-wallet** — Check balances before swapping |
| 100 | - **moonpay-auth** — Set up wallets for signing |