# ProvenPaid

Evidence before you pay. Independent evidence for agent payments.

A valid x402 paywall shows that an endpoint can take payment. It does not show that anyone pays it. ProvenPaid answers that second question from public Base data: how many distinct wallets paid the endpoint's receiving address in the last 30 days, how many came back, and how much of the paying a few wallets account for. It also checks the payment challenge, but payer depth is the part nobody else measures independently.

## When to use it
Call ProvenPaid before your agent pays an x402 endpoint it has not used before, for example one found in a directory, a link or a search result. You get evidence to decide with, not a verdict.

## How to call it
`GET https://api.provenpaid.com/v1/check?url=<endpoint URL>`

The route is paid over x402: the first request returns HTTP 402 with payment requirements (USDC on Base). Any x402 client pays and retries automatically. Price: see the 402 challenge.

## What you get (JSON)
A worked example, written out for people: https://api.provenpaid.com/sample

- **payer_depth** (first): the headline for each receiving address. A one-line statement such as "14 distinct payers made 120 x402-style USDC payments to this receiving address in the last 30 days", plus distinct payers, payments, repeat-payer share, top-payer share and how much of the window was scanned.
- **onchain**: the full detail behind payer_depth. Public Base data for the receiving address over the last 30 days: both views (x402-style and all inbound USDC), totals, median payment, block range, coverage and source.
- **probe**: one unpaid request to the endpoint. Is its x402 payment challenge valid (v1 or v2)? Which network, price and receiving address? Which payment rails does it advertise (x402, MPP)?
- Every section names its source and the time it was measured.

## Free checks for integrations
Wallets, CLIs and agent frameworks that run the check before a first payment can use `GET /v1/free-check?url=<endpoint URL>`. Each wallet gets 10 delivered checks free; the wallet needs no funds, a fresh key works. Sign this exact message with the wallet (EIP-191 personal_sign), using the URL you pass and the current unix time:

```
ProvenPaid free check
url: <endpoint URL>
timestamp: <unix seconds>
```

Send it as headers `X-ProvenPaid-Address`, `X-ProvenPaid-Timestamp` and `X-ProvenPaid-Signature`. Each signature works once and must be under 5 minutes old. Only delivered checks count. After 10, use the paid route. A daily cap applies across all free users.

## You are not charged when
- the URL is invalid, not public, or unsafe to contact (HTTP 422, `invalid_target`);
- the URL does not return an x402 payment challenge (HTTP 422, `not_x402`);
- none of its payment options is USDC on Base with a well-formed receiving address (HTTP 422, `unsupported_network`);
- on-chain data cannot be read at that moment, or the service is busy (HTTP 503).

Each payment authorization can be used for one check. If a check is not charged, sign a new authorization to try again. Authorizations must stay valid for at least 120 seconds. A payer with more than 5 uncharged checks in an hour is paused for the rest of that hour.

If on-chain evidence is delivered for at least one receiving address, the check is charged; addresses that could not be read are marked `error`. A scan cut short by an outage with under 25% of the window covered is not charged.

## Limits
- A receiving address can serve several endpoints, so on-chain figures describe the address, not one URL.
- ProvenPaid does not verify that an endpoint controls its receiving address; each result reports how many distinct endpoint hosts have advertised the same address.
- Payments settled through other schemes may not appear as direct transfers.
- ProvenPaid reports evidence and its methodology. It does not label sellers.

## What we record about you
Hourly counts of requests by outcome (asked the price, paid, not charged), a coarse client type from the User-Agent (for example "python-httpx" or "browser"), the browser's language setting (a language code only) when our CDN supplies one, a two-letter country code, and for browser page views the kind of site that linked to the page, reduced to a short list of names such as "linkedin" or "other". No IP addresses, URLs you check, or payment details. Payments themselves are public on-chain.

Chinese version / 中文版: https://api.provenpaid.com/zh

## More
- All market notes: https://api.provenpaid.com/notes
- Market note no. 3, Main Street: More Lookouts Than Miners (October 2026): https://api.provenpaid.com/notes/main-street
- Market note no. 2, The Assay: Who Actually Pays x402 Sellers (October 2026): https://api.provenpaid.com/notes/who-actually-pays
- Market note, State of x402 Demand (October 2026): https://api.provenpaid.com/notes/state-of-x402-demand
- Methodology: https://api.provenpaid.com/methodology
- Machine-readable API description: https://api.provenpaid.com/openapi.json
- Health: https://api.provenpaid.com/v1/health
