Manage Pool

This document provides a brief overview of single-sided pools and the related operation APIs.

Covered APIs

• Get submission limits: /api/pool/single/add_request_limit

• Query available balance: /api/pool/single/balance

• Get network fee: /api/pool/single/get_network_fee

• Submit add-liquidity request: /api/pool/single/add_liquidity

• Update add-liquidity request: /api/pool/single/update_liquidity

• Cancel matching: /api/pool/single/cancel

• Remove liquidity: /api/pool/single/remove

Prerequisites

1. Prepare address fields:

• payer_address: BTC address

• payer_asset_address: asset address (usually an Ordinals-compatible address, such as for ORDI/Runes assets)

1. Prepare the sign_info object:

• address

• public_key

• sign_info

• signature

• nonce (anti-replay, retrieve from /api/nonce)

1. Amount and precision conventions:

• Pass amount fields exactly as defined by each API (most are string).

• price_tick_lower and price_tick_upper define the price range boundaries.

• unit_tick defines the base unit for pricing.

1. Identifier convention:

• pool_id is passed as string in pool management APIs.

Recommended Call Flow

1. Call add_request_limit to get submission constraints (minimum/maximum amount, fee settings, etc.).

2. Call balance to confirm available balance.

3. Call add_liquidity to submit the matching request.

4. Use update_liquidity or cancel when needed.

5. Only before calling remove, call get_network_fee to estimate on-chain cost for liquidity removal.

Status Reference (Common Pool Statuses)

• MATCHING: currently matching

• MATCHED: matched

• MATCHING_ONCHAIN: matching on-chain in progress

• REMOVING_LIQUIDITY: liquidity removal in progress

• REMOVED: removed

Before update/cancel/remove operations, query the latest pool status and perform validation checks.

API Details

Get Add-Liquidity Submission Limits

post

Body

application/json

Responses

200Success

application/json

codeintegerRequired

msgstringRequired

post

/api/pool/single/add_request_limit

HTTPcURLJavaScriptPython

POST /api/pool/single/add_request_limit HTTP/1.1
Host: 127.0.0.1:8090
Content-Type: application/json
Accept: */*
Content-Length: 241

{
  "payer_address": {
    "address": "text",
    "public_key": "text"
  },
  "payer_asset_address": {
    "address": "text",
    "public_key": "text"
  },
  "tick_a": {
    "tick": "text",
    "token_id": "text",
    "coin_type": "text"
  },
  "tick_b": {
    "tick": "text",
    "token_id": "text",
    "coin_type": "text"
  }
}

200Success

{
  "code": 0,
  "msg": "success",
  "data": {
    "not_found_pool": false,
    "tick_a_maximum_value": "11",
    "tick_b_maximum_value": "17",
    "tick_a_minimum_value": "28",
    "tick_b_minimum_value": "41",
    "channel_usage_rates": 63,
    "real_channel_usage_rates": 0.63
  }
}

Query Available Balance

post

Body

application/json

addressstringRequired

Address to query

tickstringRequired

Token name

coin_typestringRequired

Token type

pool_idstringOptional

Pool

Responses

200Success

application/json

codeintegerRequired

msgstringRequired

post

/api/pool/single/balance

HTTPcURLJavaScriptPython

POST /api/pool/single/balance HTTP/1.1
Host: 127.0.0.1:8090
Content-Type: application/json
Accept: */*
Content-Length: 122

{
  "address": "tb1pf0tcpgxr30kqhh2gn3pgvr4qyachzm0xxydnfxth5cxlkjl37ugspxp7tm",
  "tick": "BTC",
  "coin_type": "",
  "pool_id": "50001"
}

200Success

{
  "code": 0,
  "msg": "success",
  "data": {
    "balance": "312312"
  }
}

Get Estimated Network Fee

post

Body

application/json

objectOptional

Responses

200Success

application/json

codeintegerRequired

msgstringRequired

post

/api/pool/single/get_network_fee

HTTPcURLJavaScriptPython

POST /api/pool/single/get_network_fee HTTP/1.1
Host: 127.0.0.1:8090
Content-Type: application/json
Accept: */*
Content-Length: 2

{}

200Success

{
  "code": 0,
  "msg": "success",
  "data": {
    "network_fee": "425"
  }
}

Submit Add-Liquidity Request

post

Body

application/json

min_amountstringRequired

Minimum amount

max_amountstringRequired

Maximum amount

min_fee_ratestringRequired

Minimum fee rate

price_tick_lowernumberRequired

Minimum price

price_tick_uppernumberRequired

Maximum price

unit_tickstringRequired

Tick unit

Responses

200Success

application/json

codeintegerRequired

msgstringRequired

post

/api/pool/single/add_liquidity

HTTPcURLJavaScriptPython

POST /api/pool/single/add_liquidity HTTP/1.1
Host: 127.0.0.1:8090
Content-Type: application/json
Accept: */*
Content-Length: 635

{
  "tick1": {
    "tick": "btc",
    "token_id": "",
    "coin_type": "btc"
  },
  "tick2": {
    "tick": "USDC•STARKNET•TEST",
    "token_id": "",
    "coin_type": "runes"
  },
  "token": {
    "tick": "btc",
    "token_id": "",
    "coin_type": "btc"
  },
  "min_amount": "10000",
  "max_amount": "20000",
  "min_fee_rate": "0.04",
  "sign_info": {
    "sign_info": "test",
    "address": "tb1pupt6rkpqv77mkxwks85vewwhyakc430rzmelgw5dhg3v83wnf40slm7mqs",
    "public_key": "l03f41902fd17e0c632fce4dd4b7c54a8f738635746bb5bfc9c503376e3db267be7",
    "signature": "AUB4xtqGpQIR0kcZgb5BGIuRckkZVsASt0fYztEMgHJqRDG2d2G0E+80C1nX7T3Tfn9Rl7KCp7ktpVA44+93YZB7",
    "nonce": "test-nonce"
  },
  "price_tick_lower": 80000,
  "price_tick_upper": 110000,
  "unit_tick": "BTC"
}

200Success

{
  "code": 0,
  "msg": "Success",
  "data": {
    "isSuccess": true
  }
}

Update Liquidity

post

Body

application/json

min_amountstringRequired

Minimum amount

max_amountstringRequired

Maximum amount

min_fee_ratestringRequired

Minimum fee rate

pool_idstringRequired

pool id

price_tick_lowernumberRequired

Minimum price

price_tick_uppernumberRequired

Maximum price

unit_tickstringRequired

Tick unit

Responses

200Success

application/json

codeintegerRequired

msgstringRequired

post

/api/pool/single/update_liquidity

HTTPcURLJavaScriptPython

POST /api/pool/single/update_liquidity HTTP/1.1
Host: 127.0.0.1:8090
Content-Type: application/json
Accept: */*
Content-Length: 574

{
  "min_amount": "1000",
  "max_amount": "2000",
  "min_fee_rate": "0.01",
  "pool_id": "50001",
  "sign_info": {
    "sign_info": "Account was activated by tb1p...p7tm at 2026-01-15 03:05:34",
    "address": "tb1pf0tcpgxr30kqhh2gn3pgvr4qyachzm0xxydnfxth5cxlkjl37ugspxp7tm",
    "public_key": "03786f146fa5031d05f5e81a2e983a6747f4444762e90b717b15633e9e043a16b9",
    "signature": "AUAPXqoJF4Sw/UukzHPuhqVcX2GPNobNjCaecc1RfaOx/xKjfSv8kONONG6mXcUCWoB/H1iGdKKPlFG94psn6n4y",
    "nonce": "test-nonce"
  },
  "token": {
    "tick": "BTC",
    "token_id": "",
    "coin_type": "btc"
  },
  "price_tick_lower": 80000,
  "price_tick_upper": 110000,
  "unit_tick": "BTC"
}

200Success

{
  "code": 0,
  "msg": "success",
  "data": {
    "isSuccess": true
  }
}

Cancel Matching

post

Body

application/json

pool_idstringRequired

pool id

Responses

200Success

application/json

codeintegerRequired

msgstringRequired

post

/api/pool/single/cancel

HTTPcURLJavaScriptPython

POST /api/pool/single/cancel HTTP/1.1
Host: 127.0.0.1:8090
Content-Type: application/json
Accept: */*
Content-Length: 334

{
  "pool_id": "50004",
  "sign_info": {
    "sign_info": "test",
    "address": "tb1pupt6rkpqv77mkxwks85vewwhyakc430rzmelgw5dhg3v83wnf40slm7mqs",
    "public_key": "l03f41902fd17e0c632fce4dd4b7c54a8f738635746bb5bfc9c503376e3db267be7",
    "signature": "AUB4xtqGpQIR0kcZgb5BGIuRckkZVsASt0fYztEMgHJqRDG2d2G0E+80C1nX7T3Tfn9Rl7KCp7ktpVA44+93YZB7",
    "nonce": "test-nonce"
  }
}

200Success

{
  "code": 0,
  "msg": "success",
  "data": {
    "isSuccess": true
  }
}

Remove Liquidity

post

Body

application/json

pool_idstringRequired

pool id

Responses

200Success

application/json

codeintegerRequired

msgstringRequired

post

/api/pool/single/remove

HTTPcURLJavaScriptPython

POST /api/pool/single/remove HTTP/1.1
Host: 127.0.0.1:8090
Content-Type: application/json
Accept: */*
Content-Length: 388

{
  "pool_id": "50001",
  "sign_info": {
    "address": "tb1pf0tcpgxr30kqhh2gn3pgvr4qyachzm0xxydnfxth5cxlkjl37ugspxp7tm",
    "public_key": "03786f146fa5031d05f5e81a2e983a6747f4444762e90b717b15633e9e043a16b9",
    "sign_info": "Account was activated by tb1p...p7tm at 2026-01-15 03:05:34",
    "signature": "AUAPXqoJF4Sw/UukzHPuhqVcX2GPNobNjCaecc1RfaOx/xKjfSv8kONONG6mXcUCWoB/H1iGdKKPlFG94psn6n4y",
    "nonce": "test-nonce"
  }
}

200Success

{
  "code": 0,
  "msg": "success",
  "data": {
    "isSuccess": true
  }
}

Error Handling and Retry Guidance

• Always check code and msg first, and only use data when the request succeeds.

• Show explicit error prompts for signature failures, nonce replay, and out-of-range parameters (minimum/maximum amount).

• For transient network issues and timeouts, use idempotent retries and avoid duplicate submissions for the same business intent.

• Before update/cancel/remove, re-fetch pool status and balance whenever possible.