Skip to main content

Ethereum Swap API

Broker as a Service (BaaS) swaps ETH and the listed ERC-20 tokens on Ethereum to and from every other supported chain, through the REST API and the MCP server. This page collects what is specific to Ethereum: minimums and token contracts, addresses, deposits and refunds, vault swaps and pitfalls. For the general flow, start with Starting a Swap and View Available Assets.

Assets and minimums​

AssetidDecimalsMinimumNative minimumContract
CBBTCcbbtc.eth80.0004 CBBTC400000xcbB7C0000aB88B473b1f5aFd9ef808440eed33Bf
ETHeth.eth180.01 ETH10000000000000000—
FLIPflip.eth184 FLIP40000000000000000000x826180541412D574cf1336d22c0C0a287822678A
USDCusdc.eth620 USDC200000000xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
USDTusdt.eth620 USDT200000000xdAC17F958D2ee523a2206206994597C13D831ec7
WBTCwbtc.eth80.0004 WBTC400000x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599

Snapshot captured on 2026-11-17 from the production /assets endpoint. Minimums are Chainflip's current source (ingress) minimum deposit amounts; query /assets for live values. Destination-side egress minimums depend on gas and are not in /assets; see Error Codes for egress_below_minimum and egress_fee_not_covered. minimalAmountNative is in the asset's smallest unit. Assets disabled upstream are omitted.

The Contract column is the token's mainnet contract; check it before you send or approve a token. Decimals differ per token, so convert amounts with the value in the table, not a fixed 18.

Addresses​

Ethereum addresses are 0x followed by 40 hexadecimal characters. A mixed-case address must carry a valid EIP-55 checksum; an all-lowercase or all-uppercase address is accepted without one. The same address rules apply on Ethereum, Arbitrum and BNB Smart Chain, so BaaS cannot tell which EVM chain an address was meant for: confirm the user controls it on Ethereum.

A destination address is checked with the destination asset's rules and a refund address with the source asset's, so an Ethereum refundAddress is required when the source asset is on Ethereum.

Deposits and refunds​

A /swap call opens a deposit channel and returns the address the user sends the source asset to.

  • Deposit channels close after 24 hours. Open a new channel for every deposit-channel swap and send the deposit immediately (Chainflip: closure of deposit channels).
  • minimumPrice and refundAddress are required.
  • retryDurationInBlocks is optional: omitted or negative, it is the 150-block (15-minute) default, and a value above Chainflip's current runtime limit is lowered to that limit. Use the quote's recommendedRetryDurationInBlocks.
  • If the minimum price or live price protection is not met within the retry window, the source asset is refunded to refundAddress. For DCA, only unexecuted chunks are refunded; executed chunks still pay out to the destination.

See Starting a Swap and Chainflip's Swapping Basics.

Chainflip's ingress table lists a 5-block safety margin for Ethereum deposits, about a minute. Show users the quote's estimatedDurationSeconds rather than a fixed number.

Vault swaps​

An Ethereum vault swap is a call to Chainflip's Vault contract that your application or the user's wallet signs and submits; there is no deposit channel. /tx-payload/evm takes sourceAmount (in the source asset's smallest unit), minimumPrice, refundAddress and retryDurationInBlocks, and returns:

  • to - the Vault contract to call.
  • callData - the encoded swap call.
  • value - the amount of native ETH to attach, hex-encoded.
  • sourceTokenAddress - only for an ERC-20 source: the token to approve. It is a response field, not a request parameter.

For an ERC-20 source, the Vault must be approved to spend the token before the swap transaction is submitted; without the approval the call fails on chain. For an ETH source, the swap amount travels as the transaction's value.

Payloads can stay valid for a long time, but Chainflip advises signing and broadcasting only freshly built ones. See Chainflip's EVM Vault Swaps for the protocol details.

Boost is documented for Bitcoin deposits; see the Bitcoin page.

Known pitfalls​

  • ERC-20 approval. A token vault swap needs an approval transaction first; budget gas for both.
  • Gas and egress fees. A small output to Ethereum can be rejected at quote time with egress_below_minimum or egress_fee_not_covered when gas is high; quote a bigger amount.
  • FLIP has no oracle price. Live price protection is omitted for pairs with FLIP, so minimumPrice is the only price limit.
  • Payload freshness. Build a new vault payload for each transaction instead of reusing an old one.
  • Decimals. Read each token's decimals from the table or /assets; they are not all 18.
  • Same address, other chains. An Ethereum address is also valid on Arbitrum and BNB Smart Chain; check which chain the user expects.