If you are integrating Chainflip deposit channels, treat the channel as a time-bounded swap instruction with explicit execution and refund controls, not as a reusable payment address. This is the operational layer behind how Chainflip settles cross-chain swaps: a deposit is witnessed, processed against liquidity, then paid out or refunded. Your application needs to preserve the instruction details and track the outcome across all three stages.
What does a deposit channel commit to?
A channel request registers the destination chain and address, swap amount and assets, and fill-or-kill parameters on the State Chain. The Broker returns a deposit channel ID and address; retain both, along with the opening transaction hash, quote, and refund address. The hash lets a user verify that the registered instruction matches what your interface displayed.
With the JavaScript SDK, request a quote through getQuoteV2, then pass the chosen quote, destination address, and fillOrKillParams to requestDepositAddressV2. Use the SDK’s encoder or Broker RPC helpers for protocol parameters. A quote set for a vault swap or on-chain swap cannot be used to open a deposit channel.
Channels expire after 24 hours. Open one for each swap and send the deposit promptly. Some vault types reuse an expired channel’s address for a later channel, so a late transfer may be ambiguous or unrecognized; do not treat the address as a standing deposit endpoint. Show the expiry estimate and transaction hash to the user before they send funds.
How should you set execution and refund limits?
fillOrKillParams protects the swap with a minimum price, a retry duration, and a source-chain refund address. The SDK converts slippageTolerancePercent into the minimum price and retryDurationMinutes into blocks. Start from the quote’s recommended values: a current SDK example returns 0.5% slippage, 0.125% live-price tolerance, and a five-minute retry window. These are quote-specific recommendations, not protocol-wide constants.
For example, on a 1.5 ETH to BTC quote, 0.5% tolerance lets execution proceed only if the achieved rate clears the encoded floor; a tighter setting reduces adverse price movement but raises refund probability when the market moves or liquidity is thin. The retry window gives the protocol time to try again after a price-limit failure. A longer window may recover a swap as prices normalize, but prolongs unresolved status and exposure to market movement.
Set the refund address to an address controlled by the user on the source chain, and validate its chain and format before requesting the channel. The Bitcoin Optech glossary’s explanation of confirmations is a useful reminder: a broadcast deposit is not yet a settled deposit. Chainflip’s documentation gives six Ethereum blocks and three Bitcoin blocks as typical witnessing thresholds, while actual duration depends on the source chain and network conditions.
What should your status handler do?
Poll getStatusV2 with the deposit channel ID, source transaction hash, or swap ID, and handle its states as a lifecycle: WAITING, RECEIVING, SWAPPING, SENDING, then SENT or COMPLETED; a failed swap can report FAILED. Preserve state transitions and transaction references for support and reconciliation instead of inferring completion from the source-chain transaction alone.
A swap can fail its minimum price check, hit stale or out-of-tolerance oracle pricing, or encounter a destination egress failure. Distinguish a swap refund from a failed payout: status data exposes refund and fallback egress information, and a refund can incur network and broadcast fees. Display the returned amount and refund transaction when available; do not promise the original deposit amount back.
Questions integrators ask next
How long does a channel stay open?
Twenty-four hours from opening. That is the deposit window, not a guaranteed swap duration: witnessing and destination-chain inclusion add time after a timely deposit. Use the returned expiry block and estimated expiry time for the countdown, and issue a fresh channel if the user has not sent funds promptly.
What does a refund cost?
It depends on the source asset and chain. The protocol’s documentation describes a refund fee with a $0.50 USD minimum, plus the broadcast fee for returning the funds. Show fees reported in swap status or a current quote; avoid promising a fixed refund amount before execution.
Can a user send more than once?
Do not assume multiple transfers to one channel create independent swaps. The channel encodes one swap instruction, and excess or late deposits can fall outside the expected amount or channel lifetime. In the interface, bind each payment attempt to its channel and explain what to do before accepting a second transfer.
When should you choose a vault swap?
Use a vault swap when a connected wallet or contract needs to initiate the swap directly on-chain, or when composability matters. A deposit channel is useful when the user should send from any wallet without token approvals. The choice changes the initiation path and parameter encoding, so keep quote type and initiation method aligned.
For a robust integration, persist the channel instruction, honor the quote’s minimum-price and retry recommendations, and reconcile the full lifecycle through status data. Those controls determine whether a delayed or adverse execution becomes a completed swap or a traceable refund.