# 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](https://docs.chainflip-broker.io/resources/ai-documentation/). 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](https://docs.chainflip-broker.io/features/start-swap/) and [View Available Assets](https://docs.chainflip-broker.io/features/view-assets/).

## Assets and minimums

| Asset | id | Decimals | Minimum | Native minimum | Contract |
| --- | --- | ---: | ---: | --- | --- |
| CBBTC | `cbbtc.eth` | 8 | 0.0004 CBBTC | `40000` | `0xcbB7C0000aB88B473b1f5aFd9ef808440eed33Bf` |
| ETH | `eth.eth` | 18 | 0.01 ETH | `10000000000000000` | — |
| FLIP | `flip.eth` | 18 | 4 FLIP | `4000000000000000000` | `0x826180541412D574cf1336d22c0C0a287822678A` |
| USDC | `usdc.eth` | 6 | 20 USDC | `20000000` | `0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48` |
| USDT | `usdt.eth` | 6 | 20 USDT | `20000000` | `0xdAC17F958D2ee523a2206206994597C13D831ec7` |
| WBTC | `wbtc.eth` | 8 | 0.0004 WBTC | `40000` | `0x2260FAC5E5542a773Aa44fBCfeDf7C193bc2C599` |

*Snapshot captured on 2026-11-17 from the production [`/assets`](https://docs.chainflip-broker.io/features/view-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](https://docs.chainflip-broker.io/features/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](https://docs.chainflip-broker.io/chains/arbitrum/) and [BNB Smart Chain](https://docs.chainflip-broker.io/chains/bsc/), 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`](https://docs.chainflip-broker.io/features/start-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](https://docs.chainflip.io/brokers/broker-deposit-channels-swaps#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](https://docs.chainflip-broker.io/features/start-swap/#slippage-protection) and Chainflip's [Swapping Basics](https://docs.chainflip.io/protocol/swapping-basics#slippage-protection).

Chainflip's [ingress table](https://docs.chainflip.io/protocol/ingress-witnessing-deposits#the-witness-process) 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`](https://docs.chainflip-broker.io/features/tx-payload/) 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](https://docs.chainflip.io/brokers/vault-swaps-api/evm) for the protocol details.

Boost is documented for Bitcoin deposits; see the [Bitcoin page](https://docs.chainflip-broker.io/chains/bitcoin/#boost).

## 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.

## Related

* [Starting a Swap](https://docs.chainflip-broker.io/features/start-swap/)
* [Vault Swap Transaction Payloads](https://docs.chainflip-broker.io/features/tx-payload/)
* [View Available Assets](https://docs.chainflip-broker.io/features/view-assets/)
* [View Available Networks](https://docs.chainflip-broker.io/features/view-networks/)
* [Error Codes](https://docs.chainflip-broker.io/features/error-codes/)
* [Testing Environment](https://docs.chainflip-broker.io/environments/testing/)
* [Ethereum Hackathon](https://docs.chainflip-broker.io/guides/ethereum-hackathon/)
