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.

Each source chain has its own endpoint. All four are GET requests, take the same 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 and Arbitrum, 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.

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.
  • 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.
  • retryDurationInBlocks - Number of blocks (6 seconds each) after which a deposit is refunded if the minimum price cannot be met. Maximum 14400 (24 hours).

Two parameters differ per chain:

  • Bitcoin uses destinationMinimumAmount - the minimum output amount in the smallest native unit of the output asset.
  • EVM, Solana and Tron use sourceAmount - the amount of the source asset in its smallest native unit.

Optional parameters:

  • commissionBps - Override to the charged commission, within Commission Protection.
  • boostFee - Maximum accepted boost fee in basis points for Bitcoin swaps.
  • numberOfChunks and chunkIntervalBlocks - DCA parameters, EVM, Solana and Tron only.

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 upstream failures. See Error Codes.

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