Broker API Requests

Broker-API Methods

`broker_request_swap_deposit_address`

Parameters:

source_asset: Source asset.
destination_asset: Egress asset.
destination_address: Egress Address.
broker_commission: Broker Commission in basis points (100th of a percent or 0.01%). Broker operators can choose to charge a fee for the use of their endpoint, and can be set at any value from 1 basis point to 1000 basis points (0.01% - 10%).
channel_metadata: (Optional) Json object with the cross-chain messaging metadata:
- message: Hex encoded call data used after the message is egressed.
- gas_budget: The amount of gas or compute units required by the user logic on the destination chain.
- ccm_additional_data: Hex encoded additional data for the cross-chain message. Should be an empty array except for CCM Swaps to Solana.
boost_fee: (Optional) Maximum accepted boost fee in basis points (100th of a percent).
affiliate_fees: (Optional) Array of affiliate brokers (up to 5) [{"account": <AccountId>, "bps": <number>}].
refund_parameters: (Optional) Slippage protection for swaps through the channel as JSON object: {"retry_duration": <number>, "refund_address": <address>, "min_price": <hex_string>, "max_oracle_price_slippage": <number | undefined>}. Where retry_duration is a number of blocks, refund_address is an address, and min_price is a price, and max_oracle_price_slippage is basis points.
dca_parameters: (Optional) DCA parameters for swaps through the channel as JSON object: {"number_of_chunks": <number>, "chunk_interval": <number>}. Where number_of_chunks is the number of “sub-swaps” to perform, and chunk_interval is the delay between them in number of blocks.

Where every affiliate broker is defined as follow:


{
	"account": <AccountId>,
	"bps": <BasisPoints>,
}

The total broker fee is the sum of the broker_commission + all the affiliate_fees.

Return:

deposit address.

`broker_register_account`

Parameters:

None

Return:

null if successful, otherwise an error.


curl 'http://localhost/' \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "broker_register_account"}' | jq

`broker_withdraw_fees`

Withdraw all accumulated fees for a given asset.

Parameters:

asset: The asset to withdraw.
destination_address: The destination address to which the assets should be withdrawn.

Return:

tx_hash: Hash,
egress_id: [ForeignChain, Number],
egress_amount: Amount,
egress_fee: Amount,
destination_address: Address,

Example input:


curl 'http://localhost/' \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "broker_withdraw_fees", "params": {"asset": {"chain": "Ethereum", "asset": "ETH"}, "destination_address": "0xabababababababababababababababababababab"}}' | jq

Example output:


{
  "jsonrpc": "2.0",
  "result": {
    "tx_hash": "0x736c159fec96ea84b8eceb49258019625a17e68ab981a3a674261e1df00a0482",
    "egress_id": [
      "Ethereum",
      103
    ],
    "egress_amount": 99998499999503000,
    "egress_fee": 490000,
    "destination_address": "0xabababababababababababababababababababab"
  },
  "id": 1
}

`broker_mark_transaction_for_rejection`

Request an incoming transaction to be rejected. Only available for bitcoin. This call will always succeed, but the transaction will only be refunded if it hasn’t been witnessed on-chain yet. For un-boosted channels this means prior to 6 blocks confirmation, for boosted channels its prior to 1 block confirmation, i.e. only while the transaction is in the mempool. Also, a broker can only mark transactions going into its own deposit-channels for rejection.

Parameters:

tx_id: The transaction id of the transaction to be rejected. Only bitcoin is supported, the transaction hash has to be specified as shown in the example below. Also, note that the byte order of the hash is in reverse to the usual representation in bitcoin block explorers.

Return:

Nothing if transaction was successfully marked for rejection, error message otherwise.

Example input:


curl 'http://localhost/' \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "broker_mark_transaction_for_rejection", "params": {"tx_id": {"Bitcoin": "0x736c159fec96ea84b8eceb49258019625a17e68ab981a3a674261e1df00a0482"}}}' | jq

Example output (success):


{
  "jsonrpc": "2.0",
  "result": "null",
  "id": 1
}

`broker_get_open_deposit_channels`

Return all deposit channels which have been opened and are relevant for broker_mark_transaction_for_rejection. Only returns bitcoin channels.

Parameters:

query: Which deposit channels to take into account. Possible values are Mine and All.

Return:

All currently open bitcoin deposit channels that match query.

Example input:


curl 'http://localhost/' \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "broker_get_open_deposit_channels", "params": {"query": "Mine"}}' | jq

Example output:


{
  "jsonrpc": "2.0",
  "result": {
    "btc_chain_accounts": [
      {
        "Taproot": [ ... ]
      },
      {
        "Taproot": [ ... ]
      },
      {
        "Taproot": [ ... ]
      }
    ]
  },
  "id": 1
}

`broker_request_swap_parameter_encoding`

Create an encoded swap with the given parameters. The encoding depends on the chain of the input asset. See Vault Swaps for more details.

Parameters:

source_asset: The source asset who’s chain we are encoding for.
destination_asset: Egress asset.
destination_address: Egress Address.
broker_commission: Broker Commission in basis points (100th of a percent).
extra_parameters: JSON object with different data depending on the chain of the input asset.
- chain: The chain of the input asset. Use only one of the following, then provide the corresponding parameters:
  - Bitcoin:
    - min_output_amount: Minimum output amount in the smallest unit of the output asset.
    - retry_duration: Number of blocks to wait before refunding the swap.
    - max_oracle_price_slippage: Live price protection in basis points (100th of a percent) as a u8 number (set to 255 to disable).
  - Ethereum or Arbitrum:
    - input_amount: Amount of the input asset in the smallest unit.
    - refund_parameters: JSON object: {"retry_duration": <number>, "refund_address": <address>, "min_price": <hex_string>, "max_oracle_price_slippage": <number | undefined>}. See broker_request_swap_deposit_address for more details.
  - Solana:
    - from: Address of the sender.
    - event_data_account: Address of the event data account.
    - input_amount: Amount of the input asset in the smallest unit.
    - refund_parameters: JSON object: {"retry_duration": <number>, "refund_address": <address>, "min_price": <hex_string>, "max_oracle_price_slippage": <number | undefined>}. See broker_request_swap_deposit_address for more details.
    - from_token_account: (Optional) Associated token account (ATA) of the from account.
channel_metadata: (Optional) Json object with the cross-chain messaging metadata:
- message: Hex encoded call data used after the message is egressed.
- gas_budget: The amount of gas or compute units required by the user logic on the destination chain.
- ccm_additional_data: Hex encoded additional data for the cross-chain message. Should be an empty array except for CCM Swaps to Solana.
boost_fee: (Optional) Maximum accepted boost fee in basis points (100th of a percent).
affiliate_fees: (Optional) Array of affiliate brokers (up to 5) [{"account": <AccountId>, "bps": <number>}].
dca_parameters: (Optional) DCA parameters for swaps through the channel as JSON object: {"number_of_chunks": <number>, "chunk_interval": <number>}. Where number_of_chunks is the number of “sub-swaps” to perform, and chunk_interval is the delay between them in number of blocks.

Return:

Encoded swap data depending on the input asset chain. See vault swaps for more details.

Example usage:


curl -H "Content-Type: application/json" -d '
{
   "id":1,
   "jsonrpc":"2.0",
   "method":"broker_request_swap_parameter_encoding",
"params":
  {
    "source_asset": "BTC",
    "destination_asset": "ETH",
    "destination_address": "0xabababababababababababababababababababab",
    "broker_commission": 10,
    "extra_parameters":
      {
        "chain": "Bitcoin",
        "min_output_amount": 0,
        "retry_duration": 0
      }
  }
}' http://my-broker-api:9944

Example output:


{
  "chain": "Bitcoin",
  "nulldata_payload": "0x0001abababababababababababababababababababab00000000000000000000000000000000000001000200000000",
  "deposit_address": "bcrt1phs8wzjf79ga4y04ses8alz4dgjlz0jdx0r8uat6w04e5xcvqtqkqe4rx3c"
}

`broker_decode_vault_swap_parameter`

The Inverse of broker_request_swap_parameter_encoding: decode a vault swap output, returning the input parameters.

See Vault Swaps for more details.

Parameters:

vault_swap: The vault swap output produced by the broker_request_swap_parameter_encoding rpc call.
bitcoin:
nulldata_payload: encoded payload for the vault swap.
deposit_address: the address the btc should be deposited into.
ethereum and arbitrum:
details:
calldata: encoded payload for the vault swap.
value: the amount of eth to be transferred.
to: vault address for Ethereum or Arbitrum.
solana:
instruction:
program_id: address of the smart program that will execute this vault swap.
accounts: accounts with metadata needed for this vault swap.
data: encoded payload for the vault swap/solana instruction.

Return:

Input parameter for the given vault swap. See vault swaps for more details.

source_asset: Source asset for the vault swap.
destination_asset: Egress asset.
destination_address: Egress Address.
broker_commission: Broker Commission in basis points (100th of a percent).
extra_parameters: JSON object with different data depending on the chain of the input asset.
chain: The chain of the input asset. Use only one of the following, then provide the corresponding parameters:
Bitcoin:
min_output_amount: Minimum output amount in the smallest unit of the output asset.
retry_duration: Number of blocks to wait before refunding the swap.
Ethereum or Arbitrum:
input_amount: Amount of the input asset in the smallest unit.
refund_parameters: JSON object: {"retry_duration": <number>, "refund_address": <address>, "min_price": <hex_string>}. See broker_request_swap_deposit_address for more details.
Solana:
from: Address of the sender.
event_data_account: Address of the event data account.
input_amount: Amount of the input asset in the smallest unit.
refund_parameters: JSON object: {"retry_duration": <number>, "refund_address": <address>, "min_price": <hex_string>}. See broker_request_swap_deposit_address for more details.
from_token_account: Associated token account (ATA) of the from account.
channel_metadata: Json object with the cross-chain messaging metadata:
message: Hex encoded call data used after the message is egressed.
gas_budget: The amount of gas or compute units required by the user logic on the destination chain.
ccm_additional_data: Hex encoded additional data for the cross-chain message. Should be an empty array except for CCM Swaps to Solana.
boost_fee: Maximum accepted boost fee in basis points (100th of a percent).
affiliate_fees: Array of affiliate brokers (up to 5) [{"account": <AccountId>, "bps": <number>}].
dca_parameters: DCA parameters for swaps through the channel as JSON object: { "number_of_chunks": <number>, "chunk_interval": <number> }. Where number_of_chunks is the number of “sub-swaps” to perform, and chunk_interval is the delay between them in number of blocks.

Example usage:


curl -H "Content-Type: application/json" -d '{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "broker_decode_vault_swap_parameter",
    "params": [ {
        "chain": "Bitcoin",
        "nulldata_payload": "0x0001abababababababababababababababababababab00000000000000000000000000000000000001000200000000",
        "deposit_address": "bcrt1phs8wzjf79ga4y04ses8alz4dgjlz0jdx0r8uat6w04e5xcvqtqkqe4rx3c"
    }]
}' http://localhost:10997

Example output:


{
  "jsonrpc": "2.0",
  "result": {
    "source_asset": {
      "chain": "Bitcoin",
      "asset": "BTC"
    },
    "destination_asset": {
      "chain": "Ethereum",
      "asset": "ETH"
    },
    "destination_address": "0xabababababababababababababababababababab",
    "broker_commission": 0,
    "extra_parameters": {
      "chain": "Bitcoin",
      "min_output_amount": "0x0",
      "retry_duration": 0
    },
    "channel_metadata": null,
    "boost_fee": 0,
    "affiliate_fees": [],
    "dca_parameters": {
      "number_of_chunks": 1,
      "chunk_interval": 2
    }
  },
  "id": 1
}

`broker_encode_cf_parameters`

Validates and encode the cf_parameter needed as part of a Vault Swap call. See Vault Swaps and Chainflip parameters for more details.

Parameters:

source_asset: The source asset who’s chain we are encoding for.
destination_asset: Egress asset.
destination_address: Egress Address.
broker_commission: Broker Commission in basis points (100th of a percent).
refund_parameters: JSON object: {"retry_duration": <number>, "refund_address": <address>, "min_price": <hex_string>}. See broker_request_swap_deposit_address for more details.
channel_metadata: (Optional) Json object with the cross-chain messaging metadata:
message: Hex encoded call data used after the message is egressed.
gas_budget: The amount of gas or compute units required by the user logic on the destination chain.
ccm_additional_data: Hex encoded additional data for the cross-chain message. Should be an empty array except for CCM Swaps to Solana.
boost_fee: (Optional) Maximum accepted boost fee in basis points (100th of a percent).
affiliate_fees: (Optional) Array of affiliate brokers (up to 5) [{"account": <AccountId>, "bps": <number>}].
dca_parameters: (Optional) DCA parameters for swaps through the channel as JSON object: {"number_of_chunks": <number>, "chunk_interval": <number>}. Where number_of_chunks is the number of “sub-swaps” to perform, and chunk_interval is the delay between them in number of blocks.

Return:

Encoded cf_parameters as raw bytes.

Example usage:


curl -H "Content-Type: application/json" -d '{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "broker_encode_cf_parameters",
    "params": [
        { "chain": "Ethereum", "asset": "ETH" },
        { "chain": "Solana", "asset": "SOL" },
        "BdyHK5DckpAFGcbZveGLPjjMEaADGfNeqcRXKoyd33kA",
        0,
        {
            "retry_duration": 10,
            "refund_address": "0xc64722AD9613851b10E26fF8118A7696A0f956f2",
            "min_price": "0x0"
        },
        {
            "message": "0x0011223344556677",
            "gas_budget": 1000,
            "ccm_additional_data": "007417da8b99d7748127a76b03d61fee69c80dfef73ad2d5503737beedc5a9ed480104a73bdf31e341218a693b8772c43ecfcecd4cf35fada09a87ea0f860d028168e50090e0b0f5b60147b325842c1fc68f6c90fe26419ea7c4afeb982f71f1f54b5b44"
        }
    ]
}' http://my-broker-api:9944

Example output:


{
  "jsonrpc": "2.0",
  "result": "0x009101007417da8b99d7748127a76b03d61fee69c80dfef73ad2d5503737beedc5a9ed480104a73bdf31e341218a693b8772c43ecfcecd4cf35fada09a87ea0f860d028168e50090e0b0f5b60147b325842c1fc68f6c90fe26419ea7c4afeb982f71f1f54b5b440a000000c64722ad9613851b10e26ff8118a7696a0f956f2000000000000000000000000000000000000000000000000000000000000000000009059e6d854b769a505d01148af212bf8cb7f8469a7153edce8dcaedd9d299125000000",
  "id": 1
}

`broker_open_private_btc_channel`

A private Bitcoin channel is a dedicated persistent deposit channel unique to a single broker.

Opening a private Bitcoin channel is a requirement for Brokers who wish to support Vault Swaps with Bitcoin as the source asset. This is a one-time operation and requires the Broker to post a bond of 100 $FLIP, meaning the Broker must maintain a balance of at least 100 FLIP. The bond will be unlocked once the Broker closes the channel again.

Note that even though the channel is considered persistent, the corresponding deposit address will change every Epoch.

Private Channels are not required unless the Broker wishes to support Vault Swaps with Bitcoin as source asset.

Parameters: None

Return: The channel ID (Number)

`broker_close_private_btc_channel`

Close the private Bitcoin deposit channel. The bond will be returned to your free balance.

Parameters: None

Return: The channel ID (Number)

`broker_register_affiliate`

Registers an affiliate account and returns the account id of the affiliate.

Parameters:

withdrawal_address: The withdrawal address of the affiliate.

Return:

The account id of the affiliate.

Example input:


curl 'http://localhost/' \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "broker_register_affiliate", "params": {"withdrawal_address": "0x3499b9b27ec38fe019299498958c451d294f6b5e"}}' | jq

Example output:


{
  "jsonrpc": "2.0",
  "result": "cFPS1XY681MaJZUKMQ1fEwThFGZveDkpgkwinsJRC24sRG1MR",
  "id": 1
}

`broker_affiliate_withdrawal_request`

Request a withdrawal of the affiliate’s collected commissions. The affiliate will receive the funds to their registered withdrawal address.

Parameters:

affiliate_account_id: The account id of the affiliate.

Return:

TxHash: The transaction hash of state chain extrinsic.
EgressId: The egress id of the withdrawal.
EgressAmount: The amount of the withdrawal.
EgressFee: The fee of the withdrawal.
DestinationAddress: The destination address of the withdrawal.

Example input:


curl 'http://localhost/' \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "broker_affiliate_withdrawal_request", "params": {"affiliate_account_id": "cFPS1XY681MaJZUKMQ1fEwThFGZveDkpgkwinsJRC24sRG1MR"}}' | jq

Example output:


{
  "jsonrpc": "2.0",
  "result": {
    "tx_hash": "0x2b130acc1b3d56f8caff1e1adc32b8fbcc25c5ce0d9daa559d073e438c136ce1",
    "egress_id": [
      "Ethereum",
      174
    ],
    "egress_amount": "0x6d4186e",
    "egress_fee": "0x1843a",
    "destination_address": "0x015c2baa0c23ce4340eb24ca0562883084aacef3"
  },
  "id": 1
}

`broker_get_affiliates`

Get a list of all affiliates registered to your broker account.

Parameters: None

Return: Array of registered Affiliate Account IDs and Affiliate Details: [[<AffiliateId>, {"short_id": <ShortId>, "withdrawal_address": <EthereumAddress>}]].

Example input:


curl 'http://localhost/' \
  -H 'accept: application/json' \
  -H 'content-type: application/json' \
  --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "broker_get_affiliates", "params": []}' | jq

Example output:


{
  "jsonrpc": "2.0",
  "result": [
    [
      "cFNGCP7MUJCbRyktHizaYnEekiTAPp1Sgopsbt99FNWc6Q1LU",
      {
        "short_id": 0,
        "withdrawal_address": "0xa646ff46ce321cf4259caa01bcc71b54a333532c"
      }
    ]
  ],
  "id": 1
}