Docs — Licita

Discovery order (for agents)

1. GET /llms.txt — concise machine-readable service description.
2. GET /openapi.json — full REST schema.
3. GET /v1/pricing — machine-readable price ladder + payment flow.
4. Call paid endpoints, paying per call (below), or use MCP at /mcp.

Research — POST /v1/research

One paid call ($0.50 USDC via x402, config-driven) turns a topic into a deterministic research brief. NO LLM and no external APIs: every finding comes from the licita database through the same builders as the raw endpoints, so it is reproducible and fully auditable.

• Contract — body { "query": "<topic>", "limit": 1–10 }; returns data.topic, data.confidence, data.summary, data.findings[] and data.windows in the standard envelope.
• Finding types — tender, renewal, opportunity, buyer; each carries evidence[] plus source/source_ref.
• Confidence rule — evidence-strength heuristic: ≥2 distinct finding types with a finding within the last 90 days → high; exactly 1 → medium; else low. Deterministic and explainable, not a probability estimate. meta.methodology states this framing explicitly.
• Evidence & provenance — each finding lists its evidence lines; the envelope exposes meta.provenance (deduped { source, source_ref }, up to 10) and meta.generated_at.

Example: POST /v1/research {"query": "health sector IT services", "limit": 5} → a brief with confidence, summary and findings (see the homepage for the full shape).

Demo — GET /v1/demo

Free, zero-cost sample of what the paid API returns: the single most recent tender and the single most recent renewal signal, each under an explicit sample: true marker, plus the list of currently priced endpoints. Values are real rows — never fabricated. Use it to validate Licita data before paying.

Payment flow (x402 v2)

Priced endpoints require a payment per call. Unpaid requests get HTTP 402 with the exact requirement in a base64 PAYMENT-REQUIRED response header ({ x402Version: 2, resource, accepts: [{ scheme, network, asset, amount, payTo, maxTimeoutSeconds, extra }] }).

1. Call a paid endpoint without payment → 402 + PAYMENT-REQUIRED header.
2. Sign an EIP-3009 transferWithAuthorization of USDC for the advertised amount on the advertised network (scheme exact) with an x402 client, producing a base64 payment payload.
3. Retry the original request with PAYMENT-SIGNATURE: <payload> (v2). The legacy v1 header X-PAYMENT is still accepted for backward compatibility.
4. The server verifies and settles the payment through its facilitator before serving content; proofs are single-use.

Local development only (PAYMENTS_MODE=x402): when the payments mode is dev, POST /v1/dev-faucet mints a dev token instead — retry with X-PAYMENT: <token>. The faucet is not available in production.

# 1. Try a paid endpoint without payment → HTTP 402 + base64 PAYMENT-REQUIRED header
curl -i 'http://localhost:3000/v1/search?q=software&type=award'
# → 402
#   PAYMENT-REQUIRED: ", amount: "", payTo: "", ... }] }>

# 2. Sign an EIP-3009 transferWithAuthorization of USDC with an x402 client
#    (or viem directly) from the PAYMENT-REQUIRED requirement → base64 payload 

# 3. Retry with the payment payload (v2; legacy X-PAYMENT also accepted)
curl -s 'http://localhost:3000/v1/search?q=software&type=award' \
  -H "PAYMENT-SIGNATURE: "
# → {"data":[...],"meta":{"paid":true,"price_usd":"0.02",...}}

# 4. Local development only (PAYMENTS_MODE=dev): mint a dev token instead
curl -s -X POST 'http://localhost:3000/v1/dev-faucet' \
  -H 'content-type: application/json' \
  -d '{"endpoint":"GET /v1/search"}'
# → {"token":"","proof":"","endpoint":"GET /v1/search","amount":"0.02","expires_at":"..."}
curl -s 'http://localhost:3000/v1/search?q=software&type=award' \
  -H "X-PAYMENT: "

Billing — prepaid credits & the Creem MoR subscription arm

Per-call proofs are the default way to pay. For regular usage, prepaid credit bundles (5/10/25 USDC, one-time x402 purchase) are cheaper: send x-client-key on every priced request and calls debit the balance (GET /v1/billing reads it). Credits never expire and never touch the x402 proof path.

Monthly subscription (Creem MoR): POST /v1/creem/checkout with an email opens a Creem Checkout session for €29.00/month (config-driven — the price shown here is always the configured CREEM_PRICE_CENTS). After payment, Creem calls POST /v1/creem/webhook (signature-verified) and the account is marked kind=creem for 30 days.

How subscriber calls are billed (honest description): a subscription grants one-time credits, not metered per-call billing — each priced call debits your credit balance, and running out simply returns 402 until you refill. Trial keys that upgrade preserve their remaining calls; credits are consumed first and the preserved 25 trial calls stay usable. Creem handles the payment itself; Licita never sees a card number.

Trial/pro keys are not enabled on this deployment (TRIAL_ENABLED=false), so no trial quota branch is documented here; lct_ api_clients keys are inert and fall back to the credit/x402 proof path. Creem-subscriber keys (kind=creem) are unaffected — they were purchased, not granted.

Endpoints

GET /v1/stats additionally requires header x-operator-key. Common query params: page, size (≤100), cpv (prefix), region (NUTS), from/to (YYYY-MM-DD).

MCP

Streamable-HTTP MCP server at POST /mcp (transport is free; tools are priced like their REST equivalents). Each tool accepts an optional payment_token argument — the base64 payment payload (the same value a REST client sends as PAYMENT-SIGNATURE). Unpaid calls return {"payment_required": true, "price_usd": "...", "how_to_pay": {...}} as normal content (not an error) — parse it, create the payment with an x402 client from the PAYMENT-REQUIRED requirement, and retry with payment_token set. In dev mode how_to_pay points at the faucet instead.

Paid tools also accept client_key: when set, the call first tries to pay from the prepaid balance (see /pricing → Credits & billing) before requiring a per-call proof. Buy credits via billing_purchase_credits and check the balance via billing_get_balance.

# tools/list then e.g.
{"jsonrpc":"2.0","id":1,"method":"tools/call",
 "params":{"name":"search_tenders",
           "arguments":{"q":"software","type":"award","payment_token":""}}}

Discovery — Bazaar & the server card

• Bazaar extension on 402s — every paid endpoint and paid MCP tool advertises its discovery info via extensions.bazaar on the 402 PAYMENT-REQUIRED, so x402 facilitators can catalog Licita in Bazaar search (method, input/output examples, input schema).
• Server card — static MCP server card at /.well-known/mcp/server-card.json: identity, SSE transport URL and the 11 tools with descriptions and input schemas, for directory crawlers that prefer a static card over a live scan.
• How a facilitator catalogs Licita — hit GET /v1/pricing (free) for the ladder, then any paid call; the 402 requirement carries extensions.bazaar and the sanitized service metadata (name "Licita", tags procurement/tenders/eu/contracts/ai). Read the card at /.well-known/mcp/server-card.json for the MCP surface.

Conventions

• Envelope: {"data": ..., "meta": {"request_id", "price_usd", "paid", "provenance": [...]}}.
• Errors: {"error": {"code", "message", "hint"}} — the hint is agent-actionable.
• Nulls are never fabricated: unknown values stay null.
• Framework agreement values are ceiling amounts, not actual spend.
• Renewal signals (GET /v1/renewals) are deterministic heuristics over historical awards and contract dates with confidence low/medium/high — not calibrated probabilities. Each signal exposes its full evidence in basis.