# 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](https://docs.chainflip-broker.io/features/rpc/#swapkit-example). Moving from a broker you run yourself? The [migration guide](https://docs.chainflip-broker.io/features/migration/) 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](https://docs.chainflip-broker.io/features/view-fees/).

## API Endpoint

* [`POST /rpc/{apiKey}`](https://chainflip-broker.io/docs/ui/index.html#tag/Rpc/operation/brokerRpc) with `Content-Type: application/json`.
* The body is a JSON-RPC 2.0 call object with `id`, `jsonrpc` (`"2.0"`), `method` and `params`.
* 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.
* `params` is a positional array. Named (object) params are refused.

## Supported Methods

| Method | Use |
| --- | --- |
| [`broker_request_swap_deposit_address`](https://docs.chainflip-broker.io/features/rpc/#broker_request_swap_deposit_address) | Open a deposit channel. |
| [`broker_request_swap_parameter_encoding`](https://docs.chainflip-broker.io/features/rpc/#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](https://docs.chainflip-broker.io/features/rpc/#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`, `Solana` or `Tron`: a `refund_parameters` object with `retry_duration`, `refund_address` and `min_price`.
* `Bitcoin`: `min_output_amount` and `retry_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](https://docs.chainflip-broker.io/features/rpc/#vault-swap-example) and [Vault Swap Payloads](https://docs.chainflip-broker.io/features/tx-payload/).

## 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.

```json
{
  "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"
      }
    }
  ]
}
```

```json
{
  "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](https://docs.chainflip-broker.io/features/tx-payload/).

## 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

> **Tip**
>
> Want to test first? Change the API base URL to `https://perseverance.chainflip-broker.io`. The [Testing](https://docs.chainflip-broker.io/environments/testing/) environment swaps testnet assets with no real value.
>
> Swap the API key in the examples for your own [production API key](https://chainflip-broker.io/register). Testing requires a separate [testnet API key](https://perseverance.chainflip-broker.io/register).

When using the [Chainflip SDK](https://docs.chainflip.io/brokers/how-to-use-chainflip-sdk) you can provide a custom broker url to use your BaaS account:

```js
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](https://docs.chainflip-broker.io/environments/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](https://swapkit.github.io/SwapKit/) 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`](https://docs.chainflip-broker.io/features/ask-quote/) and [`/swap`](https://docs.chainflip-broker.io/features/start-swap/), as shown in the [migration guide](https://docs.chainflip-broker.io/features/migration/#swapkit).
