Catalog payment-response validity

What it measures

The percentage of mapper catalog endpoints with payment_required_valid=1. The live endpoints schema contains payment_required_valid; it does not contain a strict_v2 column.

How it is produced

The method checks the schema, counts all endpoint rows by the persisted validity flag, then decomposes valid rows by inferred provider and parsed host. The parser implementation is inspected alongside the queries.

Schema check

PRAGMA table_info(endpoints);

Canonical query

SELECT
  COUNT(*) AS endpoints,
  SUM(payment_required_valid=1) AS valid,
  SUM(payment_required_valid=0) AS invalid,
  ROUND(100.0 * SUM(payment_required_valid=1) / COUNT(*), 6) AS valid_pct
FROM endpoints;

Provider decomposition

SELECT
  COALESCE(NULLIF(provider_inferred,''),'(blank)') AS provider,
  COUNT(*) AS endpoints,
  SUM(payment_required_valid=1) AS valid,
  ROUND(100.0 * SUM(payment_required_valid=1) / (
    SELECT SUM(payment_required_valid=1) FROM endpoints
  ), 6) AS pct_of_valid,
  ROUND(100.0 * SUM(payment_required_valid=1) / COUNT(*), 6) AS provider_valid_pct
FROM endpoints
GROUP BY provider
ORDER BY valid DESC, endpoints DESC
LIMIT 20;

Host decomposition

WITH parsed AS (
  SELECT
    id,
    url,
    payment_required_valid,
    CASE WHEN instr(url,'://')>0 THEN substr(url,instr(url,'://')+3) ELSE url END AS rest
  FROM endpoints
),
hosts AS (
  SELECT
    lower(CASE WHEN instr(rest,'/')>0 THEN substr(rest,1,instr(rest,'/')-1) ELSE rest END) AS host,
    payment_required_valid
  FROM parsed
)
SELECT
  COALESCE(NULLIF(host,''),'(blank)') AS host,
  COUNT(*) AS endpoints,
  SUM(payment_required_valid=1) AS valid,
  ROUND(100.0 * SUM(payment_required_valid=1) / (
    SELECT SUM(payment_required_valid=1) FROM endpoints
  ), 6) AS pct_of_valid
FROM hosts
GROUP BY host
ORDER BY valid DESC, endpoints DESC
LIMIT 20;

Parser inspection

sed -n '450,530p' mapper.py

Limits and assumptions

• payment_required_valid is produced by hardcoded parsing logic for 402 responses: the Payment-Required header, JSON body accepts or paymentRequirements, and legacy x-payment-required.
• There is no persisted strict-v2 field in this schema.
• The metric depends on a persisted mapper catalog and parser heuristics. It can be incomplete if discovery misses endpoints or the parser does not recognize valid x402 variants.
• The deterministic replacement defines a canonical payment-valid probe and stores per-probe evidence in endpoint_history. It keeps current-v2 and legacy-valid as separate states and derives current validity from the latest probe rather than from a mutable catalog bit.

How to refute this

1. Re-run the canonical SQL and get a different valid count or denominator.
2. Re-probe a statistically meaningful sample and show payment_required_valid disagrees with fresh 402 evidence.
3. Add a strict-v2 parser and show the current field either overcounts legacy/nonstandard responses or undercounts valid v2 endpoints.

Last validated

2026-06-08