# LienFi

> A marketplace for tokenized US tax lien certificates and redeemable tax deeds,
> settled onchain in USDC on Base. Each listing is a claim on delinquent property
> taxes, secured by the underlying real estate, with a statutory redemption
> deadline and a defined payout.

The public listing book is available as JSON, without a credential and without a
browser. Prefer the API below over scraping this site: the pages carry a
server-rendered record of every listing, but screening 250+ liens on price, state
and yield is a query, and the JSON is where queries are cheap.

## API

Base URL: https://api.lienfi.com/api/v1
OpenAPI 3.1: https://api.lienfi.com/api/v1/openapi.json
Human-readable reference: https://app.lienfi.com/docs/api — every endpoint and query param
below, its enumerated values, the sort keys, the MCP tools with their arguments,
and the same money conventions restated for a person. Server-rendered, so it is
readable as HTML. It opens with a copyable brief written for exactly this
purpose; if you are choosing between that page and this file, that block is the
denser one.

- `GET /liens` — the listing book, with filters and pagination. Roughly 30
  query params; the ones that matter for screening are `states`, `counties`,
  `min_price` / `max_price`, `min_interest` / `max_interest`, `max_ltv`,
  `property_types`, `lien_types`, `maturity_before` / `maturity_after`,
  `search` (free text over address, parcel ID, certificate number, county) and
  `sort_by`. `limit` caps at 100 and defaults to 20.
- `GET /liens/{id}` — one lien in full, including the live `calculated` block.
- `GET https://api.lienfi.com/api/public/liens/{id}` — the same lien as flat camelCase JSON with no
  response envelope: the investment facts only, on a curated allowlist. Start
  here unless you need the full record. It is the one endpoint that carries
  `netPerYearPercent` — what a buyer actually keeps, per year — beside the
  gross figures, so you do not have to apply the fee yourself.
- `GET /liens/facets` — the distinct values and real numeric bounds of the live
  inventory. Call this first to learn which states and counties actually have
  stock rather than guessing.
- `GET /liens/map` — the same filter surface, unpaginated, as slim
  location records.
- `GET /market/activity` — recent sale results (hammer prices and lots, no
  wallet addresses).
- `GET /legal` — the terms and risk disclosure, as documents.

## MCP

If you speak Model Context Protocol, use it instead of the REST endpoints above:

    POST https://api.lienfi.com/api/v1/mcp

Stateless streamable HTTP, JSON-RPC 2.0, nothing to install. `tools/list` is the
authority on what a deployment serves. The step-by-step walkthrough, with a
request body for every call and every refusal code with what to do about it:
https://app.lienfi.com/docs/api#mcp-walkthrough

1. Research, no credential: `market_overview` (what is on the book and where),
   `search_liens` (a shortlist ranked on NET yield, after our share of the gain,
   with the same arithmetic the site displays), `get_lien` (one lien in full).
   Liens under a month from maturity come back in a separate `maturing_soon`
   list with no per-year rate; liens that cannot be scored are counted, not
   silently dropped.
2. Your operator authorizes you once, in a browser, at https://app.lienfi.com/agents/authorize.
   The page hands them one ready-made prompt to paste to you, carrying what your
   wallet signs (a key proof and one consent per agreement), the registration
   call, and an `Authorization: Bearer <blob>` header that IS the authorization.
   When a tool answers `not_registered`, first check the call carried that
   header — registering opens no session, and a call without it is refused this
   way even after you have registered. If it did, the refusal carries
   `handoff_url`: surface it to your operator and stop.
3. Register: `register_agent` (where enabled) or `POST /agents/register`, with
   the signatures from your own wallet. Send the bearer on every call after,
   starting with the very next one.
4. `agent_status` (registered? expiry, balances, the spend record) and
   `quote_lien` (indicative price, affordability). Neither signs or reserves.
5. Buy: `prepare_purchase`
   runs every gate — authorization, the signed per-lien cap, consents, sanctions,
   the wallet's balance — RESERVES (one purchase in flight per wallet) and
   returns acknowledgment typed data; sign it from your wallet;
   `confirm_purchase` records it, mints the 300-second LienFi price signature
   and returns UNSIGNED transactions — `approve` for exactly the total,
   `buyNFT`, and the vault approval when needed — which your wallet submits in
   order, each after the previous is mined with status success;
   `report_purchase` with the buyNFT hash, or `failed: true`.
6. `my_positions` to verify.

LienFi never holds a key and never submits a transaction; it signs only the
price. Two signed caps: the per-lien cap is enforced when a price is signed
(`cap_exceeded_per_purchase`); the cumulative is recorded and reported, not
enforced. A second live quote is refused with `purchase_in_flight` naming the
first. Purchases are final. The same loop is available over REST:
`GET /liens/{id}/buy-price?buyer=<agent>` with the same
`Authorization: Bearer <blob>` header (a bound wallet answers 401
`authorization_required` without it; add `&intent=indicative` to price without a
bearer or a reservation), then `approve`, `buyNFT` and `setApprovalForAll`
from your own wallet.

## Reading the numbers

These are the things that are not guessable from the field names, and each one
has been got wrong before:

- **Every yield the API returns is gross.** `calculated.apy` also compounds. It
  has no consumer in our own interface and is almost certainly not what you want.
- **A buyer pays `listing_price`.** At redemption the vault charges
  `interest_fee_bps` of the **gain over that purchase price** — not of the
  redemption value — floored at zero, so a lien redeeming below what the buyer
  paid is charged nothing. At the default 1000 bps, a $1,000 lien redeeming at
  $1,100 is charged $10 and the buyer keeps $1,090. Read the live rate rather
  than assuming 1000: `GET /liens` carries it at `meta.fee_config`,
  `GET /liens/{id}` on the lien object as `fee_config`. It is read from the
  chain when the lien redeems, so it can change.
- **`redemptive_value`, `accrued_interest` and `listing_price` on the raw
  row are frozen snapshots** written at create/update time, and are stale on
  essentially every row. The `calculated` block is recomputed live on read —
  use `calculated.current_redemptive_value` and
  `calculated.current_listing_price`.
- **Per-year rates on our own surfaces annualize simply** (`return * 365 / days`),
  because a certificate pays once at redemption and there is nothing to
  reinvest. We do not publish a per-year rate for a lien maturing in under 30
  days — there is no year there to restate over.
- **The asking price on most listings MOVES, and `deal_type` is what says so.**
  `par` — nearly the whole live book — is priced AT the redemptive value and is
  recalculated on every quote, so the price climbs with accrual and a redemption
  on the day of purchase returns the basis and no gain. `discount`
  and `premium` are a set percentage either side of the same live figure, so
  they move too. Only `fixed` is a flat dollar amount that stays put. The
  curated endpoint publishes it as `listingType`, and null there means the lien
  is not on offer.
- **`redemption_deadline` is the statutory deadline and is immutable onchain**
  once the lien is minted. It is not recomputed and should not be inferred.

## Risk

A tax lien is not a deposit and not a bond. Redemption is the expected outcome
but not a guaranteed one; the remedy if it does not occur is foreclosure on the
property, which is slow, jurisdiction-specific, and not something this platform
underwrites. Rates and deadlines are set by state statute and differ by state.
Read the risk disclosures in https://app.lienfi.com/legal/terms-and-conditions — sections 4
(tax lien and tax deed) and 5 (digital asset and blockchain) — before summarizing
any listing as an investment recommendation. They were a standalone Risk
Disclosure Statement until 2026-08-31; that document is still published and still
readable, but the Terms are the current source.

## Pages

- [Marketplace](https://app.lienfi.com/) — the listing book. The interactive table is
  client-rendered, but the full book is also server-rendered into the HTML as a
  text index with a link to each lien. Use the API above to screen or sort it.
- [How tax liens work](https://app.lienfi.com/education) — statutory mechanics per state,
  with worked examples. Server-rendered and readable as HTML.
- [API reference](https://app.lienfi.com/docs/api) — the endpoints and parameters above as a
  page, if you would rather read HTML than this file.
- [Agent access](https://app.lienfi.com/agents) — authorize an agent wallet and configure the
  hosted MCP server without sharing its private key.
- [Individual listings](https://app.lienfi.com/sitemap.xml) — every live lien page
- [Terms](https://app.lienfi.com/legal/terms-and-conditions) — includes the risk
  disclosures (sections 4 and 5)
- [Privacy policy](https://app.lienfi.com/legal/privacy-policy)
- [About LienFi](https://lienfi.com/llms.txt) — the marketing site's own summary