For providers

This guide is for teams that sell API access through x402 on Base. It explains how an endpoint enters the scoring set, what a Probe needs to see in your 402 response, how price integrity is measured from escrow settlements, what the optional VIGIL Verified badge is, and the usual reasons a check fails.

How an endpoint gets scored

Watchers run Probes that call paid x402 endpoints continuously. Each probe result is published onchain as an Attestation. Attestations are aggregated into an Endpoint Score from 0 to 100 and written to the ERC-8004 reputation registry. See Checks and scoring for the aggregation rules.

An endpoint enters the probe set in one of two ways:

• Observed. Any endpoint that receives payments through the VIGIL Facilitator is added to the probe set automatically. Probes begin calling it on the reference cadence of every 60 s from at least 3 regions.
• Registered. A provider can register an endpoint before any agent has used it. Registration is a signed request to the registration API: the request body names the endpoint URL and the provider's ERC-8004 agent identifier, and is signed by the key that controls that identifier. This is how VIGIL links the endpoint to a provider identity. See ERC-8004 integration.

POST /v1/endpoints HTTP/1.1
Host: api.vigil.example
Content-Type: application/json
X-Vigil-Signature: 0x...   # EIP-191 signature over the body by the provider key

{
  "endpoint": "https://api.weather.example/v1/forecast",
  "agentId": "8004:base:1234",
  "regions": ["auto"]
}

Each probe pays the endpoint's quoted price, so Probes are paying customers. A score becomes public after 25 attestations from 5 distinct Watchers, which at the reference cadence takes under an hour for an endpoint that stays up.

What a Probe expects from a 402 response

A Probe issues an unpaid request and reads your 402 response before deciding whether it can pay. It needs four things from that response: the price, a way to validate the body, size bounds, and a hint about how long a response should take. All of these are read from headers. The header names below are reference names used by the Probe and the Facilitator; they are not part of the x402 specification and may change before release.

HTTP/1.1 402 Payment Required
Content-Type: application/json
X-Payment-Required: x402; network=base; asset=USDC; payTo=0x0000000000000000000000000000000000000000
X-Payment-Price: 0.02
X-Payment-Schema: https://api.weather.example/schemas/forecast.json
X-Payment-Max-Bytes: 65536
X-Payment-Deadline-Hint: 5000

{
  "error": "payment_required",
  "price": "0.02",
  "currency": "USDC"
}

The payTo address above is a placeholder; contracts are not deployed.

A 402 response that lacks a price or a parseable payment header is recorded as a failed uptime check, because no agent could pay for it either.

How price integrity is measured

Price integrity is one of the four checks and carries a weight of 25 in the score. It is not measured from what your API says; it is measured from what the escrow settles.

When a payment routes through the Facilitator, the escrow records the quoted price from your 402 response at the Quoted state. When the response is checked and released, the Facilitator records the amount actually charged. The two are compared:

• Charged more than quoted: failure. The agent paid more than it agreed to.
• Charged less than quoted: failure. A quote that overstates the price is still a wrong quote, and inconsistent pricing is a signal that the endpoint's terms are not stable.
• Charged exactly the quote: pass.

Both directions count. There is no tolerance band; change the quote in the 402 response before changing the charge.

VIGIL Verified

VIGIL Verified is an optional badge for providers. It is displayed with the score in the read API and can be shown on your own site.

• Eligibility. The endpoint's score must be 90 or above (the Reliable band) and must have stayed at or above 90 for the last 30 days without interruption.
• Subscription. The badge is a paid subscription. Subscription revenue is part of protocol fees; 50% goes to Watchers and 50% to buyback-and-burn of $VIGIL. $VIGIL is not launched.
• Revocation. If the score drops below 90, the badge is revoked automatically at the next score update. It returns once the score has been at or above 90 for 30 days again. The subscription is not refunded for the revoked period.
• No effect on scoring. The badge is read from the score; it never feeds into it. Watchers, Probes and the aggregator do not know whether an endpoint is subscribed.

Subscription pricing is not set. It will be published on x.com/VigilOnBase when the service is live.

Common causes of failed checks

For weights and decay see Checks and scoring; for who runs the Probes see Watchers.