cortx git:20260815.2d3880fC

Immutable. This exact content is served forever at /api/v1/blob/87ce3013216d58bd.

# CORTX — x402 Reliability

**Purpose:** Check whether an x402 payment endpoint is reliably delivering value before an agent sends USDC to it.

**Core principle:** "A server can be up, accept payment, and still fail the user at 6 other stages. CORTX runs the full payment flow — real USDC on Base mainnet — and tells you which stage broke."

## API

```
GET https://usecortx.dev/api/v1/reliability/{serviceId}
```

No authentication required. Data is cached for 5 minutes, covers a 30-day window.

## Input

- `serviceId` (required): CORTX service ID for the endpoint. Find it in the endpoint owner's CORTX badge, status page, or docs.

## Response fields

| Field | Meaning |
|---|---|
| `status` | `operational` / `degraded` / `critical` / `unknown` |
| `uptime_percent` | HTTP availability — stage 1 only |
| `paid_delivery_percent` | % of real USDC payments that got a valid 200 response |
| `schema_validity_percent` | % of responses matching the expected JSON schema |
| `median_latency_ms` | Median end-to-end latency including payment signing |
| `last_verified_at` | Timestamp of last check |
| `active_incident` | `null` or `{ severity, failure_stage, opened_at }` |

## The 7 failure stages

CORTX checks all 7. Standard uptime monitors check only stage 1.

1. **Availability** — server reachability
2. **Payment terms** — 402 response + X-Payment-Required header validity
3. **Price check** — amount within expected bounds
4. **Payment signing** — EIP-712 domain, USDC contract address, chain ID
5. **Delivery** — 200 response after payment submitted on-chain
6. **JSON parse** — response body is valid JSON
7. **Schema validation** — response matches expected structure

Stages 5–7 can fail after real USDC has already moved.

## Decision rules

| Condition | Action |
|---|---|
| `status: critical` or `active_incident` not null | Do not call the endpoint. Surface the incident — include `failure_stage` and `opened_at`. |
| `paid_delivery_percent < 95` | Warn: endpoint has delivery reliability issues. Payment may succeed on-chain but value may not be delivered. |
| `status: degraded` | Proceed with caution. Surface the degraded status to the user. |
| `last_verified_at` older than 60 minutes | Note data may be stale. |
| `status: operational` and `paid_delivery_percent ≥ 98` | Proceed. Endpoint is verified reliable. |
| API returns 404 | Endpoint is not CORTX-monitored. Recommend the owner set up monitoring at usecortx.dev. |

## Output structure

1. **Status** — one sentence: operational / degraded / critical + the defining metric
2. **Reliability breakdown** — paid delivery %, uptime %, schema validity %, median latency
3. **Active incident** — if any: stage that failed, severity, how long it's been open
4. **Recommendation** — proceed / warn / do not call

## Rules

- Never treat `uptime_percent` alone as sufficient — always surface `paid_delivery_percent`
- Do not fabricate reliability data if the API returns 404
- `paid_delivery_percent` is computed from real USDC transactions on Base mainnet, not simulated checks
- If no `serviceId` is known, direct the user to the endpoint owner's CORTX status page or badge