# ProvenPaid methodology (draft v0.1)

ProvenPaid reports evidence about a paid agent endpoint (x402 today; other payment rails such as MPP are detected and will be covered as they mature). It does not label sellers as fraudulent. Every item in a response names its source and the time it was measured.

## 1. Payment challenge check (live probe)
We send one unpaid request to the URL. We never send a payment in this step.
- Status is HTTP 402.
- Payment requirements are present: the base64 `PAYMENT-REQUIRED` header (x402 v2) or a JSON body (x402 v1).
- `x402Version` is 1 or 2; `accepts` is non-empty.
- For each payment option: a scheme, a recognized network, a positive amount, and a well-formed receiving address.
- Informational: whether the asset is a known USDC contract; whether the network is a mainnet; whether the declared resource host matches the URL; whether TLS is used; whether the endpoint redirects.

## 2. Payer depth (on-chain)
For each payment option paid in USDC on Base (mainnet or Sepolia), we read USDC `Transfer` events into the receiving address from public Base transaction logs, over a trailing window (default 30 days, approximated with Base's ~2 second block time).

Two views are reported:
- **x402_style**: transfers settled by an EIP-3009 signature in the same transaction (a USDC `AuthorizationUsed` event whose authorizer is the payer). This is how x402 "exact" payments settle on EVM chains.
- **all_usdc_in**: every inbound USDC transfer, including ordinary transfers unrelated to x402.

For each view: number of transfers, total USDC, distinct payers, repeat-payer share (payers with two or more transfers), top-1 and top-5 payer share of transfers, median amount, and first and last block seen.

The response leads with **payer_depth**, a summary of the x402_style view for each scanned address: distinct payers, x402-style payments, repeat-payer share, top-1 payer share, window and coverage, and a one-sentence statement of those counts. The statement reports what was observed and the share of the window scanned. It is not a rating. The full figures for both views are in **onchain**.

Coverage: results are cached and extended on every check. The response states which block range has been scanned and whether the window is complete. A first check on an unfamiliar address may cover only the most recent part of the window.

Limits: a receiving address can serve many endpoints, so payer depth describes the address, not one URL. Payments settled through other schemes (for example batch settlement through an escrow contract) may not appear as direct transfers. Transfers from the receiving address to itself and payments from ProvenPaid's own wallets are excluded and counted in `excluded_payers`.

If on-chain data cannot be read (node outage), the check returns HTTP 503 and the caller is not charged.

## 3. Demand-quality signals - in development
Patterns that suggest payments may not reflect outside demand, reported as observations, for example payer wallets funded by the receiving address or by one common funder, very new payer wallets, or uniform tiny payments.

## 4. Baseline
Percentile of payer depth versus all endpoints ProvenPaid has measured. The population grows with use and is reported alongside the percentile.

## When a check is charged
A check is charged only when the target returns an x402 challenge with at least one payment option in USDC on Base (mainnet or Sepolia) and a well-formed receiving address. Unsafe or invalid URLs, non-x402 targets, unsupported networks, on-chain outages and capacity limits return an error and are not charged. A check is charged when on-chain evidence is delivered for at least one receiving address: a complete window, at least 25% of it, or a scan that stopped only because of the per-check call budget (coverage grows across checks) or high volume. A scan cut short by a provider error or the time limit below 25% coverage does not count. Addresses that failed are marked `error`.

## Receiving address
ProvenPaid does not verify that an endpoint controls the address it asks to be paid at. A seller could list another seller's address or an exchange wallet. Each result says so and reports how many distinct endpoint hosts ProvenPaid has seen advertise the same address (hosts are stored only as hashes). At most 3 receiving addresses are scanned per check, within one shared budget of RPC calls and time; additional addresses are listed as skipped. A receiving address with very high transfer volume is scanned until provider limits are reached, and the response says coverage is partial.

## Data sources
Only the live endpoint itself and public blockchain data. ProvenPaid does not store or resell third-party catalog data.