Token Swap & Bridge

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.

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

Common Errors