Skip to main content

Starting a Swap

Details​

Request a Deposit Address to make a swap between two assets towards a given destination address.

Your broker fee will automatically be taken into account.

A Deposit Address will be provided where the user can either manually send funds to, or you can implement a wallet signing solution to do this automatically. Once received the swap will happen and the funds will be sent to the destination address.

API Endpoint​

/swap - Start a swap.

Parameters​

To start a swap, you are required to provide the following parameters:

  • sourceAsset - The asset to swap from, for example btc.btc
  • destinationAsset - The asset to swap to, for example eth.arb
  • destinationAddress - The address on the destination chain to swap to, for example 0x2578f4fa0f36138c76389095bf74331a4f57bcc0

There are also additional optional parameters:

Boost​

For Bitcoin swaps, a fee can be supplied to turn it into a Boost swap, speeding up the time of a swap. This allows the user to swap Bitcoin faster than the estimated half hour (3 Bitcoin confirmations, which take 10 minutes per confirmation). Thanks to this a Bitcoin swap can happen in minutes instead of half an hour.

We advise to set the boostFee to 30 to make sure a swap is boosted. The user will only pay the lowest possible fee.

  • boostFee- The maximum accepted boost fee in basis points (100th of a percent) for a Boost swap. Must be between 0 and 100. We advise 30 to make sure a swap gets boosted; the user then always pays the lowest fee that was enough to boost it.

Slippage Protection​

In order to prevent high slippage you are required to pass in a minimum required price. If the swap does not meet this price, the source assets will be returned to the refundAddress.

  • minimumPrice - The minimum accepted price in human-readable form, for example 2768.95 for ETH.
  • refundAddress - Address on the source chain to which the refund will be sent, if the minimum price cannot be met.
  • retryDurationInBlocks - Number of blocks after which a deposit is refunded, if the minimum price cannot be met. One block corresponds to 6 seconds. Maximum is 14400 (24 hours), and 150 (15 minutes) is a sensible default.

Example Slippage Calculation​

Have a look at the following examples to determine the minimumPrice parameter:

BTC -> ETH Swap​
  • You want to set a slippage limit of 2%
  • In the quote response there is "estimatedPrice": 28.22379438638571497457
  • Use the following formula: minimumPrice = estimatedPrice * (1 - slippageLimit / 100)
  • This gives: 28.22379438638571497457 * 98 / 100 = 27.6593184987
  • Pass 27.6593184987 as minimumPrice parameter to apply a 2% slippage limit
USDT -> BTC Swap​
  • You want to set a slippage of 1%
  • In the quote response there is "estimatedPrice": 0.00001056302864588782
  • Use the following formula: minimumPrice = estimatedPrice * (1 - slippageLimit / 100)
  • This gives: 0.00001056302864588782 * 99 / 100 = 0.00001045739
  • Pass 0.00001045739 as minimumPrice parameter to apply a 1% slippage limit
SOL -> USDC Swap​
  • You want to set a slippage of 5%
  • In the quote response there is "estimatedPrice": 184.59038231365019505646
  • Use the following formula: minimumPrice = estimatedPrice * (1 - slippageLimit / 100)
  • This gives: 184.59038231365019505646 * 95 / 100 = 175.360863198
  • Pass 175.360863198 as minimumPrice parameter to apply a 5% slippage limit

DCA​

To perform a swap spread out over time, you can pass in DCA parameters. These will split the swap amount in a specific numberOfChunks and treat every chunk as a separate swap every chunkIntervalBlocks, where a block is 6 seconds.

If DCA parameters are combined with Slippage Protection parameters, the price will be checked at every chunk. Once slippage protection kicks in, the remaining unswapped chunks will be refunded to the user.

A DCA swap can also be a Boost swap, allowing the user to more quickly get their Bitcoin swapping.

  • numberOfChunks - The number of "sub-swaps" to perform for a DCA swap.
  • chunkIntervalBlocks - The delay between the "sub-swaps" of a DCA swap in number of blocks. Needs to be at least 2. One block is 6 seconds, so an interval of 5 would account for a sub-swap to happen every 30 seconds.

Custom Commission BPS​

You can also provide the commissionBps parameter to get override your configured commission. Note this can never be lower than your default according to the Commission Protection feature.

  • commissionBps - An optional override to the charged commission bps. Must be between 0 and 995.

Extra affiliates​

You can provide up to four extra affiliates to share a commission with.

  • affiliate1 - The ss58 affiliate broker address for the first affiliate.
  • affiliate1CommissionBps - The commission to assign to the first affiliate.
  • affiliate2 - The ss58 affiliate broker address for the second affiliate.
  • affiliate2CommissionBps - The commission to assign to the second affiliate.
  • affiliate3 - The ss58 affiliate broker address for the third affiliate.
  • affiliate3CommissionBps - The commission to assign to the third affiliate.
  • affiliate4 - The ss58 affiliate broker address for the fourth affiliate.
  • affiliate4CommissionBps - The commission to assign to the fourth affiliate.

Commissions get added up to your total commission charged to the user.

Response​

The response provides the address to send the sourceAsset funds to, plus the identifiers you need to track the swap:

  • address - The deposit address. Show it to the user, or use it in a wallet integration.
  • issuedBlock, network, channelId - Together these identify the deposit channel, which you can pass to status-by-deposit-channel.
  • sourceExpiryBlock - The block on the source network at which the deposit channel expires.
  • explorerUrl - Link to the channel on the Chainflip explorer, useful to show the user the swap is real.
  • channelOpeningFee (and channelOpeningFeeNative) - The channel opening fee in FLIP. Usually effectively zero, but worth reading if you display total cost.

Once the user sends funds, follow the swap with Get Swap Status.

Error Responses​

When a deposit address cannot be issued, the response is an RFC 7807 problem details object. Failures that originate at the broker (for example Chainflip's channel cap is hit, or an asset is disabled) carry a stable, machine-readable code next to the human-readable detail. The HTTP status follows the code: 503 for temporary conditions such as the channel cap, maintenance or a disabled asset, 500 only for unclassified failures. Input validation failures (400, with an errors object) and route denial (403) do not carry a code on this endpoint.

See Error Codes for the full list, what each one means, and how to handle unknown or missing 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"
}

Testnet Example​

The following example is based on the quote received in Asking for a Quote.

We will be applying a 2.5% slippage limit using 94162.97655452752291823391 as estimatedPrice.

After using our slippage protection calculations we get the following minimumPrice:
94162.97655452752291823391 * 97.5 / 100 = 91808.9021407

We will also be retrying for 15 minutes in case our slippage limit is hit. We calculate 15 minutes is 900 seconds, divided by 6 seconds per block, giving us a retryDurationInBlocks of 150.

curl --location 'https://perseverance.chainflip-broker.io/swap?apikey=93c2bff017e243f29ffb14e42dccbec8&sourceAsset=btc.btc&destinationAsset=usdt.eth&destinationAddress=DESTINATION_EVM_ADDRESS&refundAddress=SOURCE_BTC_ADDRESS&minimumPrice=91808.9021407&retryDurationInBlocks=150'
{
    "id": 268,
    "address": "tb1pwkx9h364f3kvy3nx7gz2wpw8tgdyujhnmc82836km76za5f0dvpsacn3ce",
    "issuedBlock": 4136443,
    "network": "Bitcoin",
    "channelId": 1006,
    "sourceExpiryBlock": 3581992,
    "explorerUrl": "https://scan.perseverance.chainflip.io/channels/4136443-Bitcoin-1006",
    "channelOpeningFee": 0.00000000000001,
    "channelOpeningFeeNative": "10000"
}