# Vault Swap Transaction Payloads

## Details

The deposit-address flow in [Starting a Swap](https://docs.chainflip-broker.io/features/start-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](https://docs.chainflip-broker.io/reference/glossary/#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](https://docs.chainflip-broker.io/chains/bitcoin/), [Ethereum](https://docs.chainflip-broker.io/chains/ethereum/), [Arbitrum](https://docs.chainflip-broker.io/chains/arbitrum/), [BNB Smart Chain](https://docs.chainflip-broker.io/chains/bsc/), [Solana](https://docs.chainflip-broker.io/chains/solana/) and [Tron](https://docs.chainflip-broker.io/chains/tron/).

Vault swaps are not supported from Asset Hub: an Asset Hub `sourceAsset` answers `400` (`Unknown Source Asset.`), so swap from [Asset Hub](https://docs.chainflip-broker.io/chains/asset-hub/) through a [`/swap`](https://docs.chainflip-broker.io/features/start-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`](https://docs.chainflip-broker.io/features/start-swap/#slippage-protection).
  * `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](https://docs.chainflip-broker.io/use-cases/#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](https://docs.chainflip-broker.io/features/start-swap/#dca), 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](https://docs.chainflip-broker.io/features/start-swap/#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](https://docs.chainflip-broker.io/features/get-status/), by deposit channel or transaction hash, exactly like a regular swap.

## Error Responses

Failures use the same [RFC 7807](https://www.rfc-editor.org/rfc/rfc7807) 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](https://docs.chainflip-broker.io/features/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.

```json
{
    "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"
}
```
