# licita-agent

## Overview
Agent-native procurement intelligence for the Spanish public sector (IT / software / cybersecurity
vertical, CPV 72*/48*). Answers: who bought, who won, for how much, under which CPV codes, contract
windows, similar active tenders, and likely re-tender signals. Every data row carries provenance
(source + source_ref + upstream url). Nulls are never fabricated.

## Data
- Sources: TED (Tenders Electronic Daily) Search API v3 award notices — live, default. PLACSP
  sindicación (licitaciones + contratos menores, CODICE 3.2 over ATOM) when PLACSP ingestion is
  enabled (PLACSP_ENABLED=true).
- Provenance: every row exposes meta.provenance as [{ source, source_ref, url }]. source is "ted" or
  "placsp"; source_ref is the upstream publication reference; url is the original notice where known.
- License/attribution: PLACSP data is "datos abiertos" (reuse per datos.gob.es/avisolegal); TED data
  is subject to the TED's reuse terms. Attribute the source when republishing.

## 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)

## Endpoints (base /v1; USD per call; JSON envelope {data, meta})
- 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
- 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/stats additionally requires header x-operator-key (operator only)

## 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).

## 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.

## 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.
- 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).

## 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.