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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.on.nexus/dotswap/developers/nexus-protocol/maker/single-sided-pool/manage-pool.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.