Liquidity Provider / Market Maker RPCs

Here are the RPCs and subscriptions that are useful for liquidity providers that are available on the State Chain.

The following RPCs are only available on chainflip-node.

WebSocket subscriptions

Example usages are using a Websocket utility such as Websocat (opens in a new tab):

cf_subscribe_prewitness_swaps

Subscribes to all potential incoming swaps of a particular direction. Swaps are only executed after a certain number of block confirmations for each chain, so this RPC allows you to see swaps that are potential but not yet confirmed. This is useful for liquidity providers to see what swaps are coming in and prepare for them.

The current number of confirmations (where 0 confirmations is just in mempool and not in a block) required for each chain is:

Chain	Confirmations
BTC	6
ETH	8
DOT	Finalisation

For BTC and ETH we use probabilistic finality, for DOT we use deterministic finality.

WARNING: Because these are witnessed before confirmation, they are not guaranteed to be executed at all or at that time, since blockchains can re-org.

Example

{"jsonrpc":"2.0","id":"1","method":"cf_subscribe_prewitness_swaps","params":["Btc", "Eth"]}

cf_subscribe_pool_price

Subscribes to the current price of a particular pool. This is useful for liquidity providers to see the current price of a pool.

It returns the price at the time of beginning the subscription as the first item in the stream. Subsequent items are only returned if there is a change in the price.

Example

Request:

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "cf_subscribe_pool_price",
  "params": ["BTC", "USDC"]
}

Response:

{
  "jsonrpc": "2.0",
  "method": "cf_subscribe_pool_price",
  "params": {
    "subscription": "Utc4MGTLsfBMbA2e",
    "result": "0x2b47c8a31e678d782bc0e8dabeed2008f13ef6"
  }
}

RPC requests

Examples are using curl.

cf_required_asset_ratio_for_range_order

Returns the ratio of assets that would be required to create a range order at the specified tick range.

Parameters:

Base Asset.
Pair Asset.
A JSON array of two i32, representing the start and end of the price range the order is over as ticks. The first number should always be less than the second.

Return:

Base and Pair Asset amounts as u256. The ratio of these two amounts is the needed ratio for range orders over the same range given the current price, i.e. the asset composition of all range orders with the same range will match this ratio.

Example

Request:

curl -H "Content-Type: application/json" \
    -d '{"id":1, "jsonrpc":"2.0", "method": "cf_required_asset_ratio_for_range_order", "params": ["Eth", "Usdc", [-400000, 400000]]}' \
    http://localhost:9944

Response:

{"jsonrpc":"2.0","result":{"base":"0x48fdda050e625251db12baf14c6258c","pair":"0x13979e2ae923a625b6119832"},"id":1}

cf_pool_info

Returns the fees percentages LP's earn in the given pool.

Parameters:

Base Asset.
Pair Asset.

Return:

The fees liquidity providers earn on swaps using their limit orders or range orders in hundredth's of a pip, i.e. 1 = 0.00001%.

Example

Request:

curl -H "Content-Type: application/json" \
    -d '{"id":1, "jsonrpc":"2.0", "method": "cf_pool_info", "params": {"base_asset": "ETH", "pair_asset": "USDC"}}' \                   
    http://localhost:9944

Response:

{
  "jsonrpc": "2.0",
  "result": {
    "limit_order_fee_hundredth_pips": 20,
    "range_order_fee_hundredth_pips": 20
  },
  "id": 1
}

cf_pool_depth

Returns depth of a specified pool between two prices.

Parameters:

Base Asset.
Pair Asset.
A JSON array of two ticks as i32, representing the range of prices over which depth will be calculated. The first number should always be less than the second.

Return:

The amount of each of the pool's two assets available for sale inside the given price range. The depth of limit orders and range orders at separately stated.

Example

Request:

curl -H "Content-Type: application/json" -d '{"id":1, "jsonrpc":"2.0", "method": "cf_pool_depth", "params": ["ETH", "USDC", [0, 1000]]}' http://localhost:9944

Response:

{
  "jsonrpc": "2.0",
  "result": {
    "base": {
      "limit_orders": { "price": null, "depth": "0x0" },
      "range_orders": {
        "price": "0x15d21b1217b76a34437fca3a9",
        "depth": "0x8c3f38916066"
      }
    },
    "pair": {
      "limit_orders": { "price": null, "depth": "0x0" },
      "range_orders": { "price": "0x15d21b1217b76a34437fca3a9", "depth": "0x0" }
    }
  },
  "id": 1
}

cf_pool_liquidity

Returns all the liquidity available for swaps in a particular pool.

Parameters:

Base Asset.
Pair Asset.

Return:

For limit orders two lists of prices (as ticks) and the amount/depth available at those prices.
For range orders, an ordered list of pairs. The first element of the pair is a tick/price and the second is the liquidity between that tick and the next tick in the list. Forming a histogram of the liquidity in the range order pool.

Example

Request:

curl -H "Content-Type: application/json" \
    -d '{"id":1, "jsonrpc":"2.0", "method": "cf_pool_liquidity", "params": {"base_asset": "ETH", "pair_asset": "USDC"}}' \
    http://localhost:9944

Response:

{
  "jsonrpc": "2.0",
  "result": {
    "limit_orders": { "base": [], "pair": [] },
    "range_orders": [
      [-887272, 3161961432402363],
      [887272, 0]
    ]
  },
  "id": 1
}

cf_pool_orders

Returns all the orders associated with a specified account in a particular pool.

Parameters:

Base Asset.
Pair Asset.
The account to return the orders of.

Return:

Example

Request:

curl -H "Content-Type: application/json" \
    -d '{"id":1, "jsonrpc":"2.0", "method": "cf_pool_orders", "params": {"base_asset": "ETH", "pair_asset": "USDC", "lp": "cFPdef3hF5zEwbWUG6ZaCJ3X7mTvEeAog7HxZ8QyFcCgDVGDM"}}' \
    http://localhost:9944

Response:

{
  "jsonrpc": "2.0",
  "result": {
    "limit_orders": { "base": [], "pair": [] },
    "range_orders": [[0, { "start": -887272, "end": 887272 }, 3161961432402363]]
  },
  "id": 1
}

cf_pool_range_order_liquidity_value

Returns the value of a hypothetical range order, e.g. the assets would would be returned to an LP's free balance if they were to close/cancel such a range order.

Parameters:

Base Asset.
Pair Asset.
A JSON array of two i32, representing the start and end of the price range the order is over as ticks. The first number should always be less than the second.
The liquidity of the range order as an amount.

Return:

The value of the hypothetical range order if it where burnt now, in amounts of the base and pair assets.

Example

Request:

curl -H "Content-Type: application/json" \
    -d '{"id":1, "jsonrpc":"2.0", "method": "cf_pool_range_order_liquidity_value", "params": {"base_asset": "Eth", "pair_asset": "Usdc", "tick_range": [0, 1000], "liquidity": 10000000000}}' \
    http://localhost:9944

Response:

{ "jsonrpc": "2.0", "result": { "base": "0x1d116fb8", "pair": "0x0" }, "id": 1 }

LP API Working Example