> For the complete documentation index, see [llms.txt](https://docs.on.nexus/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.on.nexus/dotswap/developers/maker/single-sided-pool/manage-pool.md).

# 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)

2. Prepare the `sign_info` object:

* `address`
* `public_key`
* `sign_info`
* `signature`
* `nonce` (anti-replay, retrieve from `/api/nonce`)

3. 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.

4. 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

## POST /api/pool/single/add\_request\_limit

> Get Add-Liquidity Submission Limits

```json
{"openapi":"3.0.1","info":{"title":"Default Module","version":"1.0.0"},"servers":[{"url":"http://127.0.0.1:8090","description":"Local"}],"security":[],"paths":{"/api/pool/single/add_request_limit":{"post":{"summary":"Get Add-Liquidity Submission Limits","deprecated":false,"description":"","tags":[],"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"payer_address":{"type":"object","properties":{"address":{"type":"string"},"public_key":{"type":"string"}},"required":["address","public_key"]},"payer_asset_address":{"type":"object","properties":{"address":{"type":"string"},"public_key":{"type":"string"}},"required":["address","public_key"]},"tick_a":{"$ref":"#/components/schemas/tick"},"tick_b":{"$ref":"#/components/schemas/tick"}},"required":["payer_address","payer_asset_address","tick_b","tick_a"]}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer"},"msg":{"type":"string"},"data":{"type":"object","properties":{"not_found_pool":{"type":"boolean","description":"DotSwap pool not found"},"tick_a_maximum_value":{"type":"string","description":"Maximum amount for tick_a"},"tick_b_maximum_value":{"type":"string","description":"Maximum amount for tick_b"},"tick_a_minimum_value":{"type":"string","description":"Minimum amount for tick_a"},"tick_b_minimum_value":{"type":"string","description":"Minimum amount for tick_b"},"channel_usage_rates":{"type":"integer","description":"Channel usage fee"},"real_channel_usage_rates":{"type":"number","description":"Effective channel usage fee percentage"}},"required":["tick_a_maximum_value","tick_b_maximum_value","tick_a_minimum_value","tick_b_minimum_value","channel_usage_rates","not_found_pool","real_channel_usage_rates"]}},"required":["code","msg","data"]}}},"headers":{}}}}}},"components":{"schemas":{"tick":{"type":"object","properties":{"tick":{"type":"string"},"token_id":{"type":"string"},"coin_type":{"type":"string"}},"required":["tick","coin_type"]}}}}
```

## POST /api/pool/single/balance

> Query Available Balance

```json
{"openapi":"3.0.1","info":{"title":"Default Module","version":"1.0.0"},"servers":[{"url":"http://127.0.0.1:8090","description":"Local"}],"security":[],"paths":{"/api/pool/single/balance":{"post":{"summary":"Query Available Balance","deprecated":false,"description":"","tags":[],"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"address":{"type":"string","description":"Address to query"},"tick":{"type":"string","description":"Token name"},"coin_type":{"type":"string","description":"Token type"},"pool_id":{"type":"string","description":"Pool"}},"required":["address","tick","coin_type"]}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer"},"msg":{"type":"string"},"data":{"type":"object","properties":{"balance":{"type":"string","description":"Balance excluding funds in matching"}},"required":["balance"]}},"required":["code","msg","data"]}}},"headers":{}}}}}}}
```

## POST /api/pool/single/get\_network\_fee

> Get Estimated Network Fee

```json
{"openapi":"3.0.1","info":{"title":"Default Module","version":"1.0.0"},"servers":[{"url":"http://127.0.0.1:8090","description":"Local"}],"security":[],"paths":{"/api/pool/single/get_network_fee":{"post":{"summary":"Get Estimated Network Fee","deprecated":false,"description":"","tags":[],"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer"},"msg":{"type":"string"},"data":{"type":"object","properties":{"network_fee":{"type":"string","description":"Network fee"}},"required":["network_fee"]}},"required":["code","msg","data"]}}}}}}}}}
```

## POST /api/pool/single/add\_liquidity

> Submit Add-Liquidity Request

```json
{"openapi":"3.0.1","info":{"title":"Default Module","version":"1.0.0"},"servers":[{"url":"http://127.0.0.1:8090","description":"Local"}],"security":[],"paths":{"/api/pool/single/add_liquidity":{"post":{"summary":"Submit Add-Liquidity Request","deprecated":false,"description":"","tags":[],"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"tick1":{"$ref":"#/components/schemas/tick","description":"Tick1 details"},"tick2":{"$ref":"#/components/schemas/tick","description":"Tick2 details"},"token":{"$ref":"#/components/schemas/tick","description":"Selected token"},"min_amount":{"type":"string","description":"Minimum amount"},"max_amount":{"type":"string","description":"Maximum amount"},"min_fee_rate":{"type":"string","description":"Minimum fee rate"},"sign_info":{"$ref":"#/components/schemas/sigInfo","description":"Signature data"},"price_tick_lower":{"type":"number","description":"Minimum price"},"price_tick_upper":{"type":"number","description":"Maximum price"},"unit_tick":{"type":"string","description":"Tick unit"}},"required":["tick1","max_amount","min_amount","token","tick2","sign_info","min_fee_rate","price_tick_lower","price_tick_upper","unit_tick"]}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer"},"msg":{"type":"string"},"data":{"type":"object","properties":{"isSuccess":{"type":"boolean"}},"required":["isSuccess"]}},"required":["code","msg","data"]}}},"headers":{}}}}}},"components":{"schemas":{"tick":{"type":"object","properties":{"tick":{"type":"string"},"token_id":{"type":"string"},"coin_type":{"type":"string"}},"required":["tick","coin_type"]},"sigInfo":{"type":"object","properties":{"sign_info":{"type":"string","title":"Signature info"},"address":{"type":"string","title":"Wallet address"},"public_key":{"type":"string","title":"Wallet public key"},"signature":{"type":"string","title":"Signature"},"nonce":{"type":"string","title":"Anti-replay nonce"}},"required":["sign_info","address","public_key","signature","nonce"]}}}}
```

## POST /api/pool/single/update\_liquidity

> Update Liquidity

```json
{"openapi":"3.0.1","info":{"title":"Default Module","version":"1.0.0"},"servers":[{"url":"http://127.0.0.1:8090","description":"Local"}],"security":[],"paths":{"/api/pool/single/update_liquidity":{"post":{"summary":"Update Liquidity","deprecated":false,"description":"","tags":[],"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"min_amount":{"type":"string","description":"Minimum amount"},"max_amount":{"type":"string","description":"Maximum amount"},"min_fee_rate":{"type":"string","description":"Minimum fee rate"},"pool_id":{"type":"string","description":"pool id"},"sign_info":{"$ref":"#/components/schemas/sigInfo","description":"Signature data"},"token":{"$ref":"#/components/schemas/tick","description":"Token to update"},"price_tick_lower":{"type":"number","description":"Minimum price"},"price_tick_upper":{"type":"number","description":"Maximum price"},"unit_tick":{"type":"string","description":"Tick unit"}},"required":["max_amount","min_amount","sign_info","min_fee_rate","pool_id","token","price_tick_upper","price_tick_lower","unit_tick"]}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer"},"msg":{"type":"string"},"data":{"type":"object","properties":{"isSuccess":{"type":"boolean"}},"required":["isSuccess"]}},"required":["code","msg","data"]}}},"headers":{}}}}}},"components":{"schemas":{"sigInfo":{"type":"object","properties":{"sign_info":{"type":"string","title":"Signature info"},"address":{"type":"string","title":"Wallet address"},"public_key":{"type":"string","title":"Wallet public key"},"signature":{"type":"string","title":"Signature"},"nonce":{"type":"string","title":"Anti-replay nonce"}},"required":["sign_info","address","public_key","signature","nonce"]},"tick":{"type":"object","properties":{"tick":{"type":"string"},"token_id":{"type":"string"},"coin_type":{"type":"string"}},"required":["tick","coin_type"]}}}}
```

## POST /api/pool/single/cancel

> Cancel Matching

```json
{"openapi":"3.0.1","info":{"title":"Default Module","version":"1.0.0"},"servers":[{"url":"http://127.0.0.1:8090","description":"Local"}],"security":[],"paths":{"/api/pool/single/cancel":{"post":{"summary":"Cancel Matching","deprecated":false,"description":"","tags":[],"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"pool_id":{"type":"string","description":"pool id"},"sign_info":{"$ref":"#/components/schemas/sigInfo","description":"Signature data"}},"required":["pool_id","sign_info"]}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer"},"msg":{"type":"string"},"data":{"type":"object","properties":{"isSuccess":{"type":"boolean"}},"required":["isSuccess"]}},"required":["code","msg","data"]}}},"headers":{}}}}}},"components":{"schemas":{"sigInfo":{"type":"object","properties":{"sign_info":{"type":"string","title":"Signature info"},"address":{"type":"string","title":"Wallet address"},"public_key":{"type":"string","title":"Wallet public key"},"signature":{"type":"string","title":"Signature"},"nonce":{"type":"string","title":"Anti-replay nonce"}},"required":["sign_info","address","public_key","signature","nonce"]}}}}
```

## POST /api/pool/single/remove

> Remove Liquidity

```json
{"openapi":"3.0.1","info":{"title":"Default Module","version":"1.0.0"},"servers":[{"url":"http://127.0.0.1:8090","description":"Local"}],"security":[],"paths":{"/api/pool/single/remove":{"post":{"summary":"Remove Liquidity","deprecated":false,"description":"","tags":[],"parameters":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"pool_id":{"type":"string","description":"pool id"},"sign_info":{"$ref":"#/components/schemas/sigInfo","description":"Signature data"}},"required":["pool_id","sign_info"]}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer"},"msg":{"type":"string"},"data":{"type":"object","properties":{"isSuccess":{"type":"boolean"}},"required":["isSuccess"]}},"required":["code","msg","data"]}}},"headers":{}}}}}},"components":{"schemas":{"sigInfo":{"type":"object","properties":{"sign_info":{"type":"string","title":"Signature info"},"address":{"type":"string","title":"Wallet address"},"public_key":{"type":"string","title":"Wallet public key"},"signature":{"type":"string","title":"Signature"},"nonce":{"type":"string","title":"Anti-replay nonce"}},"required":["sign_info","address","public_key","signature","nonce"]}}}}
```

## 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.