Request Deposit Address
The ability to create a unique deposit address that is reserved for a user during a fixed period of time (24hs) provides a lot of flexibility and is a unique feature of the Chainflip protocol.
Once the deposit address is available, the user can send the funds from any wallet(s) to trigger the swap process. No need to connect a wallet.
Sending funds to a deposit address is cheaper than a smart contract call, as no token approvals are required.
Learn more on Deposit Channels & Brokers section.
requestDepositAddress
Requests a deposit address based on the provided DepositAddressRequest
.
requestDepositAddress(
depositAddressRequest: DepositAddressRequest
): Promise<DepositAddressResponse>
The depositAddressRequest
object describes the swap for which a deposit address is requested.
Param | Description | Data type |
---|---|---|
srcChain (required) | Source chain for the swap | Chain |
destChain (required) | Destination chain for the swap | Chain |
srcAsset (required) | Symbol of the token to be swapped from the source chain | Asset |
destAsset (required) | Symbol of the token to be received on the destination chain | Asset |
destAddress (required) | Address where the swapped tokens will be sent to on the destination chain | string |
amount (required) | Amount of the source token to be swapped, represented in the base unit of the source token | string |
brokerCommissionBps (optional) | Commission charged by the broker creating the channel, in basis points. If given, this value will be used instead of the brokerCommissionBps value used when initializing the SDK. This option is only available when the SDK is initialized with a brokerUrl | number |
affiliateBrokers (optional) | An array of objects defining affiliate broker accounts that take a commission in addition to brokerCommissionBps . This option is only available when the SDK is initialized with a brokerUrl | Array |
ccmParams (optional) | Optional metadata for triggering a [smart contract call](../advanced/cross-chain-messaging.mdx) on the destination chain. | Object |
maxBoostFeeBps (optional) | The accepted boost fee limit (in bps). Defaults to 0 - non-boostable deposit channel. If set to a value higher than 0, the deposits coming through this channel will have a chance to get boosted by paying a fee that doesn't exceed the boost fee limit set - boostable deposit channel. It is recommended to understand under which conditions deposits get boosted. | number |
fillOrKillParams (optional) | Optional metadata for setting a minimum accepted price for swaps through the deposit channel. This allows to protect against price changes between a quote and the execution of a swap (also known as slippage protection). | Object |
dcaParams (optional) | Optional metadata for executing a swap through a deposit channel as a DCA swap. Setting these params will split the swap into smaller chunks and execute them consecutively with a delay. | Object |
Example
Regular Deposit Address
import { Chains, Assets } from "@chainflip/sdk/swap";
const swapDepositAddressRequest = {
srcChain: Chains.Ethereum,
destChain: Chains.Bitcoin,
srcAsset: Assets.ETH,
destAsset: Assets.BTC,
destAddress: "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq",
amount: (1.5e18).toString(), // 1.5 ETH
brokerCommissionBps: 100, // 100 basis point = 1%
affiliateBrokers: [
{ account: "cFM8kRvLBXagj6ZXvrt7wCM4jGmHvb5842jTtXXg3mRHjrvKy", commissionBps: 50 }
], // total commission 150 bps = 1.5%
};
console.log(await swapSDK.requestDepositAddress(swapDepositAddressRequest));
Boostable Deposit Address
import { Chains, Assets } from "@chainflip/sdk/swap";
const swapDepositAddressRequest = {
srcChain: Chains.Ethereum,
destChain: Chains.Bitcoin,
srcAsset: Assets.ETH,
destAsset: Assets.BTC,
destAddress: "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq",
amount: (1.5e18).toString(), // 1.5 ETH
maxBoostFeeBps: 10 // Willing to pay up to 10 bps fee for a boosted deposit
};
console.log(await swapSDK.requestDepositAddress(swapDepositAddressRequest));
The amount
will always be in the base unit of the source asset, i.e. for ETH
it will be Wei.
Sample Response
{
"srcChain": "Ethereum",
"destChain": "Bitcoin",
"srcAsset": "ETH",
"destAsset": "BTC",
"destAddress": "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq",
"amount": "1500000000000000000", // 1.5 ETH
"depositChannelId": "1234567890", // Identifies the deposit channel for this swap
"depositAddress": "0x1234567890abcdef1234567890abcdef12345678", // Address where funds need to be deposited to start the swap
"depositChannelBrokerCommissionBps": 100,
"depositChannelAffiliateBrokers": [
{ "account": "cFM8kRvLBXagj6ZXvrt7wCM4jGmHvb5842jTtXXg3mRHjrvKy", "commissionBps": 50 }
],
"estimatedDepositChannelExpiryTime": 1630000000, // Estimated expiry time of the deposit channel
"maxBoostFeeBps": 10 // Boost fee bps limit set upon channel creation. 0 by default
}
fillOrKillParams: Slippage Protection
The optional fillOrKillParams
object sets a minimum accepted price for swaps triggered through the deposit channel.
This allows to protect against price changes between a quote and the execution of a swap (also known as slippage protection).
If the minimum price cannot be met with the available liquidity during the specified number of blocks, deposited assets will
be refunded to the specified refund address.
A minimum accepted price is specified as the ratio between the human readable destination amount and the human readable source amount
(eg. 3500
for a swap from ETH to USDC). Prices are checked on the AMM level and do not include deposit or broadcast fees.
To calculate a minPrice
based on a quote, the estimatedPrice
value is multiplied
with the desired slippage tolerance. For example, quote.estimatedPrice * 99 / 100
specifies a 1% slippage
tolerance relative to the quote.
Refunds are subject to a deposit fee and a broadcast fee on the source chain to pay for the transactions sent by the Chainflip protocol. If the deposit address has a broker fee, it will be deducted from the refund amount.
Param | Description | Data type |
---|---|---|
minPrice (required) | Minimum accepted price for swaps triggered through the deposit channel. | string |
refundAddress (required) | Address on the source chain to which the refund will be sent, if the minimum price cannot be met. | string |
retryDurationBlocks (required) | Number of State Chain blocks after which a deposit is refunded, if the minimum price cannot be met. One State Chain block corresponds to 6 seconds. | number |
Example
import { Chains, Assets } from "@chainflip/sdk/swap";
const quote = await swapSDK.getQuote({
srcChain: Chains.Ethereum,
destChain: Chains.Bitcoin,
srcAsset: Assets.ETH,
destAsset: Assets.BTC,
amount: (1.5e18).toString(), // 1.5 ETH
});
const swapDepositAddressRequest = {
srcChain: Chains.Ethereum,
destChain: Chains.Bitcoin,
srcAsset: Assets.ETH,
destAsset: Assets.BTC,
destAddress: "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq",
amount: (1.5e18).toString(), // 1.5 ETH
brokerCommissionBps: 100, // 100 basis point = 1%
fillOrKillParams: {
minPrice: (quote.estimatedPrice * 99 / 100).toString(), // minimum accepted price for swaps through the channel
refundAddress: '0xa56A6be23b6Cf39D9448FF6e897C29c41c8fbDFF', // address to which assets are refunded
retryDurationBlocks: 100, // 100 blocks * 6 seconds = 10 minutes before deposits are refunded
},
};
console.log(await swapSDK.requestDepositAddress(swapDepositAddressRequest));
dcaParams
See DCA
The optional dcaParams
object sets two parameters numberOfChunks
and chunkIntervalBlocks
that would split up a swap into smaller chunks and execute them consecutively with a delay. Doing so allows market makers to offer better pricing especially for larger swaps
numberOfChunks
is the number of chunks to split the swap into and chunkIntervalBlocks
is the number of state-chain blocks to wait before executing the next chunk. We recommend that integrators that wish to adopt DCA swaps set these values according to the response from the quoteV2.
dcaParams
must also be set in conjunction with fillOrKillParams
. This causes the minPrice
to apply to each individual chunk in the overall swap. If a chunk fails to meet the minPrice
, it will retry according to retryDurationBlocks
until it does. If it does not meet it, the entire swap is retired. The swapped amount is egressed and anything that was not swapped is refunded back to the refundAddress
Param | Description | Data type |
---|---|---|
numberOfChunks (required) | The number of chunks to split the swap into. | number |
chunkInterval (required) | Interval in state-chain blocks between each chunk. (minimum value: 2 blocks) | number |
import { Chains, Assets } from "@chainflip/sdk/swap";
const [quote, dcaQuote] = await swapSDK.getQuoteV2({
srcChain: Chains.Ethereum,
destChain: Chains.Bitcoin,
srcAsset: Assets.ETH,
destAsset: Assets.BTC,
amount: (1.5e18).toString(), // 1.5 ETH
});
const swapDepositAddressRequest = {
srcChain: Chains.Ethereum,
destChain: Chains.Bitcoin,
srcAsset: Assets.ETH,
destAsset: Assets.BTC,
destAddress: "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq",
amount: (1.5e18).toString(), // 1.5 ETH
brokerCommissionBps: 100, // 100 basis point = 1%
fillOrKillParams: {
minPrice: (quote.estimatedPrice * 99 / 100).toString(), // minimum accepted price for swaps through the channel
refundAddress: '0xa56A6be23b6Cf39D9448FF6e897C29c41c8fbDFF', // address to which assets are refunded
retryDurationBlocks: 100, // 100 blocks * 6 seconds = 10 minutes before deposits are refunded
},
dcaParams: {
numberOfChunks: dcaQuote.numberOfChunks,
chunkIntervalBlocks: dcaQuote.chunkInterval,
},
};
console.log(await swapSDK.requestDepositAddress(swapDepositAddressRequest));
ccmParams: Cross-Chain Messaging (CCM)
The optional ccmParams
object enables executing a smart contract call on
the destination chain and has the following properties:
Param | Description | Data type |
---|---|---|
message (required) | Message that is passed to the destination address on the destination chain. The message should be shorter than 10k bytes. | string |
gasBudget (required) | Gas budget for the call on the destination chain. This amount is based on the source asset and will be subtracted from the input amount and swapped to pay for gas. | number |
Example
import { Chains, Assets } from "@chainflip/sdk/swap";
const callDepositAddressRequest = {
srcChain: Chains.Bitcoin,
destChain: Chains.Ethereum,
srcAsset: Assets.BTC,
destAsset: Assets.ETH,
destAddress: "0x2f41dd5dEe1BcF767139b6bB6e27673aE90061b5",
amount: (1e8).toString(), // 1 BTC
ccmParams: {
message: "0xdeadc0de",
gasBudget: (0.001e8).toString(), // 0.001 BTC will be swapped for ETH to pay for gas
},
};
console.log(await swapSDK.requestDepositAddress(callDepositAddressRequest));
The amount
and gasBudget
will always be in the base unit of the source
asset, i.e. for ETH
it will be Wei.
Sample Response
{
"srcChain": "Bitcoin",
"destChain": "Ethereum",
"srcAsset": "BTC",
"destAsset": "ETH",
"destAddress": "0x2f41dd5dEe1BcF767139b6bB6e27673aE90061b5",
"amount": "100000000", // 1 BTC
"ccmParams": {
"message": "0xdeadc0de",
"gasBudget": "100000", // 0.001 BTC will be swapped for ETH to pay for gas
},
"depositChannelId": "1234567890", // Identifies the deposit channel for this swap
"depositAddress": "tb1pylj9uhsmuz7h62spprv2z2vcnx2lw9epzt4amm3j45y75r6rrd8sdx0sjf", // Address where funds need to be deposited to start the swap
"brokerCommissionBps": 0, // Commission charged by the broker for this swap
"estimatedDepositChannelExpiryTime": 1630000000, // Estimated expiry time of the deposit channel
}
The resulting depositChannelId
can be used in Get Status.
Use Your Own Broker
The previous two examples can also be performed with your own broker, instead of the broker that is provided by the Chainflip SDK:
import { SwapSDK } from '@chainflip/sdk/swap';
const sdk = new SDK({
network: 'perseverance',
broker: {
url: 'https://my.broker.io',
commissionBps: 15,
},
});
const channel = await sdk.requestDepositAddress({
srcAsset: 'ETH',
srcChain: 'Ethereum',
destAsset: 'FLIP',
destChain: 'Ethereum',
amount: '1000000000000000000', // 1 ETH
destAddress: '0x1234567890abcdef1234567890abcdef12345678',
});
console.log(channel);
/*
{
srcAsset: 'ETH',
srcChain: 'Ethereum',
destAsset: 'FLIP',
destChain: 'Ethereum',
amount: '1000000000000000000',
destAddress: '0x717e15853fd5f2ac6123e844c3a7c75976eaec9b',
depositChannelId: '710643-Ethereum-615',
depositAddress: '0x2d564a0754168cf49af604c82e84bd3a30599bf5',
brokerCommissionBps: 15,
estimatedDepositChannelExpiryTime: 1630000000,
}
*/