Skip to main content

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 example btc.btc.
  • destinationAsset - The asset to swap to, for example eth.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 no minimumPrice or refundAddress: 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 the minimumPrice on /swap.
    • refundAddress - address on the source chain to which the refund will be sent, if the minimum price cannot be met.
  • Solana: sourceAmount, minimumPrice and refundAddress as 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) of sourceAddress.

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 is 150 (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.
  • numberOfChunks and chunkIntervalBlocks - DCA parameters, accepted by all four endpoints and adjusted as on /swap: chunks below 1 become 1, an omitted, negative or (with more than one chunk) zero interval becomes 2, and a schedule above Chainflip's runtime limit is shortened. invalid_dca_parameters answers 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, where 255 means none, so 254 bps (2.54) is the largest value there and a larger value is lowered to 2.54; EVM, Solana and Tron take up to 100.

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) and depositAddress. Build one transaction that sends the amount to depositAddress with an OP_RETURN output carrying nulldataPayload.
  • EVM: to (the vault contract), callData, value and, for ERC-20 sources, sourceTokenAddress (approve that token first).
  • Solana: programId, accounts and data for the instruction.
  • Tron: to, callData, value, note and sourceTokenAddress.

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"
}