# Limitguard lead validation API: full reference

> Limitguard is a lead validation service for lead generation agencies, B2B marketing and sales teams: it checks the company behind each lead against official business registers (full coverage in the Netherlands and Belgium), EU VAT and sanctions lists, with website age in the company check, and returns proceed, review or block with the source on every line. Developers and AI agents can use its HTTP API, MCP server and A2A service, hosted in the EU.

> Free sandbox key, no wallet: POST /v1/keys/create {"email": "you@example.com", "tier": "sandbox"} → lg_sandbox_ key → X-API-Key. Mock data, no charge, 10 req/min. The sandbox covers entity, risk and KYB checks; Lead Verify and the agent check need a live key or an x402 payment.
> Paid by x402: Lead Verify $0.10 per lead and agent check $0.005 per wallet; entity check and KYB $0.29 and risk score $0.25 fresh, $0.11 cached ($0.25 KYB) when available; report $0.55; sanctions and wallet screens $0.005; other routes at the account price. API keys, the dashboard and the Claude connector pay the account prices: Lead Verify $0.27 per lead and agent check $0.75 per wallet; $0.11-1.85 per call; entity and risk checks $0.88-1.05 fresh ($1.50 KYB), $0.11 cached ($0.25 KYB) when available (a cache miss returns 404 not_cached, no source is called).

- Checks: Dutch and Belgian company registers, EU VAT, sanctions, website domain and country risk, with a score and reasons; available checks depend on the product and the details supplied. Company-register coverage is limited to NL and BE.
- Price: agents paying by x402 from $0.005 per call, $0.25-$0.29 per fresh entity, risk or KYB check; API keys and the dashboard from $0.11 per call, $0.88-$1.50 per fresh check on the tiered endpoints, from $0.11 on a cached repeat; a free sandbox key returns mock data.
- Access: pay per call with x402 in USDC on Base or Solana with no signup, or use an API key debited from a prepaid balance. API keys and x402 have no subscription; the dashboard has monthly and yearly plans. The monthly request caps on keys are abuse limits, not quotas.
- Developers and AI agents: HTTP API at https://api.limitguard.ai, MCP at https://api.limitguard.ai/mcp and A2A at https://api.limitguard.ai/a2a. Integration guide: https://limitguard.ai/developers/.
- Hosting: in the EU (API and dashboard in the European Union, database in Ireland). Operator: Ambulatio Consulting BV (KVK 77272471), Breda, the Netherlands.
- Lead Verify: $0.27 per lead for Dutch and Belgian companies from an API-key balance, or $0.10 per lead paid per call with x402, over the HTTP API (POST /v1/leads/verify), MCP (verify_lead) and A2A (lead_verify). Whole lists upload in the dashboard at EUR 0.25 per lead.
- Agent check: $0.75 per EVM wallet from an API-key balance, or $0.005 paid per call with x402, over the HTTP API (POST /v1/agent/check), MCP (check_agent_wallet) and A2A (agent_check): sanctions address screen, Base balances, and the agent's ERC-8004 identity and open feedback.

For developers and AI agents: https://limitguard.ai/developers/?utm_source=llms_txt&utm_medium=agent&utm_campaign=developers&utm_content=lead_lines
Lead verification pricing, comparisons and NL/BE company-check guides: https://limitguard.ai/pricing/?utm_source=llms_txt&utm_medium=agent&utm_campaign=pricing&utm_content=buyer_pages, https://limitguard.ai/compare/lead-verification/?utm_source=llms_txt&utm_medium=agent&utm_campaign=compare&utm_content=buyer_pages and https://limitguard.ai/guides/?utm_source=llms_txt&utm_medium=agent&utm_campaign=guides&utm_content=buyer_pages

> Base URL: https://api.limitguard.ai
> OpenAPI: https://docs.limitguard.ai/api-reference/openapi.json

## What Limitguard does not provide, and why (law, not technology)
- DGA (directeur-grootaandeelhouder): a Dutch classification, not a register field. For tax it means a director holding at least 5% of the shares; labour and social-security law apply their own tests. A BV's shareholder register is private, so it cannot be derived reliably.
- UBO register data (Netherlands and Belgium): closed to the public since the CJEU judgment C-37/20 (22 November 2022). Access is limited to obliged entities (banks, notaries, accountants and the like) for their own use, competent authorities and, in some cases, parties that show a legitimate interest; none of these lets Limitguard resell extracts.
- Shareholders of a Dutch BV: the shareholder register is not public.
- Sanctions screening is a name match: entity, KYB, risk and reputation checks query the OpenSanctions lists; Lead Verify and /v1/sanctions/screen use local copies of the OFAC SDN, EU and UN lists. Limitguard does not trace ownership or control and applies no 50% ownership rule: an entity owned by a sanctioned party is flagged only if it is listed by name itself.

## Authentication Methods

### API Key (Prepaid Balance)
Header: `X-API-Key: lg_live_xxxxxxxxxxxxxxxxxxxx`
Key prefixes: lg_live_ (production), lg_sandbox_ (sandbox, Redis-backed), lg_test_ (dev/staging only)
Create key: POST /v1/keys/create (free, no auth required)
Key is shown once only. Stored as SHA-256 hash server-side.
Creating a key is free; calling a paid endpoint with it is not. A key on a paid tier
(indie, starter, growth, pro) holds a prepaid balance; each priced call is debited at
the account price in the table, and the key is told via 402 `insufficient_balance` when the
balance is short. Top up via x402: POST /v1/keys/upgrade/{tier} credits its price 1:1,
POST /v1/keys/topup/{usd} credits any whole-dollar amount at or above $5. A
`free` key holds no balance: its calls are still billed per request via
x402. A `sandbox` key returns mock data at no charge on endpoints that serve it (entity/risk/kyb,
the /v1/mcp/* mirrors, reputation) and is charged per call elsewhere.

### x402 V2 Micropayments (Pay-Per-Use)
Header: `PAYMENT-SIGNATURE: <base64-json>` (legacy `X-PAYMENT` also accepted)
Official client envelope: {x402Version: 2, accepted, payload: {signature, authorization: {from, to, value, validAfter, validBefore, nonce}}}; see /llms.txt 'x402 Payment Flow'.
Flat dialect fields (also accepted):
  chainId: CAIP-2 chain ID (e.g., "eip155:8453")
  amount: USDC amount in 6-decimal units (e.g., 290000 for $0.29, the agent price of /v1/entity/check)
  sender: Wallet address (0x... for EVM, base58 for Solana)
  recipient: Facilitator address from 402 response
  nonce: Unique hex string (0x + 32 random bytes)
  signature: EIP-3009 EIP-712 signature (EVM) or ed25519 (Solana)
  validAfter: Unix timestamp (now - 10)
  validBefore: Unix timestamp (now + 300)
Settled transfer (accepts scheme "settled-transfer", on the EVM chain that entry's `network` names for
this deployment): if you already sent the USDC, send its transaction hash instead of a signature:
`X-PAYMENT: 0x<64 hex chars>`. See /llms.txt 'Wire format D'.
Docs: https://docs.limitguard.ai/x402-protocol?utm_source=llms_txt&utm_medium=agent&utm_campaign=docs&utm_content=x402_auth

### Sandbox Mode
Use `lg_sandbox_` key prefix (registered via Redis) or `lg_test_` prefix (dev/staging only).
Rate limit: 10 req/min per IP. Returns mock data, no real sources called.
Note: the X-Limitguard-Mode header is NOT supported (removed).

## Quality Tiers

Header: `X-Response-Quality: cached|fresh|enhanced` (default: fresh)
- cached: Served only from cache (cheapest). A miss is HTTP 404 not_cached, no data source is called; retry with fresh.
- fresh: Always run full data source fan-out (default)
- enhanced: Retired 2026-09-24 (#405) on /v1/entity/check, /v1/risk/score, /v1/reputation/score and /v1/kyb/check: it took the identical fan-out as fresh and reached no source fresh does not. Sent anyway, those four are served and charged at the fresh price; the response's response_quality field and disclaimers say so. On /v1/entity/deep-check, enhanced is unaffected: it is the real "extended" tier (adds adverse_media).

## Supported Networks

| Network          | Chain ID                                          | USDC Contract                                      |
|------------------|---------------------------------------------------|----------------------------------------------------|
| Base Mainnet     | eip155:8453                                       | 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913         |
| Solana Mainnet   | solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp           | EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v      |

Testnets (Base Sepolia, Solana Devnet) are not accepted in production: /.well-known/x402.json says testnet_supported false.

## Pricing Table

### Tiered (X-Response-Quality)

| Endpoint                              | cached    | fresh     | enhanced  |
|---------------------------------------|-----------|-----------|-----------|
| POST /v1/entity/check                 | $0.11     | $1.05     | n/a       |
| POST /v1/risk/score                   | $0.11     | $0.90     | n/a       |
| POST /v1/reputation/score             | $0.11     | $0.90     | n/a       |
| POST /v1/kyb/check                    | $0.25     | $1.50     | n/a       |
| POST /v1/entity/deep-check            | n/a       | $0.88     | $1.71     |

These tables are the account prices: what an API key or the dashboard is debited. An x402 payment pays the agent prices in "Agent prices (x402)" below.

USDC 6-decimal units: $1.05 = 1_050_000. deep-check has no cached tier: `cached` is served and charged as fresh. The four `enhanced` cells marked n/a above sold the tier until #405 (2026-09-24); `enhanced` sent to any of them today is served and charged at that row's fresh price.

### Flat-Priced

| Endpoint                              | Price     |
|---------------------------------------|-----------|
| GET /v1/reputation/history/{hash}     | $0.11     |
| GET /v1/wallet/balance                | $0.11     |
| GET /v1/compliance/readiness/{id}     | $0.11     |
| GET /v1/compliance/alerts             | $0.11     |

### Agent prices (x402)

An x402 payment (REST, A2A or MCP pay-per-call on /mcp) pays these prices. API keys, the dashboard and the Claude connector pay the account prices above. A route not listed here costs its account price on x402 too. The official x402 SDKs refuse a payment above $1 by default, and every agent price is under it.

| Endpoint | Agent price (x402) | Account price |
|---|---|---|
| POST /v1/entity/check | $0.11 cached / $0.29 fresh | $0.11 cached / $1.05 fresh |
| POST /v1/mcp/check-entity | $0.29 | $1.05 |
| POST /v1/risk/score | $0.11 cached / $0.25 fresh | $0.11 cached / $0.90 fresh |
| POST /v1/mcp/risk-score | $0.25 | $0.90 |
| POST /v1/kyb/check | $0.25 cached / $0.29 fresh | $0.25 cached / $1.50 fresh |
| POST /v1/reports/entity | $0.55 | $1.85 |
| POST /v1/leads/verify | $0.10 | $0.27 |
| POST /v1/agent/check | $0.005 | $0.75 |
| POST /v1/mcp/verify-wallet | $0.005 | $0.11 |
| POST /v1/sanctions/screen | $0.005 | $0.11 |
| POST /v1/entity/light-check | $0.05 | $0.11 |
| POST /v1/seller/preflight | $0.005 | $0.11 |

### Free (No Payment, No Auth)

/health, /.well-known/*, /v1/keys/create, /v1/self-verify, /v1/methodology,
/v1/self-verify/signals, /v1/certificate/{hash} (GET),
/v1/legal/*, /llms.txt, /llms-full.txt

## All Endpoints

### Entity checks (Paid)
POST /v1/entity/check: Company check. Country risk and sanctions always run; the register, KVK annual accounts, VAT, domain, IBAN and wallet format checks run when their identifier is sent (an NL company without a KVK number gets a KVK name search)
  Body: entity_name*, country*, kvk_number?, cbe_number?, domain?, iban?, vat_number?, wallet_address?, wallet_chain?
  `entity_name` and `country` are required; identifiers (kvk_number, cbe_number, domain, iban, vat_number, wallet_address) are optional and raise confidence.
  Returns: trust_score (0-100), trust_level (high/medium/low/critical), cluster, recommendation (proceed/review/enhanced_due_diligence/block), confidence, top_factors[], sources_checked (int), processing_time_ms

POST /v1/entity/deep-check: Extended PEP/RCA screening + Dutch insolvency register ($0.88 fresh) or + adverse media ($1.71 enhanced)
  Body: entity_name*, country*, kvk_number?
  Returns: quality, sources_returned[], pep_extended{screened, pep_exposure, match_count, matches[], truncated, retrieved_at}, insolvency_records{screened, applicable, jurisdiction, query_by, found, match_count, records[], truncated, retrieved_at} (applicable: false outside NL), adverse_media{screened, adverse_media_found, match_count, category_hits, articles[], truncated, retrieved_at}? (enhanced only), processing_time_ms

POST /v1/risk/score: Quick risk (2 sources)
  Body: entity_name*, country*
  Returns: risk_score (0=low, 100=high), risk_level, recommendation, top_factors[], processing_time_ms

POST /v1/kyb/check: Know Your Business
  Body: entity_id*, registration_number*, country*, entity_name?, vat_number?, domain?
  Returns: verified (bool: trust_score 60 or more, not a register match), register_verified (bool: KVK/KBO found the company), register_checked (KVK/KBO/null), sanctions_flagged, kyb_status (approved/review_required/edd_required/rejected), trust_score, risk_flags[], group_structure {status (ok/not_found/unavailable/error), reason, lei, legal_name, direct_parent{lei,name,country}, ultimate_parent{lei,name,country}, registration_status, next_renewal_date, retrieved_at, cache_age_days, parents_screened: false}, group_chain (BE with NBB on, else null) {status, summary, links[{role,name,country,share_pct,scope,lei,lookup,source}]}

### Reputation (Paid)
POST /v1/reputation/score: Trust decay scoring
  Body: entity_name*, country (2-letter; required unless trust_score and cluster are both given), trust_score? (0-100), cluster?, last_verified_at? (unix, default: now), verification_count (default:1), agent_id?
  Without trust_score and cluster, they are computed from a sanctions screen of entity_name and the country's risk.
  Returns: reputation_score, decay_applied, cluster, agent_verified?

GET /v1/reputation/history/{entity_hash}: Score trend (last 52 recorded checks)
  Returns: history[] with timestamp, reputation_score, cluster, decay_applied

GET /v1/watchlist: List monitored entities
POST /v1/watchlist: Add entity (body: entity_id, entity_name, reason, rescore_interval)
DELETE /v1/watchlist/{entity_id}: Remove entity

### Compliance
GET /v1/compliance/alerts: Regulatory alerts ($0.11 per call on every API key tier; the dashboard's sanctions-list feed is included in the Growth, Pro and Enterprise workspace plans; daily OFAC/EU/UN sanctions-list changes plus hits on entities and wallets you checked; poll to read; alerts about entities or wallets you checked are also pushed to a webhook registered for sanctions.match.new)
  Query: jurisdiction?, severity?, limit (max 200), offset
  Returns: total, alerts[]

GET /v1/compliance/sources: Source health
  Query: jurisdiction?

POST /v1/compliance/subscribe: Alert subscription (narrows the alerts GET returns; the subscription sends nothing itself, alerts about entities or wallets you checked go to a webhook registered for sanctions.match.new)
  Query: entity_types[], severity_filter[], jurisdictions[], tier, webhook_url?
  Returns: subscription fields + notice

GET /v1/compliance/readiness/{entity_id}: EU AI Act readiness
  Query: system_type, completed_items[]
  Returns: risk_level, readiness_score, completed_items, total_items, gaps[], days_until_enforcement, urgency

GET /v1/compliance/report/{entity_id}: Withdrawn (#426); unpriced, answers 410
  Returned the same fixed briefing for every entity_id. Use /v1/compliance/readiness/{entity_id} instead.

### Entity Reports
POST /v1/reports/entity: Per-entity report built from one real check (201). Price: $0.55 by x402; $1.85 with an API key or the dashboard
  Body: entity_name + country, plus any of kvk_number, cbe_number, vat_number, domain, iban,
  wallet_address, wallet_chain; or check_id (a check an earlier report ran), never both
  Returns: report_id, check_id, schema_version, created_at, document_number (the PDF's
  number), entity, identity, identification, sanctions, pep, wallet, domain, financials,
  sector_comparison (NL same-sector median, as read when built), group_structure,
  group_chain, be_shareholders (every holder in the latest NBB filing; with no filing yet,
  gazette_url links to the founding deed in the Belgian Official Gazette), party_sanctions
  (#1848, when enabled: each shareholder and parent on the local OFAC/EU/UN lists, exact
  name key, at most 10, clear / hit / not_screened; a hit holds proceed at review), be_accounts,
  website_phones (+ website_phones_reason), kbo_functions, entity_links, company_website,
  activity_evidence,
  risk (trust_score 0-100, 100 = best; trust_level, recommendation, cluster, confidence,
  sources_checked, rules_fired), correlations, findings (up to 12), findings_note,
  sources (ok / unavailable / error, never a clean default), attributions, evidence.report_hash
  Sandbox keys get 403 report_not_available_in_sandbox: reports use real checks only.
  MCP: tool get_compliance_report (same input; an x402 payment pays the agent price, a key or the Claude connector the account price), and the same JSON except what the
  MCP privacy guardrail removes: every entity_name, entity_hash, matched_name, matched_entity, match_details, alias, aliases, address, birth_date, national_id and nationality key at any depth
  (the entity name, identity addresses and screening names), and wallet_address and iban
  masked. A paid key's prepaid balance is debited and refunded if the report is rejected; an
  x402 payment for a rejected report is never settled, so nothing is charged.
  A keyless x402 payer gets X-Report-Token (30 days) to read the report back.
GET /v1/reports/{report_id}: The stored report (free). Query: format=json|pdf
  Auth: the creating key, or X-Report-Token

### Agent Check
POST /v1/agent/check: Agent wallet check in one call. Price: $0.005 by x402; $0.75 with an API key or the dashboard
  Body: wallet (EVM 0x + 40 hex, read on Base), agent_id? (decimal ERC-8004 agentId),
    domain? (website domain; WHOIS age, mail records, TLS; not scored)
  Returns: verdict (block / review / no_findings), verdict_reasons, ran, did_not_run,
  sanctions (OFAC SDN digital-currency address list), balance (Base USDC and ETH),
  identity (ERC-8004 registration; with agent_id: owner, payment wallet, wallet_controls_agent),
  reputation (open ERC-8004 feedback, descriptive, never read by the verdict), wallet_risk,
  domain (WHOIS age, MX/SPF/DMARC, TLS, each probe's status; not_requested when omitted;
  never read by the verdict);
  each part has status ok / unavailable / error, never a clean default
  503 agent_check_unavailable when no wallet part could be checked (domain alone is not enough):
  nothing is charged.
  Sandbox keys get 403 agent_check_not_available_in_sandbox: live sources only.
  MCP: tool check_agent_wallet; A2A: skill agent_check. Same input and JSON; an x402
  payment pays the agent price, a key or the Claude connector the account price.

### Lead Verify
POST /v1/leads/verify: Is this NL/BE lead a real company I can call? Price: $0.10 by x402; $0.27 with an API key or the dashboard
  Body: country (NL or BE), company_number (8-digit KVK or 10-digit KBO) or name (NL only),
  and optionally vat_number, email, domain, address {street, house_number, postcode, city}, iban,
  phone (rejected with 422 until website phone lookup is switched on; never echoed),
  target_industries and target_size (your ideal customer profile; fill icp_fit, information only,
  never change the lead score)
  Returns: verdict (real_active / real_inactive / not_found / ambiguous / unverifiable /
  sanctioned), lead_score (0-100), company (as registered; registered_address, address_match),
  vat, iban (country, bank, BIC and last 4 only; holder_checked is always false), sanctions
  (local OFAC SDN, EU and UN lists; natural-person legal forms are not screened), email
  (has_mx, disposable), correlations (kvk_website_match, phone_match), website_phones (the
  numbers the company publishes on its website, while that lookup is on, each with its
  page_kind and register_number_on_page) and
  website_phones_reason, company_website (the company's own site, found and confirmed
  when none is given or registered; null when not run), flags (a company KVK lists as
  stopped has both inactive and
  business_stopped), findings, sources_checked. company.profile is the KVK record (NL only):
  industry, stopped date, staff, websites; a natural person's data is withheld.
  An input not given is not checked and never counts against the lead.
  422 lead_verify_invalid for a number the register cannot take; 503 lead_verify_unavailable
  when the register cannot be reached: nothing is charged.
  Sandbox keys get 403 lead_verify_not_available_in_sandbox: live registers only.
  MCP: tool verify_lead; A2A: skill lead_verify. Same input and JSON; an x402 payment
  pays the agent price, a key or the Claude connector the account price.

### Light Check
POST /v1/entity/light-check: Is this company registered and active? Price: $0.05 by x402; $0.11 with an API key or the dashboard
  Body: country (ISO 3166-1 alpha-2), registration_number (8-digit KVK or 10-digit KBO/CBE)
  and/or vat_number; one of the two is required
  Returns: register {status (active / inactive / not_found / not_covered / unavailable), name,
  source, as_of}, active, vat {status}, sanctions {status (no_match / possible_match /
  not_checked / unavailable), lists_checked, list_dates}, as_of, not_checked
  Calls no paid source: the free KVK search, the stored KBO register, VIES and the local lists.
  503 when no part could be checked: nothing is charged. Sandbox keys get 403.
  A2A: skill light_check. Same input and JSON. Not an MCP tool.

### Seller Preflight
POST /v1/seller/preflight: Check an x402 seller before you pay it. Price: $0.005 by x402; $0.11 with an API key or the dashboard
  Body: pay_to (the quote's payTo), network (CAIP-2, default eip155:8453; eip155:* or solana:*),
  resource_url (https, a public DNS name; IP literals and internal names answer 422),
  payer (optional, your own EVM wallet: its previous USDC payees on Base)
  Returns: verdict (ok / caution / block), reasons [{code, detail}], wallet {address_redacted,
  chain_id, sanctioned, lists, as_of}, domain {host, company, registered_at},
  company_sanctions, lookalike {status, reasons, declared, declared_masked, payer_history,
  previous_payee_masked}, as_of, sources
  block: the wallet is on the OFAC SDN list, or the payTo is a lookalike of the seller's published
  wallet or of one you paid before. caution: the list is not loaded, the domain company may match
  a sanctions entry, the domain is under 30 days old, the host has no RDAP record, the payTo is
  not the wallet the seller publishes, or its recent transfers to you were only dust or fake USDC.
  Calls no paid source unless payer history is on. Sandbox keys get 403.
  A2A: skill seller_preflight. Same input and JSON. Not an MCP tool.

### Sanctions Screen
POST /v1/sanctions/preview: Free yes/no screen against the local OFAC SDN, EU and UN lists
  Body: name (1-200 chars), country (optional ISO 3166-1 alpha-2)
  Returns: possible_match, lists_checked, list_dates, list_note, detail. Never an entry.
  10 per caller (API key, or client IP without one) per UTC day, and API keys
  calling from one client IP share a ceiling of 50; the next call
  gets 429 sanctions_preview_daily_limit with paid_path and Retry-After
POST /v1/sanctions/screen: The matched list entries. Price: $0.005 by x402; $0.11 with an API key or the dashboard
  Body: name, country (optional; orders matches, never excludes one)
  Returns: possible_match, matches (list, list_key, entry_id, entry_type, matched_name,
  programmes, countries, listed_on, match_score, match_type), matches_truncated,
  lists_checked, list_dates, list_note, disclaimer, screened_at
  Matching: exact normalised or word-order-insensitive name match, a trailing legal form
  ignored; no fuzzy matching, no outbound call. A name match is not a determination.
  MCP: tools sanctions_preview (free, same daily count) and sanctions_screen (same input; an x402 payment pays the agent price, a key or the Claude connector the account price);
  over MCP matched_name is withheld from match entries (DYN-509).
POST /v1/sanctions/wallet: Free yes/no check of a wallet address against the OFAC SDN list
  Body: wallet_address, chain_id (optional, default eip155:8453; CAIP-2 or base/eth/solana/btc),
  validated as POST /v1/mcp/verify-wallet (422 when the address does not fit the chain)
  Returns: wallet_address (canonical), chain_id, sanctioned, lists (["OFAC SDN"] on a match),
  as_of (list publication date), status (ok or stale), source, upgrade (path, tool, price_usd,
  adds: what the full screen adds). Never programmes or entry ids.
  Its own 10 per caller per UTC day, separate from the name preview, with the same
  ceiling of 50 per client IP; the next call gets 429
  sanctions_wallet_daily_limit naming POST /v1/mcp/verify-wallet ($0.005 by x402; $0.11 with an API key or the dashboard). 503
  sanctions_lists_unavailable when the list is not loaded (the call is not counted).
  MCP: tool wallet_sanctions_preview (same daily count); A2A: skill wallet_sanctions.

### Financial & Treasury (Auth Required)
GET /v1/wallet/balance?agent_id=...: ERC-8004 USDC balance (Base mainnet)
  Returns erc8004_agent_id: the registry's token id for the agent, resolved best-effort
  (Registered-log owner filter, then an indexed Transfer lookup confirmed via ownerOf), null
  when neither resolves it.
GET /v1/financial/health: System financial status (treasury balance and settlement fields: admin key only)
GET /v1/treasury/settlements?nonce=?: Settlement verification
GET /v1/treasury/revenue/{agent_id}: Per-agent revenue

### API Keys (Auth for most)
POST /v1/keys/create: FREE, no auth. Body: {email, tier}
  Returns: api_key (once only), key_id, tier, monthly_limit
  monthly_limit is an abuse CEILING, not prepaid calls: a paid-tier key is debited from
  its prepaid balance per call, and on a `free` tier key every call to a paid endpoint
  still requires x402 payment.
POST /v1/keys/upgrade/{tier}: x402-priced ($29/$99/$299/$999); credits the price 1:1 to the
  key's prepaid balance and sets the tier label (burst limits only)
POST /v1/keys/topup/{usd}: x402-priced at {usd} dollars (minimum 5); credits 1:1
GET /v1/keys/usage: Usage, abuse limit and prepaid balance_usd
GET /v1/usage/summary?period=day|week|month: Aggregated usage
GET /v1/usage/endpoints: Per-endpoint call counts
GET /v1/usage?period=...: Full customer usage analytics

### Audit Trail (Auth Required)
GET /v1/audit/trail?limit=100: Recent audit entries
GET /v1/audit/verify: Hash chain integrity of your own entries
GET /v1/audit/query?entity_id=&from=&to=&limit=&offset=: Filtered audit entries
GET /v1/audit/sanctions?entity_hash=&from=&to=&decision=&limit=&offset=&fmt=json|csv

### Webhooks (Auth Required)
POST /v1/webhooks: Register (body: url, events[]); the URL must be HTTPS. Sent today: sanctions.match.new, identifier.change.new; delivered_events in the response lists which of yours are sent
GET /v1/webhooks: List webhooks
DELETE /v1/webhooks/{webhook_id}: Remove webhook
POST /v1/webhooks/{webhook_id}/test: Send test event

### Certificates & Providers (issue/revoke are admin-only, not listed here)
GET /v1/certificate/{hash}: Verify certificate (PUBLIC)
POST /v1/providers/register: Register validation provider
GET /v1/providers: List providers
GET /v1/providers/{provider_id}: Get provider

### GDPR & Data Lifecycle (Auth Required)
DELETE /v1/data/purge: Erasure (body: entity_name)
GET /v1/data/retention: Retention policies

### Legal (PUBLIC, No Auth)
GET /v1/legal: All legal documents
GET /v1/legal/privacy: Privacy policy
GET /v1/legal/terms: Terms of service
GET /v1/legal/dpa: Data Processing Agreement

### Score History & Feedback (Auth Required)
GET /v1/scores/{subject}/history?limit=50: Trust score trend
POST /v1/feedback: Submit accuracy feedback
  Body: subject, feedback_type, comment?

### Transparency (PUBLIC, No Auth)
GET /v1/self-verify: Limitguard's own trust score
GET /v1/methodology: Methodology of Limitguard's own self-verification score
GET /v1/self-verify/signals: Trust signals list

### Sales & Discovery (Auth Required)
GET /v1/sales/listing: Bazaar service listing
GET /v1/sales/recommendations?current_endpoint=...&trust_score=?: Cross-sell

### Discovery (PUBLIC, Free)
GET /.well-known/x402.json: x402 Bazaar service listing
GET /.well-known/agent.json: A2A Agent Card
GET /.well-known/agent-card.json: A2A Agent Card (v0.3+ name)
GET /.well-known/mcp.json: MCP tool manifest
GET /.well-known/security.txt: Security contact (RFC 9116)
GET /llms.txt: This concise summary
GET /llms-full.txt: This full reference
GET /: Discovery index (links to x402, Agent Card, mcp.json, llms.txt, spec, docs, MCP, A2A, free key)

### A2A JSON-RPC (Key for priced skills)
POST /a2a: A2A v0.3.0, JSON-RPC 2.0: message/send, tasks/get, tasks/cancel. message/send with data part {"skill": "lead_verify"|"agent_check"|"entity_check"|"risk_score"|"kyb_check"|"verify_wallet"|"wallet_sanctions"|"light_check"|"seller_preflight", "input": <REST body>} runs that REST route at its account price (prepaid balance of a paid-tier X-API-Key; a sandbox key gets what the REST route gives it; an x402 payment pays the agent price) and returns a completed Task whose artifact is the REST JSON. Errors: -32602 bad skill/input (Pydantic errors in data), -32020 payment required (data.price_usdc, data.pay_at), -32001 task not found, -32002 task not cancelable. Tasks kept 24 h per key. No streaming or push notifications.
A2A 1.0 (same URL): header A2A-Version: 1.0 (or ?A2A-Version=1.0; no header means 0.3, an unsupported version is -32009). Methods: SendMessage, GetTask, CancelTask, ListTasks (X-API-Key required; contextId, status, pageSize 1-100, pageToken, statusTimestampAfter, includeArtifacts). Parts: text, or data plus mediaType "application/json", no kind. Roles ROLE_USER and ROLE_AGENT, task states TASK_STATE_*. SendMessage returns {"task": Task} or {"message": Message}. Errors keep their codes; error.data is a list whose first item is a google.rpc.ErrorInfo (reason, domain, metadata). The extensions header is A2A-Extensions (X-A2A-Extensions also works). The 1.0 Agent Card is /.well-known/agent-card.json requested with A2A-Version: 1.0. A signed card verifies against the ES256 key at GET /.well-known/agent-card-jwks.json.
x402 inside A2A, no key (a2a-x402 v0.2 extension, optional): send the header X-A2A-Extensions: https://github.com/google-agentic-commerce/a2a-x402/blob/main/spec/v0.2 with a priced skill call and no key; the result is a Task in state input-required whose status.message.metadata["x402.payment.required"] is the REST route's x402 PaymentRequired (x402Version 2, accepts in USDC on Base and Solana). Sign one accepts entry, then send message/send with {"taskId": <task id>, "metadata": {"x402.payment.status": "payment-submitted", "x402.payment.payload": <PaymentPayload>}} in the message. The payload is checked against the requirements quoted for that task, then verified and settled exactly as on the REST route (settled only when the call succeeds). Result: the completed Task, metadata "x402.payment.status": "payment-completed" and "x402.payment.receipts" [{"success": true, "transaction", "network", "payer"}]. Failure: state failed, "x402.payment.status": "payment-failed", "x402.payment.error" one of INSUFFICIENT_FUNDS, INVALID_SIGNATURE, EXPIRED_PAYMENT, DUPLICATE_NONCE, NETWORK_MISMATCH, INVALID_AMOUNT, SETTLEMENT_FAILED. "x402.payment.status": "payment-rejected" (or tasks/cancel) cancels the task. Each quote is paid once; tasks/get finds these tasks by id with no key.

### Health (PUBLIC, Free)
GET /health: Status, version, uptime_seconds, sources{}, cache_sizes{}

## Error Responses

HTTP 402: Payment required (x402 body with accepts[])
  extensions.bazaar.info also carries a recovery path:
    recovery.url       → https://api.limitguard.ai/v1/quickstart
    documentation_url  → https://docs.limitguard.ai/x402-protocol?utm_source=api&utm_medium=agent&utm_campaign=docs&utm_content=x402_protocol
    sandbox.curl       → POST https://api.limitguard.ai/v1/keys/create {"email": "...", "tier": "sandbox"} (free, no wallet)
HTTP 404: Not cached (X-Response-Quality: cached, no cached result; body carries errorCode not_cached and
  retry{header, value: fresh, price_usdc, price_raw}; no data source was called)
HTTP 410: Gone (GET /v1/compliance/report/{entity_id}, withdrawn in #426; errorCode compliance_report_unavailable;
  unpriced, nothing charged; body lists alternatives[])
HTTP 422: Validation error ({type, title, status, detail[{field, message}]})
HTTP 429: Rate limit exceeded (sandbox: 10 req/min)
HTTP 500: Internal error ({type, title, status, detail})

## Key Facts for AI Agents

- leads/verify is the main check for NL and BE leads; entity/check returns a score, cluster and recommendation for any company
- Use risk/score for fast, cheap screening (2 sources, < 100ms typical)
- All /.well-known/* discovery endpoints are free and cacheable
- Nonces are single-use (10-minute TTL in Redis)
- Paid-tier API keys are debited from a prepaid balance at the account prices; an x402 payment pays the agent prices. A `free` key holds no balance and pays x402 per call at the agent price, same as an anonymous caller
- Sandbox: same API, mock data, no cost on endpoints that serve a mock; priced endpoints without one charge like `free`, 10 req/min limit
- Both PAYMENT-SIGNATURE (v2) and X-PAYMENT (legacy) headers are accepted; the payload format is detected by shape, not header name