HODLMM API Documentation (v2)

Engine v2 endpoints and sample code for HODLMM retail integrators and market makers.

Getting started

Base URL: https://bff.bitflowapis.finance/api

The API is public. You can call it without a key at up to 100 requests per second per IP. For a higher limit, ask in Intercom and we will issue an X-API-Key for your integration.

This API does not include a Stacks node or the Stacks API. For Stacks RPC, use Hiro Platform and the Hiro API docs.

Check that the engine is caught up with the chain:

curl -sS https://bff.bitflowapis.finance/api/quotes/v2/status \
  | jq '{ready, state_height, chain_tip, tip_lag, pool_count}'

Shared helpers

The samples on this page use these helpers.

const BFF_API_URL = 'https://bff.bitflowapis.finance/api';
const BFF_API_KEY = null; // Optional. Set to your X-API-Key for a raised rate limit.

const bff = async (path, { method = 'GET', body } = {}) => {
  const headers = { 'Content-Type': 'application/json' };
  if (BFF_API_KEY) headers['X-API-Key'] = BFF_API_KEY;

  const response = await fetch(`${BFF_API_URL}${path}`, {
    method,
    headers,
    body: body ? JSON.stringify(body) : undefined
  });

  if (!response.ok) throw new Error(`${method} ${path} returned ${response.status}`);
  return response.json();
};

// Quote v2 and App v2 return signed bin IDs (-500 to 500).
// Contract calls take unsigned bin IDs (0 to 1000).
const to_unsigned_bin_id = (signed_bin_id) => signed_bin_id + 500;

// Every bin in the pool, with price, reserves, and total shares (`liquidity`).
const get_pool_bins = async (pool_id) => {
  const data = await bff(`/quotes/v2/bins/${pool_id}`);
  if (!data.success) throw new Error(data.error ?? `No bins for ${pool_id}`);
  return data;
};

// Position at asOfHeight: overallUserShares plus per-bin userShares, binShares, reserveX, reserveY.
// Size an add, withdraw, or move only when clean, complete, and tipLag are good. See "Your position".
const get_user_current_bins = (user_address, pool_id) =>
  bff(`/app/v2/users/${user_address}/positions/${pool_id}/current-bins`);

Core concepts

Pool IDs

Each pool has a contract principal, such as SM1FKXGNZJWSTWDWXQZJNF7B5TV5ZB235JTCXYXKD.dlmm-pool-sbtc-usdcx-v-1-bps-10. GET /quotes/v2/pools returns it as pool_id. Prefer the contract principal in every call. Quote v2 also accepts short aliases such as dlmm_1. GET /app/v2/users/{user}/liquidity/{pool_id} resolves aliases and case-insensitive pool ids. Other App v2 routes (for example /app/v2/pools/{pool_id} and /positions/{pool_id}/bins) may still answer not found for an alias — prefer the principal.

For an unknown pool, GET /quotes/v2/bins/{pool_id} returns HTTP 200 with success: false and an error message. Check success as well as the status code.

Bin IDs

Quote v2 and App v2 return signed bin IDs, from -500 to 500. That includes active_bin_id and the bin_id of each bin.

Two places take unsigned IDs, from 0 to 1000:

• GET /quotes/v2/bins/{pool_id}/{bin_id} (single-bin lookup)

• Contract calls

Convert with unsigned = signed + 500. The prepare functions on this page take signed IDs and return unsigned ones, so you can pass their output to the executing code without changes.

Data freshness

Quote v2 serves pool state from memory at the latest block it has applied. GET /quotes/v2/status reports how far that state trails the chain:

• tip_lag: 0 means the engine has applied the chain tip. Require tip_lag == 0, or a limit you set, before you size or sign a transaction.

• tip_lag: null means the engine does not know the chain tip. Treat it as behind.

App v2 builds pool stats, price history, and position summaries from indexed chain events, so those reads can trail the tip. GET /app/v2/ready reports ready and logTailLag. Position sizing uses current-bins, which reports its own tipLag, clean, and complete.

Your position

Size an add, withdraw, or move from GET /app/v2/users/{address}/positions/{pool_id}/current-bins only when clean is true, complete is true, and tipLag is 0.

When those three hold, the response is the position at asOfHeight:

• The bin set and overallUserShares are the user's position.

• Per bin, userShares is the user's balance, binShares is the bin's total shares, and reserveX / reserveY are that bin's reserves.

• Share amounts are decimal strings.

An empty position is HTTP 200 with bins: []. Any other status means the position is unknown. Do not treat it as an empty book.

GET /app/v2/users/{address}/positions/{pool_id}/bins is the indexed view for charts and display. Do not size a transaction from it.

Current Balance (/liquidity)

The app Current Balance card uses GET /app/v2/users/{address}/liquidity/{pool_id}. For DLMM pools it re-values on read from held-bin reserves × the user's shares ÷ absolute bin share supply (including burn-address / unindexed supply printed on BinUpdate). That matches Clarity dlmm_position_amounts and current-bins. Do not treat ownership as user_shares / sum(indexed holders).

Wing / out-of-range positions keep per-bin X/Y splits. Pool-wide pro-rata applies only when the user has no held-bin rows. Per-bin USD on …/positions/…/bins uses the same absolute bin supply. Still size transactions from current-bins only. See Current Balance and /liquidity valuation.

Absolute bin_shares require derived checkpoint v6 on the serving host. Until that cutover finishes on a given environment, /liquidity on that host can still disagree with chain.

Strict vs Simple mode

Strict mode uses exact bin IDs. Use it for precise liquidity operations. You can broadcast these transactions in Deny mode. If on-chain state changes in a way that affects your bins or amounts, the transaction reverts. For example, an add to the active bin reverts if the active bin moves by one before execution.

Simple mode uses offsets from the active bin instead of absolute bin IDs. Broadcast these transactions in Allow mode. The contract applies the operation relative to the active bin at execution time, so the transaction can still confirm after the active bin moves.

Adding Liquidity

1

Fetch pool bins and the user's current bins

const pool_bins = await get_pool_bins(pool_id);
const active_bin_id = pool_bins.active_bin_id; // signed
const user_bins = await get_user_current_bins(user_address, pool_id);

Require clean, complete, and tipLag == 0 before you size. The bin set and overallUserShares are the position at asOfHeight.

2

Prepare bins for add liquidity

Choose the bins and the amount of each token to add. Below the active bin you can add only token Y. Above it you can add only token X.

liquidity on a Quote v2 bin holds the bin's total shares as a string, and it can be null. The samples stop on null. Treating it as 0 sends the executing code down the first-deposit path and produces a wrong min_dlp.

Strict mode

// Signed bin IDs
const bins_to_add = [
  { bin_id: active_bin_id, x_amount: 10000000000, y_amount: 1750000000 },
  { bin_id: active_bin_id - 1, x_amount: 0, y_amount: 1750000000 }
];

const prepare_bins_for_add = (pool_bins, user_bins, active_bin_id, bins_to_add) => {
  const user_bins_map = new Map((user_bins?.bins ?? []).map(bin => [bin.binIdSigned, bin]));

  return bins_to_add.map(add_bin => {
    const pool_bin = pool_bins.bins.find(b => b.bin_id === add_bin.bin_id);

    if (!pool_bin) throw new Error(`Bin ${add_bin.bin_id} not found in pool`);
    if (pool_bin.liquidity === null) throw new Error(`Bin ${add_bin.bin_id} has no share data yet`);

    if (add_bin.bin_id < active_bin_id && add_bin.x_amount > 0) {
      throw new Error('Only y_token can be added to bins below the active bin');
    }

    if (add_bin.bin_id > active_bin_id && add_bin.y_amount > 0) {
      throw new Error('Only x_token can be added to bins above the active bin');
    }

    if (add_bin.bin_id === active_bin_id && add_bin.x_amount === 0 && add_bin.y_amount === 0) {
      throw new Error('Active bin requires at least one token amount to be greater than 0');
    }

    return {
      is_active_bin: add_bin.bin_id === active_bin_id,
      bin_id: to_unsigned_bin_id(add_bin.bin_id),
      x_amount: add_bin.x_amount,
      y_amount: add_bin.y_amount,
      bin_price: Number(pool_bin.price),
      reserve_x: Number(pool_bin.reserve_x),
      reserve_y: Number(pool_bin.reserve_y),
      bin_shares: Number(pool_bin.liquidity),
      user_liquidity: Number(user_bins_map.get(add_bin.bin_id)?.userShares ?? 0),
      has_ever_added_to_bin: user_bins_map.has(add_bin.bin_id)
    };
  });
};

Simple mode

const bins_to_add_relative = [
  { active_bin_offset: 0, x_amount: 10000000000, y_amount: 1750000000 },
  { active_bin_offset: -1, x_amount: 0, y_amount: 1750000000 }
];

const prepare_bins_for_relative_add = (pool_bins, user_bins, active_bin_id, bins_to_add) => {
  const user_bins_map = new Map((user_bins?.bins ?? []).map(bin => [bin.binIdSigned, bin]));

  return bins_to_add.map(add_bin => {
    const bin_id = active_bin_id + add_bin.active_bin_offset; // signed
    const pool_bin = pool_bins.bins.find(b => b.bin_id === bin_id);

    if (!pool_bin) throw new Error(`Bin ${bin_id} not found in pool`);
    if (pool_bin.liquidity === null) throw new Error(`Bin ${bin_id} has no share data yet`);

    if (bin_id < active_bin_id && add_bin.x_amount > 0) {
      throw new Error('Only y_token can be added to bins below the active bin');
    }

    if (bin_id > active_bin_id && add_bin.y_amount > 0) {
      throw new Error('Only x_token can be added to bins above the active bin');
    }

    if (bin_id === active_bin_id && add_bin.x_amount === 0 && add_bin.y_amount === 0) {
      throw new Error('Active bin requires at least one token amount to be greater than 0');
    }

    return {
      is_active_bin: bin_id === active_bin_id,
      active_bin_offset: add_bin.active_bin_offset,
      bin_id: to_unsigned_bin_id(bin_id),
      x_amount: add_bin.x_amount,
      y_amount: add_bin.y_amount,
      bin_price: Number(pool_bin.price),
      reserve_x: Number(pool_bin.reserve_x),
      reserve_y: Number(pool_bin.reserve_y),
      bin_shares: Number(pool_bin.liquidity),
      user_liquidity: Number(user_bins_map.get(bin_id)?.userShares ?? 0),
      has_ever_added_to_bin: user_bins_map.has(bin_id)
    };
  });
};

3

Execute add liquidity

Call the liquidity router contract with the prepared bins. Use the code under Executing Add Liquidity on the v1 page, with two changes:

• In get_token_asset_name, fetch from /quotes/v2/tokens.

• In Simple mode, pass expected_bin_id as an unsigned ID: to_unsigned_bin_id(active_bin_id).

---

Withdrawing Liquidity

1

Fetch the user's current bins

const user_bins = await get_user_current_bins(user_address, pool_id);
const active_bin_id = user_bins.activeBinIdSigned;

Require clean, complete, and tipLag == 0 before you size. The bin set and overallUserShares are the position at asOfHeight. Per bin, use userShares, binShares, reserveX, and reserveY.

2

Prepare bins for withdraw liquidity

Choose the percentage of each bin to withdraw.

Strict mode

const prepare_bins_for_withdraw = (user_bins, withdrawal_percentage) => {
  return user_bins.bins
    .filter(bin => Number(bin.userShares) > 0)
    .map(bin => ({
      bin_id: bin.binIdUnsigned,
      user_liquidity: Number(bin.userShares),
      liquidity: Number(bin.binShares),
      reserve_x: Number(bin.reserveX),
      reserve_y: Number(bin.reserveY),
      withdrawal_percentage,
      has_ever_added_to_bin: true
    }));
};

Simple mode

const prepare_bins_for_relative_withdraw = (user_bins, active_bin_id, withdrawal_percentage) => {
  return user_bins.bins
    .filter(bin => Number(bin.userShares) > 0)
    .map(bin => ({
      active_bin_offset: bin.binIdSigned - active_bin_id,
      bin_id: bin.binIdUnsigned,
      user_liquidity: Number(bin.userShares),
      liquidity: Number(bin.binShares),
      reserve_x: Number(bin.reserveX),
      reserve_y: Number(bin.reserveY),
      withdrawal_percentage,
      has_ever_added_to_bin: true
    }));
};

3

Execute withdraw liquidity

Call the liquidity router contract with the prepared bins. Use the code under Executing Withdraw Liquidity on the v1 page, and fetch get_token_asset_name from /quotes/v2/tokens.

---

Moving Liquidity

1

Fetch pool bins and the user's current bins

const pool_bins = await get_pool_bins(pool_id);
const active_bin_id = pool_bins.active_bin_id; // signed
const user_bins = await get_user_current_bins(user_address, pool_id);

Require clean, complete, and tipLag == 0 before you size. The bin set and overallUserShares are the position at asOfHeight.

2

Prepare bins for move liquidity

Choose the bin to move from, the bin to move to, and the number of shares to move.

Strict mode

// Signed bin IDs. `amount` is a share count.
const bins_to_move = [
  { from_bin_id: -20, to_bin_id: -2, amount: 12848399 }
];

const prepare_bins_for_move = (pool_bins, user_bins, active_bin_id, bins_to_move) => {
  const user_bins_map = new Map((user_bins?.bins ?? []).map(bin => [bin.binIdSigned, bin]));

  return bins_to_move.map(move => {
    const { from_bin_id, to_bin_id, amount } = move;

    if (from_bin_id === to_bin_id) throw new Error('Cannot move liquidity to the same bin');

    const from_bin = user_bins_map.get(from_bin_id);
    if (!from_bin) throw new Error('Unable to find from_bin in user positions');

    const user_shares = Number(from_bin.userShares);
    if (user_shares === 0) throw new Error('User has no liquidity in from_bin');
    if (amount > user_shares) throw new Error('Amount exceeds user liquidity in from_bin');

    const to_bin = pool_bins.bins.find(b => b.bin_id === to_bin_id);
    if (!to_bin) throw new Error('Unable to find to_bin in pool bins');
    if (to_bin.liquidity === null) throw new Error(`Bin ${to_bin_id} has no share data yet`);

    const x_amount = Math.floor((amount * Number(from_bin.reserveX)) / Number(from_bin.binShares));
    const y_amount = Math.floor((amount * Number(from_bin.reserveY)) / Number(from_bin.binShares));

    if (to_bin_id < active_bin_id && x_amount > 0) {
      throw new Error('Only y_token can be added to bins below the active bin');
    }

    if (to_bin_id > active_bin_id && y_amount > 0) {
      throw new Error('Only x_token can be added to bins above the active bin');
    }

    if (to_bin_id === active_bin_id && x_amount === 0 && y_amount === 0) {
      throw new Error('Active bin requires at least one token amount to be greater than 0');
    }

    return {
      from_bin_id: to_unsigned_bin_id(from_bin_id),
      to_bin_id: to_unsigned_bin_id(to_bin_id),
      amount,
      x_amount,
      y_amount,
      bin_price: Number(to_bin.price),
      reserve_x: Number(to_bin.reserve_x),
      reserve_y: Number(to_bin.reserve_y),
      bin_shares: Number(to_bin.liquidity),
      is_active_bin: to_bin_id === active_bin_id,
      has_ever_added_to_from_bin: true,
      has_ever_added_to_to_bin: user_bins_map.has(to_bin_id)
    };
  });
};

Simple mode

// Signed bin IDs. `amount` is a share count.
const bins_to_move_relative = [
  { from_bin_id: -20, active_bin_offset: -2, amount: 12848399 }
];

const prepare_bins_for_relative_move = (pool_bins, user_bins, active_bin_id, bins_to_move) => {
  const user_bins_map = new Map((user_bins?.bins ?? []).map(bin => [bin.binIdSigned, bin]));

  return bins_to_move.map(move => {
    const { from_bin_id, active_bin_offset, amount } = move;
    const to_bin_id = active_bin_id + active_bin_offset; // signed

    if (from_bin_id === to_bin_id) throw new Error('Cannot move liquidity to the same bin');

    const from_bin = user_bins_map.get(from_bin_id);
    if (!from_bin) throw new Error('Unable to find from_bin in user positions');

    const user_shares = Number(from_bin.userShares);
    if (user_shares === 0) throw new Error('User has no liquidity in from_bin');
    if (amount > user_shares) throw new Error('Amount exceeds user liquidity in from_bin');

    const to_bin = pool_bins.bins.find(b => b.bin_id === to_bin_id);
    if (!to_bin) throw new Error('Unable to find to_bin in pool bins');
    if (to_bin.liquidity === null) throw new Error(`Bin ${to_bin_id} has no share data yet`);

    const x_amount = Math.floor((amount * Number(from_bin.reserveX)) / Number(from_bin.binShares));
    const y_amount = Math.floor((amount * Number(from_bin.reserveY)) / Number(from_bin.binShares));

    if (to_bin_id < active_bin_id && x_amount > 0) {
      throw new Error('Only y_token can be added to bins below the active bin');
    }

    if (to_bin_id > active_bin_id && y_amount > 0) {
      throw new Error('Only x_token can be added to bins above the active bin');
    }

    if (to_bin_id === active_bin_id && x_amount === 0 && y_amount === 0) {
      throw new Error('Active bin requires at least one token amount to be greater than 0');
    }

    return {
      from_bin_id: to_unsigned_bin_id(from_bin_id),
      active_bin_offset,
      to_bin_id: to_unsigned_bin_id(to_bin_id),
      amount,
      x_amount,
      y_amount,
      bin_price: Number(to_bin.price),
      reserve_x: Number(to_bin.reserve_x),
      reserve_y: Number(to_bin.reserve_y),
      bin_shares: Number(to_bin.liquidity),
      is_active_bin: to_bin_id === active_bin_id,
      has_ever_added_to_from_bin: true,
      has_ever_added_to_to_bin: user_bins_map.has(to_bin_id)
    };
  });
};

3

Execute move liquidity

Call the liquidity router contract with the prepared bins. Use the code under Executing Move Liquidity on the v1 page, and fetch get_token_asset_name from /quotes/v2/tokens.

---

Swapping Tokens

1

Get a quote

• POST /quotes/v2/quote returns the best route.

• POST /quotes/v2/quote/multi returns every route, with best_route_index.

Both endpoints take the same request body. Send amount_in as a string in the input token's base units.

const get_quote = (input_token, output_token, amount_in, amm_strategy = 'best', slippage_tolerance = 1) =>
  bff('/quotes/v2/quote/multi', {
    method: 'POST',
    body: {
      input_token, // Input token contract principal
      output_token, // Output token contract principal
      amount_in: String(amount_in), // Base units, as a string
      amm_strategy, // Optional, default 'best'
      slippage_tolerance // Optional, 1 = 1%
    }
  });

Some routes pass through venues the swap router can't execute yet. Each route has an executable flag and a reject_reason. The best route by output can be non-executable, so pick a route with executable: true. POST /quotes/v2/quote also returns the best executable route as best_executable.

const quote = await get_quote(input_token, output_token, amount_in);
const route = quote.routes.find(r => r.executable);
if (!route) throw new Error('No executable route');

2

Get swap parameters

POST /quotes/v2/swap turns a route into contract-call parameters.

const get_swap_params = (amount_in, input_token, output_token, route) =>
  bff('/quotes/v2/swap', {
    method: 'POST',
    body: {
      execution_path: route.execution_path,
      amount_in: String(amount_in),
      amount_out: route.amount_out,
      input_token,
      output_token,
      input_token_decimals: route.input_token_decimals,
      output_token_decimals: route.output_token_decimals,
      slippage_tolerance: route.slippage_tolerance,
      swap_parameters_type: 'simple' // Optional: 'simple' (default) or 'full'
    }
  });

3

Execute a swap

Call the swap router contract with the swap parameters. Use the code under Executing a Swap on the v1 page without changes.

---

Endpoint Reference

All paths are relative to https://bff.bitflowapis.finance/api.

Method	Path	Returns
GET	/quotes/v2/status	Engine height, chain tip, and tip_lag
GET	/quotes/v2/ready	200 when Quote v2 is serving
GET	/quotes/v2/tokens	Supported tokens
GET	/quotes/v2/pools	All pools, with contract pool_id
GET	/quotes/v2/pools/{pool_id}	One pool: active bin, bin step, fees, status
GET	/quotes/v2/pairs?input_token={token}	Tokens you can swap input_token into
GET	/quotes/v2/bins/{pool_id}	All bins (signed IDs) with price, reserves, liquidity
GET	/quotes/v2/bins/{pool_id}/active	Active bin ID (signed)
GET	/quotes/v2/bins/{pool_id}/{bin_id}	One bin, looked up by unsigned ID
POST	/quotes/v2/quote	Best route, plus best_executable
POST	/quotes/v2/quote/multi	All routes
POST	/quotes/v2/swap	Contract-call parameters for a route
GET	/app/v2/ready	App v2 readiness and logTailLag
GET	/app/v2/pools/{pool_id}	Pool details and analytics
GET	/app/v2/pools/{pool_id}/bin-price-history	Active bin and price history
GET	/app/v2/users/{user}/liquidity/{pool_id}	Current Balance: token amounts/value from absolute bin supply (aliases OK)
GET	/app/v2/users/{user}/positions/{pool_id}/current-bins	Position at asOfHeight. Size only when clean, complete, and tipLag are 0
GET	/app/v2/users/{user}/positions/{pool_id}/bins	Position bins from indexed events, for charts and display

const pool = await bff(`/quotes/v2/pools/${pool_id}`);

Market Makers

• Poll GET /quotes/v2/status and quote only while tip_lag is 0, or within your own limit. /ready tells you the service is up. It does not tell you the engine has applied the chain tip.

• Read the ladder from GET /quotes/v2/bins/{pool_id} and pool state (active bin, bin step, fees) from GET /quotes/v2/pools/{pool_id}. Size off price, reserves, and your own inventory.

• Read inventory from GET /app/v2/users/{address}/positions/{pool_id}/current-bins. Size only when clean and complete are true and tipLag is 0. That response's bin set and overallUserShares are the position at asOfHeight. An empty position returns 200 with bins: []. Treat any other status as unknown inventory, never as an empty book.

• .../positions/{pool_id}/bins comes from indexed events. Use it for charts, not for inventory.

BASE=https://bff.bitflowapis.finance/api
POOL=SM1FKXGNZJWSTWDWXQZJNF7B5TV5ZB235JTCXYXKD.dlmm-pool-sbtc-usdcx-v-1-bps-10

curl -s "$BASE/quotes/v2/pools/$POOL" | jq '{pool_id, active_bin, bin_step, active, quotable}'

curl -s "$BASE/quotes/v2/bins/$POOL" | jq '{active_bin_id, bin_count: (.bins | length)}'

curl -s "$BASE/app/v2/users/<your-address>/positions/$POOL/current-bins" \
  | jq '{clean, complete, tipLag, activeBinIdSigned, bins: (.bins | length)}'

Migrating from v1

The v1 page documents the legacy endpoints.

Area	v1	v2
Paths	/quotes/v1, /app/v1	/quotes/v2, /app/v2
Pool IDs	Short aliases such as dlmm_3	Contract principal. /liquidity resolves aliases; prefer principal elsewhere.
Bin IDs	Unsigned, 0 to 1000	Signed, -500 to 500. Single-bin lookup still takes unsigned.
Freshness	X-Allow-Fallback, DB to chain fallback	No fallback. Check tip_lag on /quotes/v2/status.
Position bins	/app/v1/.../bins	/app/v2/.../current-bins for transactions
Contract calls	v1 executing code	Same code, with unsigned bin IDs and /quotes/v2/tokens

Move Quote and App calls to v2 together. A client that mixes v1 pool IDs with v2 bins can get HTTP 200 with empty bins and Pool not found.