> For the complete documentation index, see [llms.txt](https://docs.bsc.lista.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bsc.lista.org/for-developer/collateral-debt-position/api.md).

# CDP API

Read-side endpoints for the **lisUSD CDP**, where each position is backed by a single collateral type (`ilk`). They are keyed by `ilk` (collateral type) and collateral token address, not by a Moolah `marketId`.

> The CDP is being wound down — see [Mechanics](/for-developer/collateral-debt-position/mechanics.md). These feeds serve existing positions. For Moolah markets use [Positions, Liquidation & Emission](/for-developer/services/lending-api/position-liquidation-emission.md).

Base URL, response envelope, and chain selector follow the same conventions as the rest of the API — see [Conventions](/for-developer/services/lending-api/conventions.md). Pagination on these CDP feeds is its own scheme, `start`/`count` (documented per endpoint below), **not** the `page`/`pageSize` scheme conventions.md documents for the Moolah-market endpoints.

## Liquidation feeds

These `/api/v2/liquidations/*` and `/api/v2/liquidated` endpoints serve the **CDP (single-collateral) borrow product**, not Moolah markets. They read from the borrower index and key results by collateral token address. Use [Positions, Liquidation & Emission](/for-developer/services/lending-api/position-liquidation-emission.md) for Moolah-market liquidations.

### GET /api/v2/liquidations/red

Positions that are currently liquidatable (current price has crossed the position's liquidation price).

| Parameter | Type   | Required | Description                                                                                                                  |
| --------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `start`   | number | No       | Offset, snapped down to a multiple of 10 and floored at `0`. Omitting it (or sending garbage) defaults to `0`, not an error. |
| `count`   | number | No       | Page size, snapped down to a multiple of 20 then clamped to `[20, 100]`. Omitting it defaults to `20`.                       |

Response `data`: `{ users: [...] }`, each entry containing `userAddress`, `tokenName`, `collateralCurrency`, `collateral`, `liquidationPrice`, `liquidationCost`, `rangeFromLiquidation`. On this endpoint `rangeFromLiquidation` is always `0` (the positions are already liquidatable), and `liquidationCost` is a high-precision decimal string of up to 20 fractional digits — parse it with a big-number library, not `parseFloat`.

### GET /api/v2/liquidations/orange

Positions approaching the liquidation threshold (within the danger band, but not yet liquidatable). Same parameters and response shape as `/red`, but **not the same ordering**: `/red` sorts by liquidation price descending, `/orange` by `rangeFromLiquidation` ascending. Here `rangeFromLiquidation` reflects the remaining buffer to liquidation.

### GET /api/v2/liquidations/auctionUser

Look up the borrower(s) and clipper (auction contract) for a given liquidation auction.

| Parameter   | Type   | Required | Description               |
| ----------- | ------ | -------- | ------------------------- |
| `auctionId` | number | No\*     | Auction identifier.       |
| `token`     | string | No\*     | Collateral token address. |

> \* Both are bound unconditionally as equality filters. Omitting either returns an empty `users` array rather than an unfiltered list.

Response `data`: `{ users: [{ userAddress, clipperAddress }] }`.

### GET /api/v2/liquidated

Recently liquidated CDP positions.

| Parameter | Type   | Required | Description                                |
| --------- | ------ | -------- | ------------------------------------------ |
| `start`   | number | No       | Offset. Defaults to `0`.                   |
| `count`   | number | No       | Page size. Defaults to and capped at `20`. |

### GET /api/v2/liquidated/:user

Liquidations for one address. `GET /api/v2/liquidated/:user/latest?collateral=` returns the volume-weighted average liquidation price for an address and collateral.

> Addresses are stored lower-cased by the indexer and `/liquidated/:user` passes the value through verbatim — send lower-case.

## Market feeds

`/api/cdp/market/*` serves the CDP markets themselves. `/info`, `/borrowRate/history` and `/userBorrow/history` each take a required `ilk`. `/list` is a paginated listing filtered by collateral **symbol**, returning the `ilk` per row; `/search` takes a required `typeId=collateral`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.bsc.lista.org/for-developer/collateral-debt-position/api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.