Integration
Liquidity Provision
LP API

LP API

These docs are under active development. 🚧

The LP API bundle exposes a JSON API that allows liquidity providers to put up orders programmatically through the JIT AMM. It connects to a State Chain node, and handles the complexities of submitting and monitoring extrinsics, allowing for simpler integration.

Please also see the LP RPCs documentation for information on RPCs and subscriptions exposed by the State Chain directly.

Command line arguments

The ws_endpoint should point at a synced RPC node, the signing_key_file should be the private key for their on-chain account, and that account should already be funded.

> ./target/release/chainflip-lp-api --help
 
chainflip-lp-api
 
USAGE:
    chainflip-lp-api [OPTIONS]
 
OPTIONS:
    -h, --help
            Print help information
 
        --state_chain.signing_key_file <SIGNING_KEY_FILE>
            [default: /etc/chainflip/keys/signing_key_file]
 
        --state_chain.ws_endpoint <WS_ENDPOINT>
            [default: ws://localhost:9944]

RPC Methods

lp_register_account

Parameters:

None

Return:

  • null if successful, otherwise an error.

lp_liquidity_deposit

Parameters:

  • Asset to be deposited as a camel-case string, e.g. "Eth" or "Dot".

Return:

  • Encoded deposit address that you should send the deposit to.

Example:

  • Request

    curl -H "Content-Type: application/json" -d '{"id":1, "jsonrpc":"2.0", "method": "lp_liquidity_deposit", "params": ["Eth"]}' http://localhost:10589

  • Response

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

lp_register_liquidity_refund_address

Parameters:

  • The external chain as a camel-case string, e.g. "Ethereum" or "Polkadot".
  • The withdraw address for the specified external chain, the format of which depends on the external chain, e.g. ss58 encoding for "Polkadot" withdrawal addresses. Each on-chain account can have a single withdrawal address for each supported external chain. Any assets associated with that chain will be transferred there if a refund is needed, e.g. "USDC" would be tranferred to the address associated with "Ethereum".

Return:

  • The transaction hash of the extrinsic that registered the new withdrawal address.

Example:

  • Request

    curl -H "Content-Type: application/json" -d '{"id":1, "jsonrpc":"2.0", "method": "lp_register_liquidity_refund_address", "params":  ["Ethereum", "0x71C7656EC7ab88b098defB751B7401B5f6d8976F"]}' http://localhost:10589

  • Response

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

lp_withdraw_asset

Parameters:

  • Asset amount to be withdrawn as u128.
  • Withdrawn asset as a camel-case string, e.g. "Eth" or "Dot".
  • Withdraw address, where the format depends on which external chain the asset is associated with, e.g. ss58 encoding for "Dot", as "Dot" is from the external chain "Polkadot" which uses ss58 encoded addresses.

Return:

  • Egress id, which is used as the identifier for the operation/s to egress/withdraw the requested funds.

Example:

  • Request

    curl -H "Content-Type: application/json" -d '{"id":1, "jsonrpc":"2.0", "method": "lp_withdraw_asset", "params": [1000, "Usdc", "0x71C7656EC7ab88b098defB751B7401B5f6d8976F"]}' http://localhost:10589

  • Response

    {"jsonrpc":"2.0","result":["Ethereum",48],"id":1}

lp_update_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".
  • Range order id as u64.
  • (Optional) A JSON array of two i32, representing the start and end of the price range the order is over. If not specified the previous tick range of this order id will be used. The first number should always be less than the second.
  • Whether you intend to increase or decrease the size of the order, e.g. "Increase" or "Decrease".
  • A JSON object specifying how much to change the order. This can be provided in two different ways:
    1. {"Liquidity": {"liquidity": <liquidity>}} where <liquidity> is a u128 or a hex string specifying the size of the order in microUSDC
    2. {"AssetAmounts":{"maximum":{"base": <amount>, "pair": <amount>}, "minimum":{"base": <amount>, "pair: <amount>}}} where the <amounts> are u128 or hex strings specifying the size of the order in smallest units of the respective asset (base or pair), e.g. For Bitcoin it is in Satoshis. Using "AssetAmounts", the system will try to the change the order by an amount of assets between the specified maximum and minimums. If you would not like to change the size of the order you can specify zero values using either "Liquidity" or "AssetAmounts".

Return:

  • A chronological list of all the updates that were done as part of the operation. Each item in the list is a JSON object: { "tick_range": [<tick>, <tick>], "liquidity_total": <liquidity>, "collected_fees": { "base": <amount> , "pair": <amount> }, "increase_or_decrease": <increase_or_decrease>, "liquidity_delta": <liquidity>, "assets_delta": { "base": <amount> , "pair": <amount> } } For example if a lp_updateRangeOrder request moves an existing range order to a new tick_range, the return would contain two of these, one for the decrease to zero/destruction of the order at the previous tick range, and then one for the increase/creation of the order at the new tick range.

lp_set_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".
  • Range order id as u64.
  • (Optional) A JSON array of two i32, representing the start and end of the price range the order is over. If not specified the previous tick range of this order id will be used. The first number should always be less than the second.
  • A JSON object specifying the new size of the order. This can be provided in two different ways:
    1. {"Liquidity": <liquidity>} where <liquidity> is a u128 or a hex string specifying the size of the order in microUSDC
    2. {"AssetAmounts":{"maximum":{"base": <amount>, "pair": <amount>}, "minimum":{"base": <amount>, "pair: <amount>}}} where the <amounts> are u128 or hex strings specifying the size of the order in smallest units of the respective asset (base or pair), e.g. For Bitcoin it is in Satoshis. Using "AssetAmounts", the system will try to the create an order that consumes an amount of assets between the specified maximum and minimums. If you would like to close the order you can specify zero values using either "Liquidity" or "AssetAmounts".

Return:

  • A chronological list of all the updates that were done as part of the operation. Each item in the list is a JSON object: { "tick_range": [<tick>, <tick>], "liquidity_total": <liquidity>, "collected_fees": { "base": <amount> , "pair": <amount> }, "increase_or_decrease": <increase_or_decrease>, "liquidity_delta": <liquidity>, "assets_delta": { "base": <amount> , "pair": <amount> } } For example if a lp_setRangeOrder request changes the total size of an existing range order, the return would contain two of these, one for the decrease to zero/destruction of the previous order, and then one for the increase/creation of the order with the new size.

lp_update_limit_order

Parameters:

  • Sold Asset as a camel-case string, e.g. "Eth" or "Dot".
  • Brought Asset as a camel-case string, e.g. "Eth" or "Dot".
  • Limit order id as u64.
  • (Optional) Price tick as i32. If not specified the previous tick of this order id will be used.
  • Whether you intend to increase or decrease the size of the order, e.g. "Increase" or "Decrease".
  • The desired change in size of the order, e.g. the amount of sold Asset as u128.

Return:

  • A chronological list of all the updates that were done as part of the operation. Each item in the list is a JSON object: { "tick": [<tick>, <tick>], "amount_total": <amount>, "collected_fees": <amount>, "bought_amount": <amount>, "increase_or_decrease": <increase_or_decrease>, "amount_delta": <amount> } For example if a lp_updateLimitOrder request moves the limit order, the return would contain two of these, one for the decrease to zero/destruction of the previous order, and then one for the increase/creation of the order with the price/tick.

lp_set_limit_order

Parameters:

  • Sold Asset as a camel-case string, e.g. "Eth" or "Dot".
  • Brought Asset as a camel-case string, e.g. "Eth" or "Dot".
  • Limit order id as u64.
  • (Optional) Price tick as i32. If not specified the previous tick of this order id will be used.
  • The desired size of the order, e.g. the amount to sell as u128.

Return:

  • A chronological list of all the updates that were done as part of the operation. Each item in the list is a JSON object: { "tick": [<tick>, <tick>], "amount_total": <amount>, "collected_fees": <amount>, "bought_amount": <amount>, "increase_or_decrease": <increase_or_decrease>, "amount_delta": <amount> } For example if a lp_updateLimitOrder request moves the limit order, the return would contain two of these, one for the decrease to zero/destruction of the previous order, and then one for the increase/creation of the order with the price/tick.

lp_asset_balances

Parameters:

None

Return:

  • A list of all assets and their free balance in JSON format.

lp_get_open_swap_channels

Parameters:

None

Return:

  • All the open swap channels and their associated details in JSON format.

Working Example

./target/release/chainflip-lp-api \
 --state_chain.ws_endpoint=ws://localhost:9944 \
 --state_chain.signing_key_file /path/to/my/signing_key
 
🎙 Server is listening on 0.0.0.0:80.

Default values are ws://localhost:9944 and /etc/chainflip/keys/signing_key_file

Then in another terminal:

> curl -H "Content-Type: application/json" \
    -d '{"id":1, "jsonrpc":"2.0", "method": "lp_register_account", "params": [0]}' \
    http://localhost:80
 
{"jsonrpc":"2.0","result":null,"id":1}
 
# This method take a little while to respond because it submits and waits for finality. So make sure the request doesn't block.
# Parameters are: [ asset ].
> curl -H "Content-Type: application/json" \
    -d '{"id":1, "jsonrpc":"2.0", "method": "lp_liquidity_deposit", "params": ["Eth"]}' \
    http://localhost:80
 
# The result is the hex-encoded deposit address.
{"jsonrpc":"2.0","result":"0x350ec3dfd773978277868212d9f1319cbc93a8bf","id":1}

Limitations

  • It doesn't seem to work with wss, so make sure the address is specified with ws. It should be ok since we're not going to expose this externally.
How Liquidity Provisioning WorksLP RPCs
;