Ctrlk
Swap On Nexus
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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
Responses
200Success
application/json
codeintegerRequired
msgstringRequired
post/api/pool/single/add_request_limit
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
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
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
objectOptional
Responses
200Success
application/json
codeintegerRequired
msgstringRequired
post/api/pool/single/get_network_fee
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
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
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
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
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
pool_idstringRequired

pool id

Responses
200Success
application/json
codeintegerRequired
msgstringRequired
post/api/pool/single/cancel
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
pool_idstringRequired

pool id

Responses
200Success
application/json
codeintegerRequired
msgstringRequired
post/api/pool/single/remove
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.

PreviousSingle Sided PoolNextRecords

Last updated