CORTX monitors every x402 endpoint on two tiers: a free lightweight ping every 5 minutes confirms reachability, and a full paid verification at a configured interval runs a real end-to-end transaction through the 7-stage pipeline below, recording evidence at each stage.
availabilityAvailabilityCORTX sends an HTTP POST (with test payload) to the endpoint URL. A 402 Payment Required response is expected — it signals the endpoint is alive and requires payment. If POST does not return 402, CORTX retries with GET to support endpoints that gate on GET requests. Any other non-402 response (connection refused, 500, timeout) fails the check here.
payment_termsPayment TermsCORTX parses the 402 response body for x402 payment terms (network, asset, amount, recipient address). If the body is not a valid x402 envelope, the X-Payment-Required header is tried as a fallback. Missing, malformed, or unparseable payment terms fail this stage.
price_checkPrice CheckThe parsed price is compared against the service's configured expected price and max price bounds. Prices exceeding max price fail this stage to protect the monitoring wallet. Price deviations from expected are recorded.
paymentPaymentReal USDCCORTX uses the x402/client package to sign an EIP-3009 transferWithAuthorization — a gasless USDC transfer on Base. The monitoring wallet's private key signs the EIP-712 message, and the resulting signature is encoded into an X-Payment header. Real USDC is spent.
deliveryDeliveryThe original request is re-sent with the X-Payment header. CORTX expects a 200 OK response. Any other status — including a second 402 — produces a critical failure: payment was sent but content was not delivered.
json_parseJSON ParseThe response body (capped at 1 MB) is parsed as valid JSON. Unparseable responses fail here. This stage runs on every check regardless of whether a schema is configured.
schema_validationSchema ValidationIf an expected JSON Schema is configured for the service, AJV validates the parsed response against it. Any violation — missing required field, wrong type, disallowed additional property — fails the check. This stage is skipped when no schema is configured.
passed ÷ (passed + failed) over the windowCounts checks with status "passed" divided by all eligible checks (passed + failed). Infrastructure errors (status "error") are excluded from both numerator and denominator — they represent CORTX monitoring issues, not endpoint failures.
checks where payment AND delivery both passed ÷ checks that reached both stagesOnly counts checks that reached both the payment stage and the delivery stage. A check that failed at payment_terms never enters this denominator. This metric answers: "Of checks that attempted a full payment cycle, how many resulted in successful delivery?"
checks where schema_validation passed ÷ checks that reached schema_validationCounts only checks that reached the schema_validation stage (i.e., that had a schema configured and a parseable JSON response). Checks without a configured schema are excluded entirely from this metric.
median of all full round-trip times (ms) over the windowFull round-trip duration including the payment signing step. For even-length arrays, the median is the average of the two middle values — not a truncated index. Infrastructure errors are excluded. Null when no latency data is available in the window.
checks with status "error" — excluded from all metricsChecks that failed due to CORTX monitoring infrastructure issues: network timeouts, RPC failures, internal errors. These do not open incidents and are excluded from all reliability metric calculations. Only "failed" check results affect uptime and incident state.
CORTX verifies technical delivery and configured response structure. It does not verify the factual accuracy, safety, or quality of arbitrary API outputs.
Specifically, CORTX confirms that an endpoint: (1) responds to an HTTP request with a 402 status, (2) provides valid x402 payment terms, (3) accepts a signed payment, (4) delivers a 200 response, (5) returns parseable JSON, and optionally (6) matches a configured JSON Schema. CORTX does not evaluate the truthfulness, helpfulness, or appropriateness of the response content.
The 7-stage pipeline above is defined as an open specification. Anyone can implement it, propose changes, or build tooling that produces conforming evidence records — no dependency on CORTX required.
danbuildss/x402-reliability-spec