Migrating from a Self-Run Chainflip Broker
If you run your own Chainflip broker, you already have the hard part: a working swap integration. BaaS runs the broker for you and exposes the same swap flow through REST, MCP and an RPC drop-in. This guide shows the smallest change for the Chainflip SDK, SwapKit and raw broker RPC, then the fee, refund and cut-over details that decide whether the migration is uneventful.
Who this guide is for
Teams that run their own Chainflip broker and open swaps through it with the Chainflip SDK, SwapKit or raw broker JSON-RPC calls. The guide covers:
- the broker URL change for the Chainflip SDK and raw RPC;
- why SwapKit is not a broker URL change, and the REST call that replaces its deposit-channel request;
- how your commission and the BaaS operating fee add up;
- the refund parameters BaaS requires;
- what happens to the fees your old broker earned, and how to withdraw them;
- a cut-over that does not drop swaps already in flight;
- what the REST API adds once you have switched.
BaaS operates the broker and its State Chain account; you keep your integration. The API and this documentation are also reachable over Tor, see Tor (.onion). The code samples below use the clearnet origins, like the rest of these docs.
What changes and what does not
| Changes | Does not change |
|---|---|
| The broker URL, for the Chainflip SDK and raw RPC. | Asset ids, destination addresses and refund addresses. |
SwapKit's current brokerUrl is not a BaaS drop-in: keep SwapKit's route, or replace its deposit-channel call with BaaS REST. | Swap states: a channel still goes from waiting through to completed or refunded on Chainflip. |
| BaaS operates the broker and its account; you no longer hold FLIP for new swaps. | The deposit-channel and vault-swap model. |
| Your commission is configured in BaaS; the old broker's fee rate is not copied. | Chainflip SDK call sites (getQuoteV2, requestDepositAddressV2, getStatusV2). |
| Refund parameters are required on every deposit channel. | The method names and values of raw RPC calls, sent as positional params. |
| Broker administration (fee withdrawal, affiliates, account registration) stays on the old broker. | |
| BaaS status lookups only know swaps opened through BaaS. |
Before and after
| Integration | Before | After |
|---|---|---|
| Chainflip SDK | broker: { url: "https://your-broker.example" } | broker: { url: "https://chainflip-broker.io/rpc/YOUR_API_KEY" }, with network: "mainnet". On testnet: https://perseverance.chainflip-broker.io/rpc/YOUR_TESTNET_API_KEY with network: "perseverance". The network must match the URL. |
| SwapKit (current releases) | config.integrations.chainflip.brokerUrl pointing at a SwapKit broker-channel endpoint. | Not a URL swap. Keep SwapKit's route, or open the channel with BaaS /quotes and /swap. |
| Raw broker RPC | POST to your broker's JSON-RPC endpoint. | POST https://chainflip-broker.io/rpc/YOUR_API_KEY (testnet: https://perseverance.chainflip-broker.io/rpc/YOUR_TESTNET_API_KEY). Same method and values; params must be a positional array. Named (object) params and batches with more than one call answer 400. |
Testnet and mainnet are separate environments with separate API keys, see Testing.
Chainflip SDK
Change the broker URL and keep network in sync with it:
const swapSDK = new SwapSDK({
network: "perseverance", // "mainnet" in production
- broker: { url: "https://your-broker.example" },
+ broker: { url: "https://perseverance.chainflip-broker.io/rpc/YOUR_TESTNET_API_KEY" },
});
networkisperseverancefor testnet andmainnetfor production. When it is omitted, the SDK defaults toperseverance, so a production broker URL withoutnetwork: "mainnet"points the SDK's other calls at testnet.- Leave
rpcUrlunset. The SDK reads chain data from Chainflip's public node:cf_environmentforgetSwapLimitsand before everyrequestDepositAddressV2, andcf_boost_pools_depthandcf_lending_poolsforgetBoostLiquidity. BaaS is a broker endpoint, not a node replacement, and refuses those two pool methods. - The SDK sends
requestDepositAddressV2andencodeVaultSwapDatato the broker URL; both work with BaaS.encodeCfParameterssendsbroker_encode_cf_parameters, which BaaS does not support (400). getStatusV2asks Chainflip's backend, not the broker, so it follows any channel, whichever broker opened it. Right after a channel opens, the backend may not know it yet and the call fails with a404; retry after a few seconds.
A full run, from quote to channel to status:
import { SwapSDK, Chains, Assets } from "@chainflip/sdk/swap";
const swapSDK = new SwapSDK({
network: "perseverance", // "mainnet" in production
broker: {
url: "https://perseverance.chainflip-broker.io/rpc/YOUR_TESTNET_API_KEY",
},
// Leave rpcUrl unset: the SDK reads chain data (cf_environment, and
// cf_boost_pools_depth/cf_lending_pools for getBoostLiquidity) from
// Chainflip's public node. BaaS is a broker endpoint, not a node replacement.
});
const { quotes } = await swapSDK.getQuoteV2({
srcChain: Chains.Bitcoin,
srcAsset: Assets.BTC,
destChain: Chains.Ethereum,
destAsset: Assets.ETH,
amount: "10000000", // 0.1 BTC in satoshis
brokerCommissionBps: 10, // your partner commission, not the total fee
});
const quote = quotes.find((q) => q.type === "REGULAR");
if (!quote) throw new Error("No regular quote");
const deposit = await swapSDK.requestDepositAddressV2({
quote,
destAddress: "YOUR_ETHEREUM_ADDRESS",
fillOrKillParams: {
refundAddress: "YOUR_BITCOIN_REFUND_ADDRESS",
retryDurationMinutes: quote.recommendedRetryDurationMinutes,
slippageTolerancePercent: quote.recommendedSlippageTolerancePercent,
livePriceSlippageTolerancePercent:
quote.recommendedLivePriceSlippageTolerancePercent,
},
brokerCommissionBps: 10, // same partner commission; BaaS adds its operating fee
});
// Right after opening, Chainflip's backend may answer 404 for a few seconds; retry.
const status = await swapSDK.getStatusV2({ id: deposit.depositChannelId });
console.log({ quoteType: quote.type, channelId: deposit.depositChannelId, state: status.state });
brokerCommissionBps is your commission, not the total the user pays; see The commission, without surprises. The brokerCommissionBps and affiliateBrokers the SDK returns from requestDepositAddressV2 echo what you sent, not the split BaaS applied; /status-by-deposit-channel shows the applied split. The RPC page has the production configuration.
SwapKit
Current SwapKit releases configure Chainflip like this:
const skClient = createSwapKit({
config: {
integrations: {
chainflip: {
brokerUrl: "https://your-swapkit-broker.example",
},
},
},
});
This is not a BaaS drop-in. SwapKit's getChainflipDepositChannel posts SwapKit's own BrokerDepositChannelParams body (sellAsset, buyAsset, destinationAddress, refundParameters and so on) to brokerUrl, or to SwapKit's hosted /chainflip/broker/channel when brokerUrl is empty. BaaS /rpc expects a JSON-RPC call, so do not point brokerUrl at it. Older SwapKit releases used a chainflipBrokerConfig setting that current SwapKit no longer has; move those integrations to the same REST path.
You have two options:
- Keep SwapKit's route. Nothing changes, and the swap does not go through your BaaS account.
- Open the channel with BaaS REST. Ask for a quote with
/quotes, then open the channel with/swapand send the deposit with your wallet code, as SwapKit did with the address it got back:
curl --location 'https://perseverance.chainflip-broker.io/quotes?apiKey=YOUR_TESTNET_API_KEY&sourceAsset=btc.btc&destinationAsset=eth.eth&amount=0.1'
curl --location 'https://perseverance.chainflip-broker.io/swap?apiKey=YOUR_TESTNET_API_KEY&sourceAsset=btc.btc&destinationAsset=eth.eth&destinationAddress=YOUR_ETHEREUM_ADDRESS&refundAddress=YOUR_BITCOIN_REFUND_ADDRESS&minimumPrice=YOUR_MINIMUM_PRICE&retryDurationInBlocks=150'
/swap has no amount: the channel accepts whatever is deposited, and the quote's estimatedPrice gives you the minimumPrice (see Slippage Protection). The answer carries the deposit address, issuedBlock, network, channelId and sourceExpiryBlock. See the SwapKit documentation for the SwapKit side.
Raw RPC
Send the same call to BaaS, one call per request, with positional params:
curl -sS -X POST "https://perseverance.chainflip-broker.io/rpc/YOUR_TESTNET_API_KEY" \
-H "Content-Type: application/json" \
--data '{
"jsonrpc": "2.0",
"id": 1,
"method": "broker_request_swap_deposit_address",
"params": [
{"chain": "Bitcoin", "asset": "BTC"},
{"chain": "Ethereum", "asset": "ETH"},
"YOUR_ETHEREUM_ADDRESS",
10,
null,
0,
null,
{
"retry_duration": 100,
"refund_address": "YOUR_BITCOIN_REFUND_ADDRESS",
"min_price": "0x45d964b80000000000000000000000000000000000"
}
]
}'
- Positional params only.
paramsmust be an array. Named (object) params answer400. A JSON array is accepted only when it holds exactly one call, and the answer then comes back in an array. - Refund parameters at index 7 are required, on every chain: an object with
retry_duration,refund_addressandmin_price. Without them the call answers400and never reaches the broker.max_oracle_price_slippage(basis points) is optional and goes in the same object. min_priceis a hex-encoded U256:floor(price × 2^128 × 10^(destination decimals − source decimals)), where price is destination units per source unit. For a minimum of 30 ETH per BTC (ETH has 18 decimals, BTC 8) that is"0x" + (30n * 2n**128n * 10n**10n).toString(16)in JavaScript, which is the value in the sample. BaaS checks that the field is present; the broker validates the encoding. The Chainflip SDK does this conversion for you.- Commission at index 3 is your commission, see below. Affiliates at index 6 must be an array or
null: your commission is injected as the first entry and the list is capped at five, so pass at most four of your own. - Supported surface. The RPC page lists the supported broker methods, the vault swap method and the errors. Other broker methods answer
400Unsupported RPC method., including broker administration:broker_withdraw_fees,broker_register_account, affiliate registration and withdrawal,broker_get_open_deposit_channelsandbroker_mark_transaction_for_rejectionstay on your old broker.
The answer is the broker's JSON-RPC answer, with address, issued_block, channel_id and source_chain_expiry_block in snake_case (the Chainflip SDK returns them camelCased).
The commission, without surprises
On your own broker, the commission you sent was the whole broker fee. On BaaS it is split:
| Slot | On your own broker | On BaaS |
|---|---|---|
| Broker commission (RPC index 3) | Your fee. | The BaaS operating fee, see Pricing. |
| First affiliate | Whatever you sent. | Your commission, credited to your affiliate account. |
| Your request value | The total broker fee. | Your commission, raised to at least the commission configured for your account. A value outside 0–995 is replaced by the configured commission, not capped. |
| User-facing total | Your fee plus any affiliate rates you supply. | Your effective commission + the BaaS operating fee + any extra affiliate rates you supply. |
Worked example with no extra affiliates: with a 10 bps commission and the 5 bps operating fee, the user pays 15 bps in broker fees. Pass 10, not 15. If you supply extra affiliates, add their rates to the user-facing total too.
The number you send as a commission is your commission, not the total the user pays. BaaS adds its operating fee on top. If you send the total, BaaS will treat it as your commission and add the operating fee again.
The same rule applies to the Chainflip SDK's brokerCommissionBps in requestDepositAddressV2. The SDK's getQuoteV2 asks Chainflip's quoting service with the commission you pass, so it does not know the BaaS operating fee and slightly overestimates the output. A BaaS /quotes quote includes both fees. Why BaaS sets the broker fee itself is explained in Commission Protection.
Migration checklist
- Register on testnet first. Create a testnet API key and open a channel against testnet without depositing. Check:
requestDepositAddressV2or your raw call returns a deposit address. - Configure your commission. Set it at registration or later on the dashboard. Check: a
/quotesanswer'sincludedFeescarries the broker fee, your commission plus the operating fee. - Verify your routes. A new account starts with every pair enabled; an account whose routes were edited may have pairs disabled, and both assets of a pair must be enabled. Check: the pairs you use answer quotes, and a channel opens, without
403. - Decide the total fee. Total = your effective commission + the BaaS operating fee + any extra affiliate rates you supply. Check: your code passes your commission, never the total.
- Point the broker URL and network. Production URL with
network: "mainnet", testnet URL withnetwork: "perseverance". Check: no401 Invalid partner.(HTTP error: 401in the SDK). - Pass refund parameters on every deposit channel. Check: no
400about refund parameters. - Cut over. A broker URL in your server's configuration switches at once. A broker URL compiled into a client app switches only as users update, so keep the old broker endpoint running for clients that still call it. Move a small share of traffic first (a canary) if your setup allows it. Check: new channels appear in your BaaS swap history and dashboard.
- Track old in-flight channels. Follow channels opened by the old broker with the SDK's
getStatusV2or the Chainflip explorer until they complete or reach their expiry block. Check: no old channel is still open. - Keep the recovery account, if you linked one. Failed deposits made through the old broker can be recovered to it; keep it and its refund addresses until the pre-cut-over channels are done.
- Withdraw the old balance. See Old fees and withdrawal. Check: the old account's earned fees are zero.
- Verify on BaaS. Check:
/feesshows your new commission, and/swapslists the new swaps. - Decommission the old broker once no client calls it, no old channel is open and its balance is withdrawn.
Old fees and withdrawal
- Fees already earned are in your old broker's State Chain account. BaaS does not take them over and cannot withdraw them, and
/feesdoes not show them. Withdraw them withbroker_withdraw_fees(an asset and a destination address; it withdraws everything earned in that asset) through your old broker's API, or with the Chainflip CLI, see Chainflip's Broker API. - Ethereum withdrawal address. If the old broker bound a fee withdrawal address with
broker_bind_fee_withdrawal_address, withdrawals of Ethereum-chain assets, USDC included, must go to that address. - FLIP for the last extrinsic. Every extrinsic a broker submits costs a small State Chain fee in FLIP, which is burned. Keep enough FLIP on the old account to submit the withdrawal.
- Existing channels opened by the old broker keep the commission and affiliate rates set when they were opened, and keep paying the old broker and its affiliates. New BaaS channels pay your effective commission plus the operating fee and any extra affiliate rates you supply: a valid requested commission above your configured minimum takes precedence; a lower or out-of-range value uses the configured minimum.
- Affiliates. If the old broker has affiliates, withdraw their balances first: an affiliate is deregistered only with a zero balance. Stop using their short IDs before deregistering them, since a released short ID is given to the next affiliate registered, see Broker Affiliates.
- Recovery account. A linked recovery account cannot be changed or removed, see Broker Account. Keep it until every pre-cut-over channel is done.
What the REST API adds
The RPC drop-in is the compatibility step: it opens swaps exactly as your broker did. The REST API is the fuller integration and can be adopted one endpoint at a time; you do not need it to migrate.
| Feature | What it gives a migrated integration |
|---|---|
| Quotes with your fee | One quote that already includes your commission and the operating fee, with recommended slippage, retry and live price values. |
| DCA and Boost quotes | DCA and Boost quotes next to the regular one. |
| Status by deposit transaction hash | Look up a swap by the user's deposit hash, including the 0x extrinsic hash of an Assethub deposit. Swaps opened through BaaS only. |
| Swap history and feed | Your completed swaps without indexing the chain yourself. Swaps recorded under your BaaS API key only. |
| Earned fees | For affiliate accounts, the commission credited to your affiliate account, per asset, excluding the operating fee. Legacy accounts without an affiliate report the broker account's earned_fees instead, which may include the operating fee. |
| Vault swap payloads | Unsigned vault swap transactions for Bitcoin, EVM chains, Solana and Tron. |
| Error codes | RFC 7807 errors with a stable code where the API classifies the failure. |
| MCP server | Quotes, swaps and status for AI agents, with your API key earning your commission. |
Troubleshooting
The Chainflip SDK throws HTTP error: <status> for any non-2xx answer and drops the message; a broker JSON-RPC error inside HTTP 200 surfaces as RPC error [code]: message. The RPC errors table lists every /rpc answer in order; Error Codes covers REST.
| Problem | REST or curl | Chainflip SDK | Fix |
|---|---|---|---|
| Wrong key, or a key from the other environment | 401 Invalid partner. | HTTP error: 401 | Use the key of the environment you call; testnet and production keys are separate. |
| Missing refund parameters | 400, Refund parameters are required: … | HTTP error: 400 | Pass retry_duration, refund_address and min_price at index 7; in the SDK, pass fillOrKillParams. |
| Unsupported method | 400 Unsupported RPC method. | HTTP error: 400, for example from encodeCfParameters | Broker administration stays on the old broker; see Supported Methods. |
| Batch or named params | 400, Batch requests with more than one call are not supported. or Object/named params are not supported, use positional array params. | Not seen: the SDK sends one positional call. | Send one call per request with a params array. |
| Pair disabled | 403 with no code on /rpc and /swap; route_disabled on quotes | HTTP error: 403 | Enable both assets of the pair in your route settings on the dashboard. |
| Wrong content type | 415 | Not seen: the SDK sends JSON. | Send Content-Type: application/json. |
| Account lookup failed for a moment | 503 with Retry-After: 2 | HTTP error: 503 | Retry after two seconds. |
| Vault swaps not enabled for the account | 400 Partner is not yet set up for vault swaps. | HTTP error: 400 from encodeVaultSwapData | Accounts registered through signup have it; contact us for an older account. |
| Wrong network for the URL | Not applicable | The channel opens on the network of the URL, while the SDK reads chain data and status from the network in network. | Set network to match the URL: mainnet for production, perseverance for testnet. |
| Old channel unknown to BaaS | 404 swap_unknown on the status endpoints | getStatusV2 follows channels of any broker; right after a channel opens it can fail with a 404 until Chainflip's backend knows the channel. | Follow old channels with getStatusV2 or the explorer; retry a 404 on a new channel after a few seconds. |
| Broker rejects a value | 200 with a JSON-RPC error from the broker | RPC error [code]: message | Fix the value the error names, such as an address format. |
FAQ
Do my old fees stay mine?
Yes. Fees you already earned are in your old broker's Chainflip account. BaaS does not take them over; withdraw them with broker_withdraw_fees before you decommission the account. Channels opened by the old broker keep paying the old broker and its affiliates at the rates set when they were opened. New BaaS swaps pay your effective commission plus the BaaS operating fee and any extra affiliate rates you supply: a valid requested commission above your configured minimum takes precedence; a lower or out-of-range value uses the configured minimum. For affiliate accounts, /fees shows the commission credited to the affiliate; legacy no-affiliate accounts report broker earnings that may include the operating fee, not balances held in your separate old broker account.
What happens to swaps already in flight?
A deposit channel is opened on-chain; the broker is not needed to execute it. Keep the old broker endpoint for clients that still call it, switch new channel creation to BaaS, and follow old in-flight channels with the Chainflip SDK's getStatusV2 or the Chainflip explorer. Chainflip's deposit channel page describes when channels close; check each channel's expiry block. BaaS status lookups only know channels opened through BaaS; for a channel the SDK opened through BaaS, the SDK's depositChannelId (issuedBlock-network-channelId) is the triple /status-by-deposit-channel takes. If the old broker has a recovery account, failed deposits made through it can still be recovered there; keep it until pre-cut-over channels are done.
Do I still need to run a broker or hold FLIP?
For new swaps, no: BaaS operates the broker and its account. Keep the old broker account and enough FLIP to submit the final broker_withdraw_fees extrinsic; after that you can decommission it.
Can I keep my current commission?
Set it in BaaS; it is not copied from the old broker. The user-facing total is your commission plus the BaaS operating fee, and a request value is your commission, not the total.
Do I have to change my code?
For the Chainflip SDK, change the broker URL and keep the network in sync; the call sites stay. For raw RPC, change the URL and use positional params; batches with more than one call and named params are rejected. For SwapKit, the current brokerUrl is a SwapKit broker-channel endpoint, not a broker RPC URL: keep SwapKit's route, or replace the deposit-channel call with BaaS /quotes and /swap. Refund parameters are required. Broker administration stays on the old broker.
What happens to my old broker account?
It remains a Chainflip account, and BaaS does not manage it. Withdraw its fees, then follow Chainflip's broker account guidance to deregister it. If a recovery account is linked, failed deposits made through the old broker can be recovered to it, and the link is irreversible: keep it and its refund addresses until pre-cut-over channels are done. Do not delete the old account's keys before the withdrawals complete.
Can I migrate only vault swaps?
Yes. The RPC drop-in's vault method is broker_request_swap_parameter_encoding; the REST API also returns unsigned vault swap payloads. Both require your account's affiliate broker account, which signup sets up; an account without it gets 400 Partner is not yet set up for vault swaps. Refund information is checked for the chains BaaS knows.
How do I test before mainnet?
Register a separate testnet API key; set the Chainflip SDK network to perseverance and the broker URL to the testnet RPC URL. Open a channel without depositing and follow its status. Testnet assets have no real value.
Sources
Checked on 2026-11-17:
- Chainflip, Brokers: broker fees, FLIP transaction fees, withdrawal through the CLI.
- Chainflip, Broker API requests:
broker_request_swap_deposit_address,broker_withdraw_fees,broker_bind_fee_withdrawal_addressand the other broker methods. - Chainflip, Broker Account: recovery account and deregistration.
- Chainflip, Broker Affiliates: deregistering an affiliate.
- Chainflip, Deposit channels and swaps: channel closure.
- Chainflip, How to use the Chainflip SDK: SDK options and the default network.
- The published
@chainflip/sdk2.3.3,@swapkit/sdk5.1.5 (@swapkit/helpers6.6.0,@swapkit/plugins5.2.5) and@swapkit/helpers4.0.0 packages: the broker and node calls the Chainflip SDK makes, and SwapKit's Chainflip configuration and deposit-channel request. - SwapKit, documentation.