> For the complete documentation index, see [llms.txt](https://docs.bitflow.finance/bitflow-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bitflow.finance/bitflow-documentation/developers/hodlmm-api-documentation-v2.md).

# 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](https://platform.hiro.so/) and the [Hiro API docs](https://docs.hiro.so/).

Check that the engine is caught up with the chain:

```bash
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.

```javascript
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.

{% hint style="info" %}
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.
{% endhint %}

**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

{% stepper %}
{% step %}
**Fetch pool bins and the user's current bins**

```javascript
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`.
{% endstep %}

{% step %}
**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.

{% hint style="warning" %}
`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`.
{% endhint %}

{% tabs %}
{% tab title="Strict mode" %}

```javascript
// 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)
    };
  });
};
```

{% endtab %}

{% tab title="Simple mode" %}

```javascript
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)
    };
  });
};
```

{% endtab %}
{% endtabs %}
{% endstep %}

{% step %}
**Execute add liquidity**

Call the liquidity router contract with the prepared bins. Use the code under [Executing Add Liquidity](https://docs.bitflow.finance/bitflow-documentation/developers/hodlmm-api-documentation#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)`.
  {% endstep %}
  {% endstepper %}

***

#### Withdrawing Liquidity

{% stepper %}
{% step %}
**Fetch the user's current bins**

```javascript
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`.
{% endstep %}

{% step %}
**Prepare bins for withdraw liquidity**

Choose the percentage of each bin to withdraw.

{% tabs %}
{% tab title="Strict mode" %}

```javascript
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
    }));
};
```

{% endtab %}

{% tab title="Simple mode" %}

```javascript
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
    }));
};
```

{% endtab %}
{% endtabs %}
{% endstep %}

{% step %}
**Execute withdraw liquidity**

Call the liquidity router contract with the prepared bins. Use the code under [Executing Withdraw Liquidity](https://docs.bitflow.finance/bitflow-documentation/developers/hodlmm-api-documentation#executing-withdraw-liquidity) on the v1 page, and fetch `get_token_asset_name` from `/quotes/v2/tokens`.
{% endstep %}
{% endstepper %}

***

#### Moving Liquidity

{% stepper %}
{% step %}
**Fetch pool bins and the user's current bins**

```javascript
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`.
{% endstep %}

{% step %}
**Prepare bins for move liquidity**

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

{% tabs %}
{% tab title="Strict mode" %}

```javascript
// 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)
    };
  });
};
```

{% endtab %}

{% tab title="Simple mode" %}

```javascript
// 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)
    };
  });
};
```

{% endtab %}
{% endtabs %}
{% endstep %}

{% step %}
**Execute move liquidity**

Call the liquidity router contract with the prepared bins. Use the code under [Executing Move Liquidity](https://docs.bitflow.finance/bitflow-documentation/developers/hodlmm-api-documentation#executing-move-liquidity) on the v1 page, and fetch `get_token_asset_name` from `/quotes/v2/tokens`.
{% endstep %}
{% endstepper %}

***

#### Swapping Tokens

{% stepper %}
{% step %}
**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.

```javascript
const get_quote = (input_token, output_token, amount_in, amm_strategy = 'best', slippage_tolerance = 1, agg_fee_bps = null, provider = null) =>
  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%
      agg_fee_bps, // Optional integrator fee in bps (0–3000); see "Integrator fees and attribution"
      provider // Optional: your Stacks principal, echoed in protocol_fee
    }
  });
```

{% hint style="warning" %}
Some routes pass through venues the **legacy** `/quotes/v2/swap` router can't execute yet. Each route has an `executable` flag and a `reject_reason`. For `/quotes/v2/swap`, pick `executable: true` (or use `best_executable` from `POST /quotes/v2/quote`). For `/quotes/v2/agg/swap`, prefer `agg_buildable: true` and do **not** gate on `executable` — external venues are often non-executable on the legacy path but still buildable on the aggregator.
{% endhint %}

```javascript
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');
```

{% endstep %}

{% step %}
**Get swap parameters**

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

```javascript
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'
      provider: 'SP3F7GQ48JY59521DZEE6KABHBF4Q33PEYJ823ZXQ' // Optional referral / attribution principal
    }
  });
```

{% endstep %}

{% step %}
**Get aggregator swap parameters (multi-venue)**

`POST /quotes/v2/agg/swap` builds contract-call args for Bitflow `agg-*` routers. Collapse consecutive identical `pool_id`s from `execution_path` into `hops` (max 4). Prefer routes with `agg_buildable: true`. Do **not** gate on `executable` — that flag is for legacy `/quotes/v2/swap` only.

```javascript
// hops: [{ pool_id, token_in, token_out }, ...] from route_path + collapsed execution_path
const get_agg_swap_params = (amount_in, route, hops, recipient, provider = null, agg_fee_bps = null) =>
  bff('/quotes/v2/agg/swap', {
    method: 'POST',
    body: {
      hops,
      amount_in: String(amount_in),
      amount_out: route.amount_out,
      slippage_tolerance: route.slippage_tolerance,
      recipient, // principal that receives the output
      snapshot_height: route.snapshot_height, // from the quote
      sender: recipient, // optional; used for post-conditions
      provider, // optional: your Stacks principal, or omit / null
      agg_fee_bps // optional: the same value you sent to the quote, or omit / null
    }
  });
```

The response includes `contract_address`, `contract_name`, `function_name`, `function_args`, `function_args_hex`, deny-mode `post_conditions`, `min_out`, and `protocol_fee`. When `provider` is set, the last Clarity arg is `(some <provider>)`; when omitted, it is `none`.
{% endstep %}

{% step %}
**Execute a swap**

Call the swap router contract with the swap parameters. Use the code under [Executing a Swap](https://docs.bitflow.finance/bitflow-documentation/developers/hodlmm-api-documentation#executing-a-swap) on the v1 page without changes.
{% endstep %}
{% endstepper %}

***

#### Integrator fees and attribution (`agg_fee_bps`, `provider`)

Integrators can charge their own fee on aggregator swaps and have the swap attributed to them. Two optional request fields control this:

| Field         | Type                                    | What it does                                                                                                |
| ------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| `agg_fee_bps` | Integer (or integer string), `0`–`3000` | Fee on the swap's output, in basis points (`25` = 0.25%; max `3000` = 30%). Omit or `null` for the default. |
| `provider`    | Stacks principal                        | Your integration's address. Attributes the swap to you on-chain.                                            |

**Where to send them**

| Endpoint                                               | `agg_fee_bps`                      | `provider`                                               |
| ------------------------------------------------------ | ---------------------------------- | -------------------------------------------------------- |
| `POST /quotes/v2/quote`, `POST /quotes/v2/quote/multi` | Prices the fee into `protocol_fee` | Echoed back as `protocol_fee.provider` (not on-chain)    |
| `POST /quotes/v2/agg/swap`                             | Signs the fee into the transaction | Embedded on-chain as the trailing `(optional principal)` |
| `POST /quotes/v2/swap` (legacy router)                 | Not supported                      | Embedded in the parameters tuple (attribution only)      |

Send the **same** `agg_fee_bps` to the quote and to `/quotes/v2/agg/swap`, and send `provider` to `/quotes/v2/agg/swap`: only that call puts it on-chain.

**How the fee is taken**

* The fee is `floor(amount_out × agg_fee_bps / 10000)`, in the output token.
* `amount_out` and `min_amount_out` in the quote are **before** the fee. Show users `amount_out − protocol_fee.amount`.
* The quote returns the fee on each route, for example `"protocol_fee": { "bps": 25, "amount": "593972", "provider": "SP…" }`.
* `/quotes/v2/agg/swap` signs the exact fee into the transaction. `min_out` is your slippage floor minus the fee, so the user's slippage protection covers what they actually receive.
* On-chain, the router sends the fee to Bitflow's aggregator treasury (`SP3B8F1ERXWHQ7FSZB6RSJA1S12DBQZZNYYHTPBFF.agg-treasury-v-1-1`) and the rest of the output to `recipient`.
* A route through a legacy single-pool core can't carry a fee above `0`. With a fee set, pick routes with `agg_buildable: true`.

**Errors**

| Endpoint              | Cause                                   | Response                                   |
| --------------------- | --------------------------------------- | ------------------------------------------ |
| Quote                 | `agg_fee_bps` malformed or above `3000` | `400`, `error_code: "INVALID_AGG_FEE_BPS"` |
| Quote                 | `provider` is not a Stacks principal    | `400`, `error_code: "INVALID_PROVIDER"`    |
| `/quotes/v2/agg/swap` | Bad `agg_fee_bps` or `provider`         | `invalid_input`                            |

**Revenue share**

{% hint style="info" %}
Bitflow shares the fees from your swaps with you automatically. Every day at 00:00 UTC, Bitflow shares a portion of fees collected on swaps that carry your `provider` address to that address, in the tokens the fees were collected in. No sign-up is needed: set `provider` and `agg_fee_bps` on your swaps.

To be paid to a different address, or to discuss a different split, contact the team (<help@bitflow.finance> or Discord).
{% endhint %}

* Only swaps that carry your `provider` **and** a fee above `0` earn a share. Swaps with no `provider` pay the fee to Bitflow only.
* Payouts are amounts already collected on-chain. Each payout is a public transaction from `agg-treasury-v-1-1` to your address.
* `provider` never changes routing or amounts. Only `agg_fee_bps` changes what the user receives.

***

#### 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` (optional `agg_fee_bps`, `provider`)            |
| POST   | `/quotes/v2/quote/multi`                                | All routes (optional `agg_fee_bps`, `provider`)                                    |
| POST   | `/quotes/v2/swap`                                       | Legacy router contract-call parameters (optional `provider`)                       |
| POST   | `/quotes/v2/agg/swap`                                   | Aggregator (`agg-*`) contract-call parameters (optional `provider`, `agg_fee_bps`) |
| 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                          |

```javascript
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.

```bash
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](https://docs.bitflow.finance/bitflow-documentation/developers/hodlmm-api-documentation) 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`.
