Marketplace API

• REST. Two trees — the complete versioned record, and a curated flat projection for consumers that are not browsers. Start at GET /liens/facets, then GET /liens.
• OpenAPI 3.1. Built from the routes themselves, so it cannot describe a parameter the API does not accept. Point a generator at it rather than hand-writing a client.
• MCP. If your client speaks Model Context Protocol, prefer it: its search_liens ranks on net yield using the same arithmetic this site displays, so you get our numbers rather than your reconstruction of them.

The book runs to 250+ live tax lien certificates and redeemable tax deeds. Terms are set by state statute and differ by state, so which states are represented changes with the inventory — ask /liens/facets rather than trusting a list on a page, and read the statutory mechanics for the rules each state sets.

# Texas liens under $50k, best net per-year rate first
curl -s 'https://api.lienfi.com/api/v1/liens?states=TX&max_price=50000&sort_by=apy_high_low&limit=5'

# What is actually in stock, before you filter blind
curl -s 'https://api.lienfi.com/api/v1/liens/facets'

# One lien, flat, no envelope
curl -s 'https://api.lienfi.com/api/public/liens/<id>'

There is nothing to sign up for and nothing to send in a header. If you get a CORS error, you are calling the versioned tree from a browser — see Limits, CORS and caching. The one call that can still refuse you is buy-price, which needs the buyer's wallet to belong to a consenting account.

npm i @lienfi/sdk
npm i viem      # only for the onchain helpers

@lienfi/sdk on npm — the full reference, including the purchase rules that cost money to get wrong.

import { LienFiClient, buildPurchaseCalls } from '@lienfi/sdk';

const client = new LienFiClient();

// Same rows, same `calculated` block, as GET /liens — typed.
const { liens, feeConfig } = await client.listLiens({
  states: 'TX', max_price: 50000, sort_by: 'apy_high_low', limit: 5,
});

// null means we could not read FeeManager. It does NOT mean zero bps.
if (!feeConfig) throw new Error('no fee rate; do not rank on net');

// Bound to this buyer for 300s. Fetch it immediately before you send.
const quote = await client.getBuyPrice(liens[0].id, buyer);

const calls = buildPurchaseCalls(quote, { chainId: 8453 });
// calls.approve then calls.buy. approvalAmount === amountActuallySpent,
// so no surplus allowance survives a buy that reverts.

LienFiClient covers the public read surface with no key and no header, and the call builders construct the approve and buy for a purchase. It is the same purchase flow the LienFi marketplace itself runs, so an integration behaves identically rather than drifting from a re-implementation.

Zero runtime dependencies. viem is an optional peer — the whole REST client works without it, and the builders return plain call descriptors, so nothing in the package imports viem at runtime.

Valuations are not recomputed in the package. Every figure comes off each row's calculated block, which is where the API computes them — so the SDK, this page and the marketplace cannot report different money for one lien. Read Reading the numbers first; all four caveats there apply here unchanged.

Source-available under PolyForm Shield 1.0.0 — build a fund, vault, keeper, analytics product or agent on LienFi freely, including modifying and redistributing it. The one excluded use is a product that competes with LienFi.

{
  "success": true,
  "data": [ /* the liens */ ],
  "meta": {
    "pagination": { "total": 257, "page": 1, "limit": 20, "totalPages": 13,
                    "hasNextPage": true, "hasPrevPage": false,
                    "nextPage": 2, "prevPage": null },
    "fee_config": { "interest_fee_bps": 1000, "fee_version": 1 },
    "filters":    { "status": "listed", "price_range": {}, "interest_range": {} },
    "sorting":    { "sort_by": "apy_high_low" }
  }
}

Read the fee from meta.fee_config rather than assuming 1000 bps — GET /liens/{id} carries the same object on the lien itself. It is read from the chain when a lien redeems, so it can change.

The /api/public tree does not use the envelope at all: it answers the object directly, or { error, message } with a 404 / 500.

Fields get added to these responses, so ignore what you do not recognize rather than failing on it.

A 400 comes back in one of two shapes, and it is worth handling both. Anything the route's own schema catches — a limit over 100, a non-numeric bound, an unknown status, a malformed id — is a framework validation error, and carries no success key at all:

{ "statusCode": 400, "code": "FST_ERR_VALIDATION", "error": "Bad Request",
  "message": "querystring/limit must be <= 100" }

The cross-field and policy checks — a minimum above its maximum, a refused status, created_by_admin_id — use the envelope:

{ "success": false, "message": "min_price must not exceed max_price" }

So branch on the status code, not on body.success.

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

JSON-RPC 2.0 over stateless streamable HTTP. There is no session to open and no session id to carry: every request is independent, so a client can call tools/call without having called initialize first. Only POST is served — every other verb answers 405 in JSON-RPC shape rather than falling through to the REST envelope.

claude mcp add --transport http lienfi https://api.lienfi.com/api/v1/mcp

{
  "mcpServers": {
    "lienfi": {
      "type": "http",
      "url": "https://api.lienfi.com/api/v1/mcp"
    }
  }
}

curl -s -X POST 'https://api.lienfi.com/api/v1/mcp' \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

{ "jsonrpc": "2.0", "id": 1,
  "error": { "code": -32600, "message": "..." } }

{ "content": [ { "type": "text",
    "text": "{\"error\":{\"code\":\"lien_not_found\",\"message\":\"...\"}}" } ],
  "isError": true }

Rate limit. 120 requests per minute per IP, which is generous enough that an agent listing tools and screening the book will not notice it. Over the budget you get a JSON-RPC error telling you to slow down, not an HTML page.

1. 1

   See what this deployment serves

   agent

   Every request is one JSON-RPC 2.0 body to the endpoint above — there is no session and no handshake to complete first. tools/list is the authority: in production all ten tools are registered; on another deployment the wallet and purchase halves may be off, and the list says so.

   request

   {"jsonrpc":"2.0","id":1,"method":"tools/list"}

   Returns result.tools[], each with a JSON Schema for its arguments.

2. 2

   Research: the book, then a shortlist, then one lien

   agentsearch_liens

   No credential. market_overview says what is on the book and where; search_liens screens it and ranks the shortlist on NET yield, after our share of the gain — the same arithmetic this site displays; get_lien is the full record for one candidate. Liens under a month from maturity come back in maturing_soon with no per-year rate, and liens that cannot be scored are counted under dropped rather than hidden.

   tools/call

   {
     "jsonrpc": "2.0",
     "id": 2,
     "method": "tools/call",
     "params": {
       "name": "search_liens",
       "arguments": {
         "budget_usd": 5000,
         "states": "FL",
         "limit": 5
       }
     }
   }

   Returns liens ranked on net_apy, plus maturing_soon, dropped, fee_config and apy_labels. Keep the lien_id of the one you want.

3. 3

   Your operator authorizes you, once, in a browser

   operator, in a browser

   The one human step. At /agents/authorize your operator signs an authorization naming your wallet address, the most you may spend on one lien, a cumulative total (recorded and reported back to you, not enforced) and an expiry no more than 90 days out. The page then hands them one ready-made prompt to paste to you, carrying everything else you need: the key-proof typed data for YOUR wallet to sign, one consent-v2 typed data per required agreement, the ready registration call, and an Authorization: Bearer <blob> header that IS the authorization. The same envelopes, and an mcpServers block, are on the page individually for a client that is driven by hand. When a tool answers not_registered, check that the call carried that header before anything else — 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 that link to your operator and stop; retrying cannot complete a browser step.

4. 4

   Sign the key proof and the consents

   agent wallet

   From the agent wallet, eth_signTypedData_v4 over the key-proof typed data — it binds your key to that exact authorization — and over each consent typed data, one per agreement. Sign them exactly as printed: the API rebuilds every message and refuses a signature made for a different network. A smart-account wallet is fine; contract signatures are verified on chain at registration.

5. 5

   Register

   agentregister_agent

   register_agent is POST /agents/register without leaving MCP: the operator authorization comes from the bearer already on the request, so you pass only what your wallet signed. POST /agents/register takes the same body if you would rather register over REST. From now on send the bearer on every call. Registering again with the same authorization is idempotent, and it tops up any consent that lapsed because a document was republished.

   tools/call · with Authorization: Bearer <blob>

   {
     "jsonrpc": "2.0",
     "id": 5,
     "method": "tools/call",
     "params": {
       "name": "register_agent",
       "arguments": {
         "agent_key_proof": {
           "specVersion": "agent-keyproof-v1",
           "signature": "0x…",
           "timestamp": 1756800000
         },
         "agent_consents": [
           {
             "specVersion": "consent-v2",
             "signature": "0x…",
             "documentType": "terms-and-conditions",
             "version": 3,
             "timestamp": 1756800000
           }
         ]
       }
     }
   }

   Returns registered: true, the binding’s expiresAt, and replay: true when this was an idempotent repeat.

6. 6

   Check yourself

   agentagent_status

   The first call to make when anything refuses. It answers whether the binding is active and when it expires, the wallet’s USDC and ETH, and the spend record — what has settled and what is live, beside the caps your operator signed, with enforced: false on the cumulative because only the per-lien cap is refused on.

   tools/call · with Authorization: Bearer <blob>

   {
     "jsonrpc": "2.0",
     "id": 6,
     "method": "tools/call",
     "params": {
       "name": "agent_status",
       "arguments": {}
     }
   }

   Returns registered, expires_at, balances, spend.

7. 7

   Price a candidate

   agentquote_lien

   An indicative price for one lien and whether the wallet can cover it. Nothing is signed and nothing is reserved, so ask as often as you like. affordable is null when the balance could not be read — never a false no.

   tools/call · with Authorization: Bearer <blob>

   {
     "jsonrpc": "2.0",
     "id": 7,
     "method": "tools/call",
     "params": {
       "name": "quote_lien",
       "arguments": {
         "lien_id": "<lien-uuid>"
       }
     }
   }

   Returns lien_price_usdc, total_to_approve_usdc, affordable, shortfall_usdc.

8. 8

   Prepare the purchase

   agentprepare_purchase

   Step 1 of the loop. Runs every gate a purchase would refuse on — authorization, the signed per-lien cap, both parties’ consents, sanctions, your max_total_usdc ceiling, and the wallet’s balance — and only then RESERVES: one purchase in flight per wallet, for ten minutes, and returns the acknowledgment typed data. A refusal here leaves nothing behind. max_total_usdc is a stale-quote guard, not a budget; the budgets are the caps your operator signed.

   tools/call · with Authorization: Bearer <blob>

   {
     "jsonrpc": "2.0",
     "id": 8,
     "method": "tools/call",
     "params": {
       "name": "prepare_purchase",
       "arguments": {
         "lien_id": "<lien-uuid>",
         "max_total_usdc": 2000
       }
     }
   }

   Returns reservation_id, acknowledgment.typed_data, total_to_approve_usdc, expires_at, spend.

9. 9

   Sign the acknowledgment

   agent wallet

   eth_signTypedData_v4 over acknowledgment.typed_data, from the agent wallet, exactly as returned. confirm_purchase rebuilds the message from what prepare stored, so an edited or re-timestamped copy does not verify.

10. 10

    Confirm: the acknowledgment is recorded, then the price is signed

    agentconfirm_purchase

    Step 2. Records the acknowledgment as a pending legal record, THEN mints the LienFi price signature — bound to your wallet, valid for 300 seconds from this moment — and returns the transactions UNSIGNED: approve for exactly the total, buyNFT carrying the signature, and setApprovalForAll for the vault unless it is already granted. If the live price moved above your ceiling, the reservation is released and the signature discarded (quote_above_ceiling). Calling it again on the same live reservation returns a fresh bundle without re-recording the acknowledgment.

    tools/call · with Authorization: Bearer <blob>

    {
      "jsonrpc": "2.0",
      "id": 10,
      "method": "tools/call",
      "params": {
        "name": "confirm_purchase",
        "arguments": {
          "reservation_id": "<reservation-uuid>",
          "acknowledgment_signature": "0x…"
        }
      }
    }

    Returns transactions[] as { step, name, to, data, value, chainId, why }, data_suffix, expires_at, consent_id.

11. 11

    Submit the transactions, in order, from the agent wallet

    agent wallet

    Each one after the previous is mined with status: success. A reverted transaction is mined too, and a buyNFT sent after a reverted approve fails on allowance, one step removed from the cause. Append data_suffix to the calldata you actually broadcast — for a smart account that is the outer execute call — it is Base Builder Code attribution, and omitting it only loses attribution. All of it inside the 300 seconds. Without setApprovalForAll the lien is owned but cannot be redeemed.

12. 12

    Report the result

    agentreport_purchase

    Step 3. Pass the buyNFT hash and LienFi reads the receipt: a success carrying the purchase event settles the reservation; a revert releases it and marks the acknowledgment failed; an unmined hash answers receipt_pending — retry once it confirms. If you never submitted, report failed: true and the wallet may prepare another purchase at once. The indexer settles the record on its own too; reporting makes it immediate.

    tools/call · with Authorization: Bearer <blob>

    {
      "jsonrpc": "2.0",
      "id": 12,
      "method": "tools/call",
      "params": {
        "name": "report_purchase",
        "arguments": {
          "reservation_id": "<reservation-uuid>",
          "tx_hash": "0x…"
        }
      }
    }

    Returns settled: true, paid_usdc, vault_approval — and a warning while the vault approval is not confirmed.

13. 13

    Verify

    agentmy_positions

    What the wallet holds, valued live and confirmed on chain, with anything the chain does not confirm reported separately rather than hidden. A purchase completed a moment ago may take the indexer a little while to appear.

    tools/call · with Authorization: Bearer <blob>

    {
      "jsonrpc": "2.0",
      "id": 13,
      "method": "tools/call",
      "params": {
        "name": "my_positions",
        "arguments": {}
      }
    }

    Returns confirmed_on_chain, claimed_but_not_confirmed, unknown_on_chain, vault_approval.

# 1. every gate, no signature, no reservation — needs no header
GET https://api.lienfi.com/api/v1/liens/{id}/buy-price?buyer=<agent>&intent=preflight

# 2. the signed quote. For a wallet bound to an agent authorization this IS the
#    reservation, and it takes the same bearer the MCP endpoint takes:
GET https://api.lienfi.com/api/v1/liens/{id}/buy-price?buyer=<agent>
    Authorization: Bearer <blob>

# 3. from the agent wallet, in order, each after the previous is mined:
#    USDC.approve(marketplace, totalAmount)
#    LienMarketplace.buyNFT(tokenId, lienPrice, maturity, deadline, baseValue, feeVersion, signature)
#    LienNFT.setApprovalForAll(vault, true)   # once per wallet; without it the lien cannot be redeemed

Some carry more than a code: not_registered and the authorization_* refusals carry handoff_url for the operator; purchase_in_flight names the live reservation; insufficient_funds carries the shortfall; quote_above_ceiling carries the quoted total and your ceiling. The retryable ones say so in their sentence; nothing marked terminal changes on a retry.

• OpenAPI 3.1 — generated from the routes' own schema blocks. The admin, internal and webhook trees are withheld from it deliberately.
• /llms.txt — the same conventions as prose for a model, and the entry point an agent should be given.
• /sitemap.xml — every live lien page, each of which server-renders a record of the listing.