Chainflip Broker RPC API
RPC Drop-In is a JSON-RPC endpoint compatible with the native Chainflip broker, provided as a migration path: code written against the native broker and the Chainflip SDK works with BaaS by changing only the broker URL. SwapKit's broker URL setting is not a JSON-RPC endpoint, see Swapkit Example. Moving from a broker you run yourself? The migration guide covers the commission, refunds, old fees and the cut-over.
Details
The endpoint takes the broker methods the Chainflip SDK uses to open swaps, one JSON-RPC 2.0 call per request. Calls go through BaaS before they reach the broker: your configured commission is enforced, the refund information Chainflip requires is checked, and your route settings apply.
Swaps opened through this endpoint earn your commission like any other BaaS swap; earned fees are on /fees, see View Earned Fees.
API Endpoint
POST /rpc/{apiKey}withContent-Type: application/json.- The body is a JSON-RPC 2.0 call object with
id,jsonrpc("2.0"),methodandparams. - One call per request. A JSON array is accepted only when it holds exactly one call; a successful answer to it comes back wrapped in an array.
paramsis a positional array. Named (object) params are refused.
Supported Methods
| Method | Use |
|---|---|
broker_request_swap_deposit_address | Open a deposit channel. |
broker_request_swap_parameter_encoding | Encode a vault swap. |
Both methods also accept camelCase aliases, such as the Chainflip SDK's broker_requestSwapDepositAddress, and reach the broker in snake_case. A method the endpoint does not support answers 400 Unsupported RPC method..
Both methods enforce your commission the same way. The commission passed at index 3, in basis points, is raised to at least the commission configured for your account (a value out of range is replaced by it) and injected as the first affiliate entry. Index 3 then carries BaaS's commission. Affiliates you pass follow your entry, five entries at most.
A recognised asset that is disabled or cannot be swapped in the requested direction, such as relay-chain DOT (dot.dot), is refused with 400 and never reaches the broker; DOT is dot.hub. When both assets are recognised, a pair disabled in your route settings answers 403. An asset BaaS does not recognise is left to the broker. See Errors.
broker_request_swap_deposit_address
Opens a deposit channel, like the native broker. It takes at least eight positional params: source asset, destination asset, destination address, commission, CCM metadata, boost fee, affiliates and refund parameters. Further params are passed on to the broker.
The refund parameters at index 7 are required on every chain: an object with retry_duration, refund_address and min_price, none of them null or blank. BaaS checks that they are present; the broker validates their values.
broker_request_swap_parameter_encoding
Encodes a vault swap, like the native broker. It takes at least five positional params: source asset, destination asset, destination address, commission and extra_parameters. BaaS fills in a missing CCM metadata (index 5), boost fee (index 6) and affiliates (index 7).
The refund information sits in extra_parameters, and BaaS checks it by the chain tag there:
Ethereum,Arbitrum,Bsc,SolanaorTron: arefund_parametersobject withretry_duration,refund_addressandmin_price.Bitcoin:min_output_amountandretry_duration.- Any other or missing tag is left to the broker, which rejects a call that lacks what its chain needs.
The answer depends on the source chain; see Vault Swap Example and Vault Swap Payloads.
Vault Swap Example
An example, not a live capture: an Ethereum broker_request_swap_parameter_encoding call in its minimal five-param form, and the shape of the broker's answer. Replace the placeholders before use: "input_amount": "0x1" is the amount you will send, and "min_price": "0x0" means no price protection. The answer's values are placeholders too.
{
"id": 1,
"jsonrpc": "2.0",
"method": "broker_request_swap_parameter_encoding",
"params": [
{ "chain": "Ethereum", "asset": "ETH" },
{ "chain": "Bitcoin", "asset": "BTC" },
"bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq",
20,
{
"chain": "Ethereum",
"input_amount": "0x1",
"refund_parameters": {
"retry_duration": 150,
"refund_address": "0x36771dab37bfa7d380f80db0b40895bc60d24e76",
"min_price": "0x0"
}
}
]
}
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"chain": "Ethereum",
"calldata": "0x00",
"value": "0x0",
"to": "0x0000000000000000000000000000000000000001",
"source_token_address": null
}
}
Arbitrum and BSC answers have the same fields. Bitcoin, Solana and Tron answers carry other fields: Bitcoin a nulldata_payload and deposit_address, Solana a program_id, accounts and data, Tron a note next to the EVM fields. To get a ready-to-sign transaction from the REST API instead, see Vault Swap Payloads.
Errors
Checks run top to bottom, and the first failing check answers. Every non-200 answer is a bare object, never wrapped in an array, even for a one-element array request. Problem bodies are application/problem+json with the message in detail unless the row says otherwise.
| Order | Status | Message | When |
|---|---|---|---|
| 1 | 503 | Could not resolve the partner for this request. Please retry shortly. (title Service Unavailable, header Retry-After: 2) | Looking up your account failed for a moment; retry. |
| 2 | 415 | Empty body. | Content-Type is not application/json. |
| 3 | 400 | title One or more validation errors occurred. with the JSON parser's message, or A non-empty request body is required., under errors; no detail | The body is not valid JSON, is empty, or is null. |
| 4 | 400 | Batch requests with more than one call are not supported. | A JSON array that does not hold exactly one call, [] included. |
| 5 | 400 | Object/named params are not supported, use positional array params. | params is an object. |
| 5 | 400 | Invalid RPC object. | Valid JSON that is not a call object: id, jsonrpc, method or params missing or of the wrong type, or an array element that is not a call. |
| 6 | 401 | Invalid partner. | Unknown API key. |
| 7 | 400 | Unsupported RPC method. | A method the endpoint does not support. |
| 8 | 400 | Partner is not yet set up for vault swaps. | broker_request_swap_parameter_encoding before vault swaps are enabled for your account. |
| 9 | 400 | Invalid number of RPC params. | Fewer than eight broker_request_swap_deposit_address params, or fewer than five broker_request_swap_parameter_encoding params. |
| 10 | 400 | Refund parameters are required: refund_parameters (params[7]) must be an object with retry_duration, refund_address and min_price. | broker_request_swap_deposit_address without complete refund parameters, on every chain. |
| 10 | 400 | Refund parameters are required: extra_parameters (params[4]) must carry refund_parameters with retry_duration, refund_address and min_price. | broker_request_swap_parameter_encoding whose chain tag is Ethereum, Arbitrum, Bsc, Solana or Tron, without complete refund_parameters. |
| 10 | 400 | Refund information is required: Bitcoin extra_parameters (params[4]) must carry min_output_amount and retry_duration. | broker_request_swap_parameter_encoding whose chain tag is Bitcoin, without both fields. |
| 11 | 400 | Source Asset not enabled to swap from., Source Asset not supported to swap from., Destination Asset not enabled to swap to. or Destination Asset not supported to swap to. | A recognised asset is disabled, such as relay-chain DOT (dot.dot), or cannot be swapped in that direction. |
| 12 | 403 | Swaps from <SOURCE> to <DESTINATION> are not enabled for your account., with asset tickers such as BTC and ETH | Both assets are recognised and the pair is disabled in your route settings. |
| 13 | 500 | Something went wrong while making RPC call. | The broker call failed, answered a non-2xx status, or returned an empty body. |
| 14 | 200 | The broker's answer unchanged, wrapped in an array for a one-element array request | The broker answered with a JSON-RPC error, for example {"jsonrpc":"2.0","id":1,"error":{"code":-32602,"message":"Invalid params","data":"Base 58 requirement is violated at line 1 column 154"}}. |
Chainflip SDK Example
Want to test first? Change the API base URL to https://perseverance.chainflip-broker.io. The Testing environment swaps testnet assets with no real value.
Swap the API key in the examples for your own production API key. Testing requires a separate testnet API key.
When using the Chainflip SDK you can provide a custom broker url to use your BaaS account:
import { SwapSDK } from '@chainflip/sdk/swap';
const options = {
network: 'mainnet', // Mainnet
broker: {
url: 'https://chainflip-broker.io/rpc/87517a91d5f34dbabfc1e410946a3a3c',
},
};
const swapSDK = new SwapSDK(options);
To test against the Testing environment instead, set network: 'perseverance' and point the broker URL at https://perseverance.chainflip-broker.io/rpc/YOUR_TESTNET_API_KEY — the Chainflip SDK requires both values to change together.
Swapkit Example
The Swapkit SDK is not a broker URL drop-in. Its current config.integrations.chainflip.brokerUrl setting points at a SwapKit broker-channel endpoint, which receives SwapKit's own request body rather than a JSON-RPC call, so pointing it at /rpc does not work. Older SwapKit releases configured a chainflipBrokerConfig instead; current releases no longer have it.
To route SwapKit swaps through BaaS, replace SwapKit's deposit-channel call with /quotes and /swap, as shown in the migration guide.