debridge-swap

name	debridge-swap
description	Execute token swaps, bridges, and cross-chain transfers via deBridge DLN. Use this skill whenever the user wants to move, send, swap, exchange, trade, convert, or bridge tokens — whether on the same chain or across different chains (EVM-to-EVM, EVM-to-Solana, any L2-to-L2). This skill handles the full lifecycle: token lookup, quoting, amount conversion, balance checks, transaction signing, execution, and order tracking. IMPORTANT: Trigger this skill even for casual or indirect requests about moving tokens between wallets or chains. Common patterns include: "swap X for Y", "bridge tokens from A to B", "move my USDC to Base", "send ETH to Solana", "trade BNB for USDT on BSC", "how much to bridge from Polygon to Optimism", "convert DAI to USDC on Arbitrum", "exchange my tokens", "transfer to a cheaper L2", "what's the rate for swapping", "get me a quote", and any mention of moving crypto between chains or swapping one token for another. Also triggers for order monitoring: "my order is stuck", "check DLN order status", "track my bridge transaction", "order stuck on Created". If the user mentions specific token names (USDC, ETH, USDT, DAI, SOL, BNB, MATIC, AVAX) alongside any intent to move, send, swap, or trade them — use this skill.
license	MIT
metadata	{"author":"deBridge","version":"0.2.0"}

Token Swap & Bridge

PREREQUISITE: Read ../common/SKILL.md for environment detection, auth, and chain configuration.

Quick Reference

Want to...	Go to
Look up chain IDs / tokens	../common/chain-config.md
Run preflight checks	preflight.md
Sign and send transaction	../signing/SKILL.md
Track cross-chain order	monitoring.md
SDK workflow (coming soon)	Not yet available — use MCP

MCP Availability Check

Before starting, verify MCP is connected:

1. Call mcp__debridge__get_supported_chains (no parameters).

2. If it returns chain data → MCP is ready. Continue below.

3. If tool not found → MCP not connected. Set up the connection:

   • Streamable HTTP (preferred): claude mcp add --transport http debridge https://agents.debridge.com/mcp
   • Stdio proxy (fallback): claude mcp add debridge npx -- -y @debridge-finance/debridge-mcp@latest

   Both require restarting the session. For full setup details: read ACCESS_SETUP in ../common/SKILL.md or ../common/mcp-setup.md.

Routing Decision

Determine whether this is a same-chain or cross-chain operation:

• Source and destination on the same chain → same-chain swap. Go to Same-Chain Swap.
• Source and destination on different chains → cross-chain swap/bridge. Go to Cross-Chain Swap.

---

Same-Chain Swap

Step 1: Resolve Tokens

Look up token addresses and decimals on the swap chain.

Call mcp__debridge__search_tokens:
  - query: "USDC"              (NOT "search" — the parameter is "query")
  - chainId: "42161"           (string, NOT number)

Repeat for the output token. Record address and decimals.

Step 2: Build Swap Transaction

Call mcp__debridge__transaction_same_chain_swap:
  - chainId:           "42161"               (string, chain deBridge ID)
  - tokenIn:           "0xaf88...e5831"      (input token address)
  - tokenInAmount:     "1000000000"          (amount in raw units — see Amount Conversion)
  - tokenOut:          "0x0000...0000"       (output token address)
  - tokenOutRecipient: "0xYourAddress"       (recipient address on the same chain)

Optional parameters:

• slippage — tolerance or "auto" (default: auto)
• tokenOutAmount — expected output or "auto"
• senderAddress — transaction submitter address
• affiliateFeePercent / affiliateFeeRecipient — affiliate fees

All parameters are strings. Do NOT pass numbers for chain IDs.

Response Format

The response includes:

• tx — the transaction object to sign and send (format depends on chain, see below)
• tokenIn / tokenOut — token metadata with amount, minAmount, approximateUsdValue
• slippage / recommendedSlippage — applied and recommended slippage (bps)
• estimatedTransactionFee — gas estimate with total (in raw native units) and approximateUsdValue
• comparedAggregators — price comparison with other DEX aggregators
• costsDetails — detailed fee breakdown

EVM chains — tx contains {to, data, value}:

{
  "tx": { "to": "0x663D...c251", "data": "0x258c...", "value": "0" },
  "tokenOut": { "amount": "10027065", "minAmount": "10019037", ... }
}

Solana (chain ID 7565164) — tx contains {data} only (hex-encoded serialized transaction):

{
  "tx": { "data": "0x01000000..." },
  "tokenOut": { "amount": "87206972", "minAmount": "86927910", ... }
}

Solana transactions are fully serialized — pass tx.data to the Solana signing pipeline (see ../signing/ows-signing.md for OWS Solana flow).

Step 3: Preflight Checks

Read preflight.md before proceeding.

Checks: balance, allowance (for ERC-20 input on EVM), and gas budget.

Step 4: Sign and Send

Read ../signing/SKILL.md — it detects the available signer and routes to the correct signing method.

1. If ERC-20 input on EVM and allowance insufficient → sign and send approval tx first. Wait for 1 confirmation.
2. Sign and send the swap tx.

Same-chain swaps settle in a single transaction. No monitoring step needed — the tx receipt confirms completion.

---

Cross-Chain Swap

Cross-chain swaps (also called bridges or cross-chain transfers) move tokens between different blockchains.

Non-EVM Destinations

Solana (deBridge chain ID 7565164):

• Recipient addresses are base58 (e.g., Gh9ZwEm...), not hex — validate format before calling create_tx.
• Native token (SOL) address: 11111111111111111111111111111111 (32 ones).
• Token amounts still use raw units but SOL has 9 decimals, not 18.

Tron (deBridge chain ID 100000026):

• Recipient addresses are base58check (e.g., T9yD14N...), starting with T — not the same encoding as Solana.
• Native token (TRX) has 6 decimals.

For both: the source side (EVM) follows the normal EVM flow — approval if needed on the source chain, then sign and send. The approveTx from create_tx is always a source-chain operation.

Step 1: Resolve Tokens

Look up token addresses and decimals on source and destination chains.

Call mcp__debridge__search_tokens:
  - query: "USDC"               (NOT "search" — the parameter is "query")
  - chainId: "1"                (string, NOT number)

Repeat for destination chain. Record address and decimals from the response.

For native tokens (ETH, BNB, etc.), use the zero address from ../common/chain-config.md. For Solana native token (SOL), use 11111111111111111111111111111111.

Step 2: Build Transaction

Call mcp__debridge__create_tx:
  - srcChainId:                    "1"                    (string, source chain deBridge ID)
  - srcChainTokenIn:               "0xA0b8...eB48"       (source token address)
  - srcChainTokenInAmount:         "100000000"            (amount in raw units — see Amount Conversion)
  - dstChainId:                    "42161"                (string, destination chain deBridge ID)
  - dstChainTokenOut:              "0xaf88...e5831"       (destination token address)
  - dstChainTokenOutRecipient:     "0xRecipient..."       (recipient on destination chain)
  - srcChainOrderAuthorityAddress: "0xSender..."          (REQUIRED — sender's address on source chain)
  - dstChainOrderAuthorityAddress: "0xRecipient..."       (REQUIRED — recipient's address on destination chain)

All parameters are strings. Do NOT pass numbers for chain IDs.

Optional parameters:

• dstChainTokenOutAmount — expected output amount or "auto" for best quote (default: auto)
• prependOperatingExpenses — set true to add estimated operating expenses to the input amount
• affiliateFeePercent / affiliateFeeRecipient — affiliate fees

The response from create_tx includes:

• tx — the main transaction object (to, data, value, chainId)
• approveTx — token approval transaction (if ERC-20 allowance is insufficient)
• orderId — the DLN order ID for tracking
• Estimated output amount and fees

Step 3: Preflight Checks

Read preflight.md before proceeding.

Preflight checks:

• Source token balance
• Token allowance (for ERC-20)
• Native token balance for gas
• Slippage tolerance

Step 4: Sign and Send

Read ../signing/SKILL.md — it detects the available signer and routes to the correct signing method.

Execution order:

1. If approveTx is present → sign and send approval first. Wait for 1 confirmation.
2. Sign and send the main tx. Record the transaction hash.

Step 5: Monitor

Read monitoring.md to track the DLN order from creation to fulfillment on the destination chain.

---

Amount Conversion

All amounts must be in raw units (smallest indivisible unit) as strings.

raw_units = human_amount × 10^decimals

Example: 100 USDC (6 decimals) → "100000000"

See ../common/chain-config.md for decimals and conversion table.

Bundled Scripts

The ../common/scripts/ directory has TypeScript helpers that handle amount conversion, balance checks, allowances, and approvals. All scripts auto-discover RPC endpoints from Chainlist and read token decimals on-chain.

Script	Purpose	Example
convert-amount.ts	Convert human ↔ raw units	npx tsx ../common/scripts/convert-amount.ts 100 0xA0b8...eB48 1
balance.ts	Query native or ERC-20 balance	npx tsx ../common/scripts/balance.ts 0xAddr 42161 --token 0xToken
allowance.ts	Check ERC-20 allowance	npx tsx ../common/scripts/allowance.ts 0xToken 0xOwner 0xSpender 1 --check 100
approve.ts	Send ERC-20 approval tx	npx tsx ../common/scripts/approve.ts 0xToken 0xSpender 1 --amount 1000
rpc.ts	Discover RPC from Chainlist	npx tsx ../common/scripts/rpc.ts 42161 --json

All scripts support --json for machine-readable output and --rpc <url> to override RPC discovery.

Common Errors

Error	Cause	Fix
No route found	Token pair not supported on chains	Check get_supported_chains and search_tokens
Insufficient allowance	Preflight should catch this	Send approval tx first, then retry
Slippage exceeded	Price moved during execution	Re-call create_tx or transaction_same_chain_swap for fresh quote
Amount too small	Below minimum amount	Increase amount or check minimum
Insufficient liquidity	Pool too small for amount	Reduce amount or try a different pair
Destination chain unsupported	Wrong chain ID format	Use deBridge chain IDs from ../common/chain-config.md