Liquidity Provider / Market Maker RPCs

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

WebSocket subscriptions

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

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

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

RPC requests

Example usages 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 as a camel-case string, e.g. "Eth" or "Dot".
Pair Asset as a camel-case string, e.g. "Eth" or "Dot".
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 lps earn in the given pool.

Parameters:

Base Asset as a camel-case string, e.g. "Eth" or "Dot".
Pair Asset as a camel-case string, e.g. "Eth" or "Dot".

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": ["Eth", "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 as a camel-case string, e.g. "Eth" or "Dot".
Pair Asset as a camel-case string, e.g. "Eth" or "Dot".
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 as a camel-case string, e.g. "Eth" or "Dot".
Pair Asset as a camel-case string, e.g. "Eth" or "Dot".

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 as a camel-case string, e.g. "Eth" or "Dot".
Pair Asset as a camel-case string, e.g. "Eth" or "Dot".
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 LPs free balance if they were to close/cancel such a range order.

Parameters:

Base Asset as a camel-case string, e.g. "Eth" or "Dot".
Pair Asset as a camel-case string, e.g. "Eth" or "Dot".
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 a u128.

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