# Licita — public procurement intelligence for AI agents

## Overview
Licita answers the questions an agent needs to act on EU public procurement: recent tenders,
renewal/re-tender signals, company opportunities and active buyer activity. It sells decisions and
intelligence, not raw data: every finding carries evidence, a confidence label (low|medium|high) and
provenance (source + source_ref + upstream url). Data: TED (Tenders Electronic Daily) award notices
(live, default) plus PLACSP when PLACSP ingestion is enabled. Nulls are never fabricated.

## Try it — POST /v1/research (paid, x402 mode)
POST /v1/research  {"query": "health sector IT services", "limit": 5}
→ 200 {"data": {"topic": "health sector IT services", "confidence": "high",
     "summary": "Recent EU procurement activity for \"health sector IT services\": 3 tender(s) ...",
     "findings": [{"type": "tender", "title": "Servicios de ciberseguridad para hospitales públicos",
       "detail": "Tender 13001: 72000000; estimated value EUR 180000.", "source": "ted",
       "source_ref": "130001-2026", "timestamp": "2026-06-20",
       "evidence": ["tender: Servicios de ciberseguridad para hospitales públicos"]}],
     "windows": {"tenders_days": 90, "renewals_days": 365}},
   "meta": {"request_id": "<uuid>", "price_usd": "0.50", "paid": true,
     "provenance": [{"source": "ted", "source_ref": "130001-2026"}],
     "generated_at": "<iso>", "methodology": "...NOT a probability estimate."}}
Confidence rule: evidence-strength heuristic over distinct finding types with a finding within the
last 90 days: >=2 types → high, 1 → medium, else low. Deterministic over the licita database (no LLM).

## Endpoints (USD per call; JSON envelope {data, meta})
- POST /v1/research — $0.50/call (research brief; always paid, config-driven)
- GET /v1/search — $0.02/call
- GET /v1/tenders/:id — $0.02/call
- GET /v1/companies/:id — $0.05/call
- GET /v1/companies/:id/awards — $0.05/call
- GET /v1/companies/:id/opportunities — $0.10/call
- GET /v1/buyers/:id/history — $0.05/call
- GET /v1/renewals — $0.25/call
- GET /v1/pricing — free
- GET /v1/stats — free
- GET /v1/demo — free
- POST /v1/billing/credits/5 — $5.00/call
- POST /v1/billing/credits/10 — $10.00/call
- POST /v1/billing/credits/25 — $25.00/call
- GET /v1/billing — free
- Common params: q (full-text), cpv (prefix), buyer, company, region (NUTS), from/to (YYYY-MM-DD),
  type=award|tender|contract, page, size (<=100)
- GET /v1/demo is a free labeled sample (recent tender + renewal signal) — validate before paying.
- GET /v1/stats additionally requires header x-operator-key (operator only)

## MCP
- Streamable-HTTP at POST /mcp (transport is free; tools priced like their REST equivalents).
  Tools: search_tenders, get_tender, get_company, get_company_awards, get_company_opportunities,
  get_buyer_history, get_renewals, get_pricing, research, billing_get_balance, billing_purchase_credits.
- Static server card: /.well-known/mcp/server-card.json (identity, SSE URL, tool schemas).
- Every tool accepts optional payment_token — the base64 payment payload (same value a REST client
  sends as PAYMENT-SIGNATURE). Unpaid calls return {"payment_required": true, "price_usd": ...,
  "how_to_pay": {...}} with isError=false (parse as data, then pay + retry with payment_token).
- Paid tools also accept optional client_key: when set, the call first tries to pay from the prepaid
  balance instead of requiring a per-call proof.

## Credits (prepaid balance)
- One-time x402 purchase, no subscription. Buy: POST /v1/billing/credits/5 (or /10 /25) — $5.00 /
  $10.00 / $25.00. The payment proof is verified and recorded (replay blocked), then the account is
  credited.
- Pay from balance: send header x-client-key: <your key> on every priced request (REST) or the
  client_key argument on paid MCP tools. Insufficient balance falls back to the normal 402 flow.
- Check balance: GET /v1/billing (free) with header x-client-key; 404 when no account exists yet.
- MCP: billing_purchase_credits (paid, args: client_key + amount 5|10|25 + payment_token) and
  billing_get_balance (free, args: client_key).

## Payment (x402 v2; current mode: x402)
1. Call a paid endpoint without payment → HTTP 402 with a base64 PAYMENT-REQUIRED response header.
   The header value is JSON { x402Version: 2, resource, accepts[] }; accepts[0] is the exact
   requirement: scheme "exact", network (CAIP-2), USDC asset contract, amount (base units), payTo
   (recipient), maxTimeoutSeconds, and the EIP-712 domain (extra.name / extra.version) for signing.
2. Sign an EIP-3009 transferWithAuthorization of USDC for that amount on the stated network with an
   x402 client (or viem), producing a base64 payment payload.
3. Retry the request with the base64 payload in the PAYMENT-SIGNATURE header (v2). The server
   verifies AND settles the payment with its facilitator before serving content; proofs are
   single-use (replay rejected).
4. Legacy: the v1 X-PAYMENT header is still accepted for backward compatibility; v1 payloads are
   clearly marked x402Version: 1.
5. Local development ONLY (PAYMENTS_MODE=dev): POST /v1/dev-faucet {"endpoint": "<METHOD PATH>"} →
   {token, expires_at}; retry with header X-PAYMENT: <token>. The faucet route exists only when
   PAYMENTS_MODE=dev and NODE_ENV is not production — it is NOT available in production (the path 404s).

## Discovery
- /llms.txt (this file), /openapi.json (OpenAPI 3.1), /v1/pricing (machine-readable price ladder +
  payment flow), /docs (human docs), /pricing (price table), /mcp (MCP endpoint),
  /.well-known/mcp/server-card.json (MCP server card)
- Paid 402s carry extensions.bazaar (x402 Bazaar discovery extension) so facilitators catalog Licita.
- Use cases: /use-cases (index) and /use-cases/tender-intelligence, /use-cases/company-research,
  /use-cases/buyer-intelligence, /use-cases/renewals-forecasting — agent missions with the exact
  endpoints, costs and real response shapes.
- Data: /data (overview), /data/spain (PLACSP Spain), /data/eu (TED EU) — sources, coverage, examples.

## Response envelope
- Success: {"data": ..., "meta": {"request_id", "price_usd", "paid", "provenance": [...]}}.
  meta.provenance is an array of { source, source_ref, url }.
- Error: {"error": {"code", "message", "hint"}}. codes: invalid_query | not_found |
  payment_required | rate_limited | internal. The hint is agent-actionable.
- Nulls are never fabricated; framework agreement values are ceiling amounts, not actual spend.

## Renewals honesty
- GET /v1/renewals signals (framework_expiry | duration_expiry | recurrence) are a DETERMINISTIC
  HEURISTIC over historical awards and contract dates — NOT calibrated probabilities.
  meta.methodology states this framing; meta.confidence_scale is only [low, medium, high]; every
  signal exposes its full evidence in basis.

## Limits
- Rate limit: 60 requests/min per client; over limit → 429 with retry-after.
- ToS / attribution: reuse the data per the upstream sources' terms (TED and PLACSP) and attribute
  the source when republishing. See /docs.