Vault Swap Transaction Payloads
Details
The deposit-address flow in Starting a Swap gives you an address the user sends funds to. A vault swap goes one step further: the API returns an unsigned transaction for the source chain, and your application (or a wallet SDK) signs and submits it. The user never has to copy a deposit address, and you control the transaction from end to end.
The glossary defines a vault swap and how it differs from a deposit channel.
Each source chain has its own endpoint. All four are GET requests, share a set of core parameters, and return the payload fields your chain library expects. They are intentionally left out of the interactive API reference; this page is their documentation.
API Endpoints
/tx-payload/bitcoin- Bitcoin, returns an OP_RETURN nulldata payload./tx-payload/evm- Ethereum, Arbitrum and BNB Smart Chain (BSC), returns calldata for the vault contract./tx-payload/solana- Solana, returns the program, accounts and instruction data./tx-payload/tron- Tron, returns calldata for the vault contract.
The chain pages cover each source chain's assets, addresses and transaction details: Bitcoin, Ethereum, Arbitrum, BNB Smart Chain, Solana and Tron.
Vault swaps are not supported from Asset Hub: an Asset Hub sourceAsset answers 400 (Unknown Source Asset.), so swap from Asset Hub through a /swap deposit channel.
Parameters
Every endpoint requires:
apiKey- Your API key.sourceAsset- The asset to swap from, for examplebtc.btc.destinationAsset- The asset to swap to, for exampleeth.eth.destinationAddress- The address on the destination chain to swap to.
The remaining required parameters depend on the source chain:
- Bitcoin:
destinationMinimumAmount- the minimum output amount in the smallest native unit of the output asset. There is nominimumPriceorrefundAddress: the change output of the Bitcoin transaction is the refund address. - EVM and Tron:
sourceAmount- the amount of the source asset in its smallest native unit.minimumPrice- the minimum accepted price in human-readable form. Same calculation as theminimumPriceon/swap.refundAddress- address on the source chain to which the refund will be sent, if the minimum price cannot be met.
- Solana:
sourceAmount,minimumPriceandrefundAddressas for EVM and Tron, plus:sourceAddress- the account that sends the swap.eventDataAccount- the address of the already derived event data account.sourceTokenAccount- optional, for SPL token sources: the associated token account (ATA) ofsourceAddress.
Optional parameters:
commissionBps- Override to the charged commission, within Commission Protection.retryDurationInBlocks- Number of blocks (6 seconds each) after which a deposit is refunded if the minimum price cannot be met. Omitted or negative, it is150(15 minutes). A value above Chainflip's current runtime limit (600 blocks = one hour at the time of writing) is lowered to that limit and the payload is built.boostFee- Maximum accepted boost fee in basis points for Bitcoin swaps.numberOfChunksandchunkIntervalBlocks- DCA parameters, accepted by all four endpoints and adjusted as on/swap: chunks below1become1, an omitted, negative or (with more than one chunk) zero interval becomes2, and a schedule above Chainflip's runtime limit is shortened.invalid_dca_parametersanswers only when that limit cannot be read or the node rejects the schedule for another reason.livePriceSlippageTolerancePercent- Live price protection against Chainflip's oracle price, in percent with at most 2 decimals, as on/swap; for a pair without an oracle price it is omitted and the payload is built without it. Bitcoin's OP_RETURN payload stores it in one byte of basis points, where255means none, so254bps (2.54) is the largest value there and a larger value is lowered to2.54; EVM, Solana and Tron take up to100.
Bitcoin encodes retryDurationInBlocks, numberOfChunks and chunkIntervalBlocks as 16-bit fields, so a value above 65535 is lowered to 65535 before encoding. In practice this matters for chunkIntervalBlocks with numberOfChunks = 1, which the node accepts at any size; the retry duration is first lowered to the runtime maximum (far below 65535 today), and the total DCA duration is bounded by the runtime limit.
Response
The response is an unsigned payload which your code signs and submits on the source chain:
- Bitcoin:
network,nulldataPayload(hex data for an OP_RETURN output) anddepositAddress. Build one transaction that sends the amount todepositAddresswith an OP_RETURN output carryingnulldataPayload. - EVM:
to(the vault contract),callData,valueand, for ERC-20 sources,sourceTokenAddress(approve that token first). - Solana:
programId,accountsanddatafor the instruction. - Tron:
to,callData,value,noteandsourceTokenAddress.
After the transaction is confirmed on the source chain, follow the swap with Get Swap Status, by deposit channel or transaction hash, exactly like a regular swap.
Error Responses
Failures use the same RFC 7807 problem details shape as the other endpoints, including the machine-readable code on failures the API can classify (upstream errors and local refusals such as safe mode). See Error Codes.
Parameter values Chainflip's node rejects and that cannot be adjusted are coded 400: invalid_refund_parameters (a retry duration above the runtime limit is lowered instead), invalid_dca_parameters (a schedule above the runtime limit is shortened instead) and, rarely, live_price_protection_unavailable (normally live price protection on an oracle-less pair is omitted instead). The detail names the node's reason and no payload is built. Plain input validation keeps the errors object without a code; on a 400, check for code before assuming an errors object.
Your partner route settings apply as on /swap: a payload for a pair you have disabled is refused with 403 before anything is sent to the broker.
While Chainflip's safe mode has paused swapping or vault-deposit witnessing for the source chain, the payload endpoints answer 503 with chainflip_safe_mode before building anything. Signing and broadcasting such a payload would leave the vault deposit unprocessed until governance lifts the pause.
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.6.4",
"title": "Service Unavailable",
"status": 503,
"detail": "Too many swaps are ongoing right now, please try again later",
"traceId": "00-6e04726aca44787669d57a48b1833007-ddd09a1fe1f24426-00",
"code": "too_many_channels"
}