Cross-chain swaps let you convert tokens across different blockchain networks in a single transaction. They’re built natively into Smart Wallets and you can integrate in minutes.

Cross-chain swaps work just like any other Smart Wallet transaction, so you can sponsor gas to do gasless swaps, or pay for gas in an ERC-20 token.

The Cross-chain Swap flow

Flow

1. Request a cross-chain swap quote
2. Sign the prepared swap calls
3. Send prepared calls
4. Wait for cross-chain confirmation

Swap options

When requesting a cross-chain swap quote, you can specify either a fromAmount , or a minimumToAmount.

1
// Mode 1: Swap exact input amount
2
{
3
  fromAmount: "0x2710";
4
} // Swap exactly 0.01 USDC (10000 in hex, 6 decimals)
5
6
// Mode 2: Get minimum output amount
7
{
8
  minimumToAmount: "0x5AF3107A4000";
9
} // Get at least 0.0001 ETH (18 decimals). The amount you need to spend is calculated to get at least your desired ETH amount.

Prerequisites

Before you begin, ensure you have:

• An Alchemy API Key
• If you’re sponsoring gas, then a Gas Manager policy
• A small amount of tokens for testing (~$1 worth is enough!)
  • Important: You’ll need to send these tokens to your smart wallet address to be able to swap!
• A signer to own the account and sign messages

$
curl -X POST https://api.g.alchemy.com/v2/{API_KEY} \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "jsonrpc": "2.0",
>
    "id": 1,
>
    "method": "wallet_requestAccount",
>
    "params": [
>
      {
>
        "signerAddress": "{SIGNER_ADDRESS}"
>
      }
>
    ]
>
  }'

1
{
2
  "jsonrpc": "2.0",
3
  "id": 1,
4
  "result": {
5
    "accountAddress": "ACCOUNT_ADDRESS",
6
    "id": "ACCOUNT_ID"
7
  }
8
}

$
curl -X POST https://api.g.alchemy.com/v2/{API_KEY} \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "jsonrpc": "2.0",
>
    "id": 1,
>
    "method": "wallet_requestQuote_v0",
>
    "params": [
>
      {
>
        "from": "{ACCOUNT_ADDRESS_FROM_STEP_1}",
>
        "chainId": "{SOURCE_CHAIN_ID}",
>
        "toChainId": "{DESTINATION_CHAIN_ID}",
>
        "fromToken": "{FROM_TOKEN}",
>
        "toToken": "{TO_TOKEN}",
>
        "fromAmount": "{FROM_AMOUNT_HEXADECIMAL}",
>
        "capabilities": {
>
          "paymasterService": {
>
            "policyId": "{PAYMASTER_POLICY_ID}"
>
          }
>
        }
>
      }
>
    ]
>
  }'

1
{
2
  "jsonrpc": "2.0",
3
  "id": 0,
4
  "result": {
5
    "rawCalls": false,
6
    "chainId": "...",
7
    "callId": "0x...",
8
    "quote": {
9
      "expiry": "EXPIRY",
10
      "minimumToAmount": "MINIMUM_TO_AMOUNT",
11
      "fromAmount": "FROM_AMOUNT"
12
    },
13
    "type": "user-operation-v070",
14
    "data": "USER_OPERATION_DATA",
15
    "signatureRequest": {
16
      "type": "personal_sign",
17
      "data": {
18
        "raw": "..."
19
      },
20
      "rawPayload": "..."
21
    },
22
    "feePayment": {
23
      "sponsored": true,
24
      "tokenAddress": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
25
      "maxAmount": "..."
26
    }
27
  }
28
}

$
curl -X POST https://api.g.alchemy.com/v2/{API_KEY} \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "jsonrpc": "2.0",
>
    "method": "wallet_sendPreparedCalls",
>
    "params": [
>
      {
>
        "callId": "{CALL_ID_FROM_STEP_2}",
>
        "type": "user-operation-v070",
>
        "data": "{DATA_FROM_STEP_2}",
>
        "chainId": "{SOURCE_CHAIN_ID}",
>
        "signature": {
>
          "type": "secp256k1",
>
          "data": "{SIGNATURE_FROM_STEP_3}"
>
        }
>
      }
>
    ],
>
    "id": 1
>
  }'

1
{
2
  "jsonrpc": "2.0",
3
  "id": "1",
4
  "result": {
5
    "preparedCallIds": ["PREPARED_CALL_ID"]
6
  }
7
}

$
curl -X POST https://api.g.alchemy.com/v2/{API_KEY} \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "jsonrpc": "2.0",
>
    "method": "wallet_getCallsStatus",
>
    "params": [
>
      [
>
        "{CALL_ID_FROM_STEP_2_OR_STEP_4}"
>
      ]
>
    ],
>
    "id": 1
>
  }'

1
{
2
  "id": "1",
3
  "jsonrpc": "2.0",
4
  "result": {
5
    "id": "CALL_ID",
6
    "chainId": "SOURCE_CHAIN_ID",
7
    "atomic": true,
8
    "status": 200,
9
    "receipts": [...]
10
  }
11
}

FAQs

What chains are supported for cross-chain swaps?

Chains supported (for now) are: Arbitrum, Arbitrum Nova, Base, Berachain, Boba Network, BSC/BNB, Celo, Ethereum, Hyperliquid, Ink, Optimism, Plasma, Polygon, Shape, Soneium, Story, Unichain, World Chain, and Zora mainnets.

Can I batch additional calls after a cross-chain swap?

No, postCalls are not supported for cross-chain swaps (for now). You can only perform the swap itself across chains.

How long do cross-chain swaps take?

Cross-chain swaps typically take longer than single-chain swaps due to the need for cross-chain messaging and confirmation. The exact time depends on the source and destination chains involved in the swap.

How do you encode values?

Values are simply passed as hexadecimal strings. The Swap API doesn’t add complexity to consider decimals, so 0x01 is always the smallest amount of a given asset. 1 ETH, or DAI (18 decimals) is 0xDE0B6B3A7640000 1 USDC (6 decimals) is 0xF4240 This removes any ambiguity— if it’s numerical, it’s a hex.

What is the expiry?

The expiry is an informational indicator of when you can expect to be able to process the swap request. If you’re at/near the expiry, it might be a good time to request a new quote.

What are the different status codes for cross-chain swaps?

Cross-chain swaps may have additional status codes beyond standard transaction statuses to reflect the cross-chain nature of the transaction. These are:

• 120: Cross-chain in progress
• 410: Cross-chain refund

When is a CallId returned from wallet_requestQuote_v0?

Any time you’re requesting a cross-chain quote via wallet_requestQuote_v0 , a callId is returned. This callId includes important data for cross-chain tracking. You can use this just like any other callId in wallet_getCallsStatus!