Cross-Chain Swap with 0x

Cross-chain swap endpoints are experimental and require explicit enablement by both the Portal and 0x teams before they can be used. Contact your Portal account manager to request access.

Portal’s Enclave MPC API provides cross-chain bridging and swapping through 0x. This guide covers getting quotes, executing swaps, and tracking transaction status across chains.

Overview

Using 0x cross-chain, you can:

Get quotes for cross-chain swaps across EVM chains with multiple bridge providers
Execute cross-chain swaps by signing and submitting the returned transaction
Track transaction status for cross-chain transfers
Browse transaction history for a wallet address
List available sources including bridge providers and DEX sources

Prerequisites

Before using 0x cross-chain operations, ensure you have:

A properly initialized Portal client (see Create a client)
An active wallet with the required token(s) on the origin chain (see Create a wallet)
0x integration enabled in your Portal Dashboard with a cross-chain-enabled API key (see 0x Integration)

Getting Cross-Chain Quotes

Use the POST /api/v3/clients/me/integrations/0x/cross-chain/quotes endpoint to get quotes for a cross-chain swap.

curl --request POST \
  --url 'https://api.portalhq.io/api/v3/clients/me/integrations/0x/cross-chain/quotes' \
  --header 'Authorization: Bearer [clientApiKey|clientSessionToken]' \
  --header 'Content-Type: application/json' \
  --data '{
  "originChain": "eip155:8453",
  "destinationChain": "eip155:42161",
  "sellToken": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
  "buyToken": "0xaf88d065e77c8cc2239327c5edb3a432268e5831",
  "sellAmount": "1000000",
  "sortQuotesBy": "price"
}'

Parameters

Name	Type	Required	Description
`originChain`	string	Yes	Origin chain in CAIP-2 format (e.g. `eip155:8453`)
`destinationChain`	string	Yes	Destination chain in CAIP-2 format (e.g. `eip155:42161`)
`sellToken`	string	Yes	Token to sell on the origin chain. Accepts a contract address (e.g. `0x833589...`), a native token keyword (`NATIVE`, `ETH`, `AVAX`, `POL`, etc.), or a supported token symbol (`USDC`, `USDT`)
`buyToken`	string	Yes	Token to buy on the destination chain. Same formats as `sellToken`
`sellAmount`	string	Yes	Amount of `sellToken` to sell, in base units (the smallest indivisible unit of the token, e.g. `1000000` for 1 USDC since USDC has 6 decimals, or wei for native ETH)
`sortQuotesBy`	string	Yes	Sort quotes by `speed` or `price`
`originAddress`	string	No	Wallet address on origin chain. Defaults to the client’s EIP-155 address
`destinationAddress`	string	No	Wallet address to receive tokens. Defaults to `originAddress`
`slippageBps`	number	No	Maximum slippage in basis points (100 = 1%). Defaults to 100
`maxNumQuotes`	number	No	Maximum number of quotes to return (1-10). Defaults to 3
`excludedBridges`	string	No	Comma-separated bridge providers to exclude
`includedBridges`	string	No	Comma-separated bridge providers to include
`feeBps`	string	No	Integrator fee in basis points
`feeRecipient`	string	No	Address to receive integrator fees

Response

The response includes an array of quotes, each containing:

sellAmount / buyAmount / minBuyAmount - Token amounts in base units
steps - Sequential steps (swap, bridge, wrap/unwrap) required to complete the cross-chain swap
transaction - A Portal-formatted transaction object (from, to, data, gas, gasPrice, value) ready to sign and submit
approvalTransaction - A Portal-formatted approval transaction (included automatically when token allowance is needed on EVM origin chains). Sign and submit this before the main transaction
estimatedTimeSeconds - Estimated time for the swap to complete
fees - Breakdown of integrator fees, 0x fees, and bridge fees
issues - Problems that would cause the swap to fail (allowance, balance, simulation, invalid sources). See Inspecting issues below

When issues.allowance is present, the response automatically includes an approvalTransaction that approves the exact sellAmount for the swap. This uses the minimum required approval for security — no unlimited approvals.

Inspecting `issues`

Before submitting any transactions, inspect the quote’s issues property. It surfaces problems that would otherwise cause the swap to fail on-chain:

allowance - The wallet hasn’t approved enough of sellToken for the 0x contract. Sign the included approvalTransaction (covered in Step 1 below).
balance - The wallet doesn’t hold enough sellToken to cover sellAmount. Top up the wallet before retrying.
simulationIncomplete - 0x couldn’t fully simulate the swap, so execution may revert. Re-fetch the quote, or proceed with caution if the route is otherwise sound.
invalidSourcesPassed - One of the bridges or DEX sources you requested via includedBridges isn’t valid for this route. Adjust includedBridges / excludedBridges and re-fetch.

Resolve any issues (top up the wallet, exclude a problematic source, etc.), then fetch a new quote and proceed with the steps below.

Executing a Cross-Chain Swap

After selecting a quote, check if an approvalTransaction is present. If so, you must sign and submit it before the main transaction. This is a two-step signing flow:

Sign approvalTransaction (if present) — approves the 0x contract to spend your ERC20 tokens
Re-fetch a fresh quote — the original quote may have expired while the approval was confirming
Sign transaction — executes the cross-chain swap

If approvalTransaction is present in the quote response, you must sign and submit it before the main transaction. Submitting the swap transaction without approval will fail with an “ERC20: transfer amount exceeds allowance” error.

Step 1: Approve Token Allowance (if required)

If the quote includes approvalTransaction, sign and submit it first. This approves the 0x contract to spend the exact amount of your sell token needed for the swap.

curl --request POST \
  --url https://mpc-client.portalhq.io/v1/sign \
  --header 'Authorization: Bearer [clientApiKey|clientSessionToken]' \
  --header 'Content-Type: application/json' \
  --data '{
  "share": "[share]",
  "method": "eth_sendTransaction",
  "params": [approvalTransaction],
  "rpcUrl": "https://api.portalhq.io/rpc/v1/eip155/8453",
  "chainId": "eip155:8453"
}'

Pass the entire approvalTransaction object from the quote response as params. Wait for the approval transaction to confirm before proceeding to the next step.

Native token swaps (e.g. ETH, AVAX) do not require approval since they are not ERC20 tokens. The approvalTransaction field will only be present when swapping ERC20 tokens that require allowance.

Step 2: Re-fetch a Fresh Quote

After the approval confirms, fetch a new quote. The original quote contains calldata with embedded timestamps that may have expired during the approval confirmation.

# Re-fetch quote with the same parameters as Step 1
curl --request POST \
  --url 'https://api.portalhq.io/api/v3/clients/me/integrations/0x/cross-chain/quotes' \
  --header 'Authorization: Bearer [clientApiKey|clientSessionToken]' \
  --header 'Content-Type: application/json' \
  --data '{
  "originChain": "eip155:8453",
  "destinationChain": "eip155:42161",
  "sellToken": "USDC",
  "buyToken": "USDC",
  "sellAmount": "1000000",
  "sortQuotesBy": "price"
}'

The new quote should no longer include approvalTransaction (since the allowance is now set) and the transaction calldata will have fresh timestamps.

Step 3: Sign and Submit the Cross-Chain Transaction

Use the transaction from the fresh quote:

curl --request POST \
  --url https://mpc-client.portalhq.io/v1/sign \
  --header 'Authorization: Bearer [clientApiKey|clientSessionToken]' \
  --header 'Content-Type: application/json' \
  --data '{
  "share": "[share]",
  "method": "eth_sendTransaction",
  "params": [transaction],
  "rpcUrl": "https://api.portalhq.io/rpc/v1/eip155/8453",
  "chainId": "eip155:8453"
}'

Pass the entire transaction object from the quote response as params.

The rpcUrl and chainId should correspond to the origin chain, since the transaction is submitted on the origin chain. The bridge provider handles delivering tokens to the destination chain.

Step 4: Resolve the Transaction Hash (Account Abstraction clients only)

If your client uses Account Abstraction, the eth_sendTransaction response contains a user operation hash rather than a transaction hash. The cross-chain status endpoint requires the actual on-chain transaction hash, so resolve the userOp hash first:

curl --request GET \
  --url 'https://api.portalhq.io/api/v3/clients/me/chains/eip155:8453/transactions/[userOpHash]' \
  --header 'Authorization: Bearer [clientApiKey|clientSessionToken]'

Use evmUserOperation.receipt.hash from the response as the originTxHash in Step 5. EOA clients can skip this step and use the hash returned from signing directly. See the transaction lookup endpoint for the full response shape.

Step 5: Track Transaction Status

Use the GET /api/v3/clients/me/integrations/0x/cross-chain/status endpoint to track the cross-chain transfer:

curl --request GET \
  --url 'https://api.portalhq.io/api/v3/clients/me/integrations/0x/cross-chain/status?originChain=eip155:8453&originTxHash=0xYourTransactionHash' \
  --header 'Authorization: Bearer [clientApiKey|clientSessionToken]'

Status Values

Status	Description
`origin_tx_pending`	Origin chain transaction is pending
`origin_tx_succeeded`	Origin chain transaction succeeded
`origin_tx_confirmed`	Origin chain transaction is confirmed
`origin_tx_reverted`	Origin chain transaction reverted
`bridge_pending`	Bridge transfer is in progress
`bridge_filled`	Bridge transfer completed successfully
`bridge_failed`	Bridge transfer failed (check `failure` field for details)

If the status is bridge_failed, check the failure field in the response. In some cases (e.g. Stargate V2), a failure.recovery.manualTransaction may be provided that you can submit to recover funds on the destination chain.

Listing Available Sources

Use the GET /api/v3/clients/me/integrations/0x/cross-chain/sources endpoint to list available bridge providers and DEX sources:

curl --request GET \
  --url 'https://api.portalhq.io/api/v3/clients/me/integrations/0x/cross-chain/sources' \
  --header 'Authorization: Bearer [clientApiKey|clientSessionToken]'

The response includes:

bridges - Available bridge providers with supported origin/destination chain pairs
swapSources - Available DEX sources with supported chain IDs

Viewing Transaction History

Use the GET /api/v3/clients/me/integrations/0x/cross-chain/tx-history endpoint to view cross-chain transaction history for a wallet:

curl --request GET \
  --url 'https://api.portalhq.io/api/v3/clients/me/integrations/0x/cross-chain/tx-history?user=0xYourWalletAddress&limit=20' \
  --header 'Authorization: Bearer [clientApiKey|clientSessionToken]'

Example Flow

Here’s a complete example of a cross-chain swap from Base USDC to Arbitrum USDC:

# 1. Get cross-chain quotes
QUOTE_RESPONSE=$(curl --request POST \
  --url 'https://api.portalhq.io/api/v3/clients/me/integrations/0x/cross-chain/quotes' \
  --header 'Authorization: Bearer [clientApiKey|clientSessionToken]' \
  --header 'Content-Type: application/json' \
  --data '{
  "originChain": "eip155:8453",
  "destinationChain": "eip155:42161",
  "sellToken": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
  "buyToken": "0xaf88d065e77c8cc2239327c5edb3a432268e5831",
  "sellAmount": "1000000",
  "sortQuotesBy": "price"
}')

# 2. Inspect quote.issues, then select a quote and pass its `transaction`
#    object straight through as `params` below.

# 3. Sign and submit the transaction on the origin chain
curl --request POST \
  --url https://mpc-client.portalhq.io/v1/sign \
  --header 'Authorization: Bearer [clientApiKey|clientSessionToken]' \
  --header 'Content-Type: application/json' \
  --data '{
  "share": "[share]",
  "method": "eth_sendTransaction",
  "params": [transaction],
  "rpcUrl": "https://api.portalhq.io/rpc/v1/eip155/8453",
  "chainId": "eip155:8453"
}'

# 4. Track the cross-chain transfer status (AA clients: first resolve the
#    userOp hash to a tx hash via GET /clients/me/chains/{chain}/transactions/{userOpHash})
curl --request GET \
  --url 'https://api.portalhq.io/api/v3/clients/me/integrations/0x/cross-chain/status?originChain=eip155:8453&originTxHash=0xYourTransactionHash' \
  --header 'Authorization: Bearer [clientApiKey|clientSessionToken]'

Failure Handling

Cross-chain operations are non-atomic. If a bridge transfer fails:

Automatic refunds: For Across, Relay, and Squid Coral, the user will be refunded in the bridging token (which may differ from the original sell token) on the origin chain.
Manual recovery: For Stargate V2, funds may be delivered to the destination chain but not to the wallet. The status API will return a failure.recovery.manualTransaction that can be submitted to re-trigger delivery.

Always monitor transaction status after submission and implement appropriate error handling for your users.

Supported Networks

0x cross-chain supports bridging between the following EVM networks:

Ethereum (eip155:1)
Base (eip155:8453)
Arbitrum (eip155:42161)
Optimism (eip155:10)
Polygon (eip155:137)
BSC (eip155:56)
Avalanche (eip155:43114)
Linea (eip155:59144)
Blast (eip155:81457)
Scroll (eip155:534352)

Use the sources endpoint to get the full list of supported bridge pairs.

Next Steps

Learn about signing Ethereum transactions
Explore same-chain 0x swaps using the SDKs
Compare with Li.Fi cross-chain bridging for alternative bridge options

Getting Started

SDKs

APIs

Integrations

Resources

Cross-Chain Swap with 0x

Overview

Prerequisites

Getting Cross-Chain Quotes

Parameters

Response

Inspecting `issues`

Executing a Cross-Chain Swap

Step 1: Approve Token Allowance (if required)

Step 2: Re-fetch a Fresh Quote

Step 3: Sign and Submit the Cross-Chain Transaction

Step 4: Resolve the Transaction Hash (Account Abstraction clients only)

Step 5: Track Transaction Status

Status Values

Listing Available Sources

Viewing Transaction History

Example Flow

Failure Handling

Supported Networks

Next Steps

​Overview

​Prerequisites

​Getting Cross-Chain Quotes

​Parameters

​Response

​Inspecting issues

​Executing a Cross-Chain Swap

​Step 1: Approve Token Allowance (if required)

​Step 2: Re-fetch a Fresh Quote

​Step 3: Sign and Submit the Cross-Chain Transaction

​Step 4: Resolve the Transaction Hash (Account Abstraction clients only)

​Step 5: Track Transaction Status

​Status Values

​Listing Available Sources

​Viewing Transaction History

​Example Flow

​Failure Handling

​Supported Networks

​Next Steps

Overview

Prerequisites

Getting Cross-Chain Quotes

Parameters

Response

Inspecting `issues`

Executing a Cross-Chain Swap

Step 1: Approve Token Allowance (if required)

Step 2: Re-fetch a Fresh Quote

Step 3: Sign and Submit the Cross-Chain Transaction

Step 4: Resolve the Transaction Hash (Account Abstraction clients only)

Step 5: Track Transaction Status

Status Values

Listing Available Sources

Viewing Transaction History

Example Flow

Failure Handling

Supported Networks

Next Steps