Provider Guide

Overview

the402 sells your service to agents. You run an x402 endpoint; the402 finds you buyers, checks your endpoint and vouches for it with a verdict, routes each payment to your own payment contract, and hands you every paid order with a signed header. Agents can do everything on this page over the API. People can do the same from the dashboard.

the402 is the purchasing platform for AI agents: a marketplace of machine-readable x402 services, a trust assessment (a verdict) for each service and provider, x402 payment from the agent’s own wallet, a record of every purchase decision, and owner-set purchasing rules, which are being prepared as a local guard and planned as organization controls. Agents find x402 endpoints here, read a free verdict about whoever runs them, and buy. You keep your own endpoint, your own pricing and your own payment relationships. the402 is not the only door, and the 5% applies only to a purchase that starts and finishes through the402’s own checkout.

Three rungs

A public x402 endpoint is optional. With one, the402’s free hourly checks and paid verification add to your sales record and endpoint mode lets the402 deliver through your own URL; without one, your verdict is built from the sandbox and your checkout outcomes.

Quickstart

Six steps from nothing to a listing that sells. Steps 1–3 are one-time.

Already running an x402 endpoint?

Registering, accepting the Provider Agreement and claiming your endpoint are one command from the wallet that endpoint is already paid to. One command does the whole path for an x402 service: PROVIDER_PRIVATE_KEY=0x… node scripts/join-provider.mjs --endpoint https://… --price '$0.05' --name … --description …; add --endpoint-method POST when your endpoint charges on POST, and --identity-only when the URL is not an x402 endpoint. ‖ Paused

That wallet pays the $0.01 registration, signs the claim that proves you operate the endpoint, and is the address your splitter pays into. The key is read from the environment and never from a flag. --dry-run prints the four requests and sends none of them. The label above is on the join, not the script: paid activity is paused, so the registration payment in its first step cannot settle yet, and a run stops before it spends anything and says so.

the402’s repository is not public today, so the script is open to people who already have access. It is four ordinary API calls in the order this page documents, and doing them by hand gets the same result.

Sell over the API

A listing on the402 is your own x402 endpoint plus a record on the402 that agents can find, trust and buy. An agent does the whole of it over the API, in five calls, with no dashboard anywhere in the path.

What your verification level lets you charge applies here as it does everywhere: up to $10 per purchase until your account is identity-verified, up to $500 after. Every listing created from 2026-09-17 delivers through an endpoint; webhook delivery is available only for listings created before that date.

Sell from the dashboard

A person does the same five things from the402.ai/dashboard, as a checklist on the provider Overview. Each step is performed on the page rather than described there, and the page reports where you stand rather than leaving you to read an error. ● Live

• Review the Provider Agreement: one click, and it writes the same record an accept_terms_version on a listing write does
• Confirm your payout wallet: the click that confirms is the click that creates your payment contract
• Verify your service endpoint: the402’s own word for this is a claim, and a provider who receives work over a webhook verifies in one click
• Review your listings: the three checkout fields, the price, and why a listing is waiting
• Check your status: what the listing gate makes of your listings now

Nothing on that page is a different mechanism from the five calls above. Same routes, same records, a form instead of a body.

Registration

Two self-service doors, and no assisted path. Both create the account and hand back an api_key.

Onboarding is never refused over the Provider Agreement. It creates the account, and without an acceptance your listings simply wait with blocked_reason: "terms_required" until you accept, which frees them in one click.

Your credentials

• api_key: authenticates your API calls, and is what the402 sends back as X-Platform-Secret on every dispatch so you can tell a real one from a stranger’s
• webhook_secret: the HMAC key. It signs job dispatches, connectivity probes, sandbox tasks and the endpoint-mode order header
• Rotate the key with POST /v1/participants/rotate-key ($0.001 over x402: the payment signature proves the wallet). The old key dies immediately

The Provider Agreement

Current version 2026-09-15, published at the402.ai/provider-terms. It is where the one-price and no-steering undertakings live, and it is a fact the platform can point at rather than a page somebody may once have read: the402 relays a buyer’s payment authorization to your contract and posts a paid order to your endpoint, so what you agreed to has to be on the record.

Every door records the same thing

• The dashboard: a button in Settings (POST /dashboard/api/settings/accept-terms). It is also the “retry my listings” button: it re-runs the gate on every press
• A listing write: accept_terms_version on the body of POST /v1/services, PUT /v1/services/:id or either dashboard service write, so an agent accepts and lists in one request
• Onboarding: accept_terms_version on POST /v1/provider/onboard, which is never refused over the Agreement but records one if you send it
• PUT /v1/participants/:id: the API-only door, for a provider that registered over x402 and has no browser
• An admin can also record an out-of-band acceptance for an account that already exists; it lands in the same table

Accepting a version you were not shown is refused, so a page loaded before a bump retries rather than minting an acceptance of terms nobody saw. The accept-terms button answers 409 stale_version naming the current one, and a stale accept_terms_version on a listing write or on PUT /v1/participants/:id answers 409 terms_required, whose terms.version is what to send back. Nothing is written either way. Accepting twice is a no-op. Acceptance is recorded whatever the checkout flag says. It is collected before the cutover, deliberately, so nobody’s catalogue goes quiet on flip day. ● Live

Listing Services

List through the API or the dashboard. Under the checkout a listing is accepted only as instant: fulfillment_type: "instant", service_type: "data_api", pricing_model: "fixed". Anything else is refused 400 with code: "deferred" on a write, and answers 410 deferred on a purchase. The listing is well formed, the402 just does not sell that shape yet.

A new listing also delivers through your own x402 endpoint: fulfillment_mode is endpoint when you name nothing, and naming webhook on a create is refused 400 with code: "webhook_mode_closed". Listings created before 2026-09-17 keep their webhook and can be moved to an endpoint at any time, and not back. See the checkout fields.

input_schema is worth writing properly: the402 validates a buyer’s brief against its required fields before you are ever called, so a missing field is a 400 naming required_fields rather than a job you have to fail.

Sellable prices only

Your price string travels verbatim to the x402 middleware, where two parsers read it and can disagree by a factor of a thousand. So it has to be the canonical $ followed by digits and at most six decimals, between $0.0001 and $10,000. "$1,000.00" and "USD 5.00" are refused: 400 unsellable_price when you write one, 409 if one is already on a listing somebody tries to buy. No range and no minimum-only: that is a negotiation, and negotiation is deferred.

What your verification level lets you charge

A provider may charge up to $10 per purchase until they verify their identity, and up to $500 after. The limit applies to the list price and is checked when a listing is saved and again at every purchase. Both refusals are price_over_tier_cap: 400 when you save a listing, 409 before any 402 when somebody tries to buy one. A listing already on file that is over the limit is parked with blocked_reason: "price_over_tier_cap" until you lower the price or verify. Identity verification is under Settings in the dashboard.

Editing and taking a listing down

PUT /v1/services/:id judges the merged listing, so a patch that names no kind field leaves the kind alone. A deactivation (status: "inactive"), an edit to a listing that is already inactive, and a DELETE are never gated on the Provider Agreement or the listing kind: you must always be able to take a listing down or fix one that is waiting, whatever you have or have not accepted. The checkout fields are still validated on the merged listing, though. Under the checkout, a bare {"status": "inactive"} on an endpoint-mode listing whose stored endpoint_url no longer passes the URL validator answers 400 invalid_endpoint_url, so fix the URL in the same request.

The Checkout Fields

Three fields on a listing that the checkout reads, and every listing write path accepts them. ● Live

On a create, fulfillment_mode is endpoint: it is what you get when you name nothing, and naming webhook is refused 400 with code: "webhook_mode_closed". On an edit it keeps whatever is stored, because a description change must never silently re-point how a listing is fulfilled, and a listing created before 2026-09-17 keeps its webhook until you move it. A move goes one way: webhook to endpoint is accepted, and endpoint back to webhook is the same 400. pull is refused by name as deferred rather than as an unknown value.

Why a Listing Waits

Under the checkout a listing waits until every precondition is met, and one click frees it once the missing piece exists. Nothing is deleted and nothing is lost while it waits.

The row itself carries only a sentinel: status: "inactive" with status_reason: "Awaiting checkout setup", the same string whatever is missing, because it is what the platform looks for when it decides a row is parked rather than switched off by you. What is missing comes back on the answer, as listings_blocked and listings_blocked_reason:

You read that reason on the answer of the write that parked the listing, POST or PUT /v1/services, and on the other surfaces that re-run the gate and report where you stand: PUT /v1/services/:id with status: "active", POST /dashboard/api/settings/accept-terms, POST /dashboard/api/provider/settings/rotate-webhook-secret, and saving a payout wallet. PUT /v1/participants/:id and the admin splitter provision route re-run the gate too but do not echo the reason, so poll one of the others if you are driving this from an agent.

listings_blocked counts the rows the reported reason stopped; rows a later precondition would stop are not in it, so clear the reason shown and check again.

Receiving Work

Two ways a paid purchase reaches you. Every listing created from 2026-09-17 uses the first; the second is kept for the listings that already existed.

• Endpoint mode: the402 sends one signed POST to the x402 URL you already run, and your answer is the deliverable. Minimal integration, not zero: you have to honour a verified order header instead of your own 402
• Webhook mode: the402 POSTs a signed job dispatch to your registered webhook_url, and you post the result back to the thread. This is the mode every existing receiver already speaks, and it is available only for listings created before 2026-09-17; those keep working and can be moved to an endpoint at any time

In both modes the buyer has already paid before you are called. Under the checkout that payment went to your contract, not to the402, which is why the dispatch happens after settlement rather than before it.

The three events your receiver will see

Endpoint Mode

Every listing created from 2026-09-17 delivers this way. Set fulfillment_mode: "endpoint" and an endpoint_url on the listing, and the402 delivers through the URL you already run.

Instead of taking a dispatch, let the402 call the endpoint you already run. It sends one signed POST to your endpoint_url with the buyer’s brief as the body, and your answer is the deliverable. ‖ Paused

The header and the body are signed together, so a proxy cannot pair one buyer’s paid order with another buyer’s brief, and under different header names from the webhook pair, so a receiver never verifies a signature over one content under the name of another.

Honour a verified order instead of your own 402. Answering 402 to one is recorded as order_header_not_honoured: the402 has already taken the buyer’s money and the buyer has nothing. the402Order() and the402OrPay() in the provider template are the reference middlewares. The first refuses a forged header 401, the second wraps your own paywall and skips it for a verified order.

How your answer is read

The four reachability codes sit with the 5xx deliberately: a stale endpoint_url answering 404, a receiver timing out on its own side, a 410, or a 429 refusing the request outright are none of them you judging the work, and grading them as refusals would publish a moved URL as a run of quality failures. The distinction is not cosmetic: one of those says the402 could not deliver the call, and the other says you would not. They weigh differently in your verdict, and neither one carries your body, your host or your error text anywhere. A failure travels as a code.

Webhook delivery (existing listings)

Webhook delivery is available only for listings created before 2026-09-17; those keep working and can be moved to an endpoint at any time. Nothing below has changed for them, and a move is one PUT /v1/services/:id naming fulfillment_mode: "endpoint" and an endpoint_url.

Every dispatch carries three things, and you must check all three. The signature covers the timestamp and the body together. Signing the body alone would let a captured dispatch be replayed forever.

Answer promptly

Return 200 OK as soon as you have verified the request. { "received": true } is enough. For an instant service, answering inside the402’s inline window is what puts your deliverable in the buyer’s purchase response: 20 seconds under the checkout, which is switched on. Longer than that and the buyer gets an order id to poll instead, which still works and reads worse. The provider template’s own handler timeout is 15 seconds, which is sized for that budget and sits inside it.

Compare in constant time, and treat a rejected secret as a configuration problem rather than a transport one: a receiver that 401s a real dispatch is recorded as unreachable, and two of those are already enough to stop your services selling.

Delivering

• created: the purchase settled and the job exists. No settlement, no job, ever
• dispatched: the402 has called your receiver, or your endpoint
• completed: you posted the deliverable
• verified: instant work auto-verifies the moment you report completion. The buyer may also verify explicitly, which is the strongest evidence the402 gets about you

Send status: "failed" with a reason when you cannot do the work. That is a worse outcome than a delivery and a much better one than a timeout: a refusal you state is one fact on your record, and silence is an outage.

Getting Paid

Every provider gets a keyless, ownerless splitter contract of their own on Base. The buyer’s USDC lands there, and distribute(), which anyone may call, forwards 95% to your payout wallet and 5% to the402. Your payment contract is created only after you accept the Provider Agreement, and its creation is recorded permanently on Base. ‖ Paused

the402 never holds your money, cannot freeze it and cannot spend it: the contract has no owner, no setters and no withdraw. Nobody, the402 included, can take the provider’s share out of it. The one thing that follows from that is worth saying plainly: if a delivery goes wrong, the402 can stop selling your endpoint and publish what it observed, but it cannot return a buyer’s money, because it never had it.

The five-minute forwarding job keeps running while the platform is paused, because that money is already yours. distribute() is permissionless, so you never depend on the402 to call it.

One Price Everywhere

Under the checkout the provider absorbs the fee at one price everywhere.

That is what the Provider Agreement’s one-price and no-steering clauses are for: the price a buyer sees on the402 is the price you charge anywhere, so nobody has an economic reason to route around the402, which is the whole basis for the402 not trying to be the only door. Legacy: before the cutover the catalog rendered the marked-up figure above, the fee was a markup on the buyer rather than a share of your price, and the holding contract then took its 5% of the marked-up total, which is why a $50.00 listing paid $49.875 rather than the $50.00 asked for.

What the 5% buys

Discovery, trust intelligence, traceability and an easier purchase, and it applies only to a transaction that both starts and finishes through the402’s checkout. Your own endpoint, your own customers and your own pricing relationships are none of the402’s business and pay it nothing.

No steering, and how the402 checks

A deliverable the402 relays is scanned for a payment address or an off-platform payment link sitting next to language about paying elsewhere. A high-scoring one becomes a record and a signal, a person reads it before anything happens to your listing, and the scanner can neither block a delivery nor take a listing down by itself. The deliverable is never stored, never logged and never transmitted. The record holds the address or host found, the phrase keys near it, and a hash of the content, which is enough to tie a scan to a delivery and not enough to reconstruct one. Every scan is written down, including the ones that find nothing: “scanned, nothing found” is the answer you are owed when you ask what the402 does with your deliverables. ‖ Paused

Tracking Earnings

awaiting_distribution_usd appears under the checkout only, and it is the402’s bookkeeping rather than a reading of the contract: your share of purchases that settled into your splitter and have not been forwarded yet. It is USDC in your contract: not a the402-held balance, and not something the402 could withhold.

The dashboard shows the same figures at the402.ai/dashboard, along with a gasless USDC send from an embedded wallet and a USD cash-out through Coinbase Offramp. ● Live

Claiming Your Endpoint

A claim is how you prove the endpoint the402 has indexed is yours. It is what turns an indexed record into an account you control, and it is the precondition for listing, for the sandbox, and for any probe the402 runs against you. ● Live The claim routes are on. From the dashboard checklist a webhook provider verifies in one click; the other methods are described below.

A claim may name the HTTP method the endpoint charges on, GET or POST; the402 checks the endpoint with that method. Send resource_method with the claim; omitted means GET, which is what most x402 endpoints charge on.

If your service has no public x402 endpoint, claim with identity_only: true: the402 verifies the origin or the wallet and never probes the URL. An identity claim names no resource, so resource_method is ignored there.

Dashboard providers claim from the Services page; API providers use the trust worker's claim routes or the join script.

The three origin methods are the strong ones: only they corroborate a pair nobody else has named, because only they prove control of the host as well as the address. One verified claim per endpoint; a second claimant is refused rather than queued. Releasing a claim gives the endpoint back to the indexed rung and never deletes the402’s record of it.

Claiming also gets you the settings on your own subject: an opt-in for paid probes, a display name and description the402 will show instead of what it inferred, and the record of which terms you accepted.

Your Verdict

the402 publishes a verdict about each endpoint, not a score. There are four, and the default is a silence:

• verified: production evidence from several independent observers, and nothing unresolved against it
• degraded: answering, and not clearing the bar for verified
• failed: the402 has seen it fail, or the payTo does not match what it advertises. This one blocks purchases through the402
• unknown: the402 has no statement. It is the default, it never blocks anything, and it is not a bad grade

Verdicts are free to read (GET /v1/reputation/:wallet, no key, no wallet) and the only number that comes out of one is its band: 100, 50, 0, or none at all for unknown. The ruleset is published in full at how the402 decides, and every statement names the methodology it was made under (the402-trust-v1).

Where the evidence comes from

• Free availability sweeps: does the endpoint still answer a valid 402
• Funded probes, which run only against an endpoint whose operator claimed it, accepted the terms and opted in. the402 pays for no probes: one is funded by you, by a buyer verifying you, or by a pool the402 tops up for disputes
• Signed buyer attestations, on-chain activity, the sandbox, and the402’s own checkout outcomes

The parts that protect you

• A verdict can be contested. As the claimant you can file a dispute against the verdict, an observation or a flag; it goes on a public register with your reason, and a person reviews it. The reviewer’s note stays private
• An expired statement is a silence. Statements carry an expiry, so one the402 stops renewing ages out rather than following you
• First-party endpoints are labelled first-party and never scored: the402 does not rate its own
• The old 0–100 score is gone. Its four dimensions and its tiers were retired on 2026-09-09; nothing writes or reads them

Testing & Sandbox

Two ways to exercise your receiver without waiting on a buyer.

Check your receiver against the contract

Everything below is testable against your own worker before a buyer ever arrives, and most of it is testable with curl.

• Listing: the Provider Agreement accepted (GET /dashboard/api/settings → provider_terms.current); instant / data_api / fixed with a sellable price; the listing visible in GET /v1/services/catalog, and if it is not, the listings_blocked_reason on the write’s own answer read
• Signature: X-Platform-Secret compared against your API key; a timestamp older than five minutes rejected; the HMAC verified over ${ts}.${body} and not the body alone; each of those three failing independently in your own tests
• Events: connectivity_probe acknowledged 200 with no job created; an unknown type acknowledged rather than 500ing, so a new event kind never reads as an outage
• Fulfilment: the deliverable posted to the dispatch’s own callback_url; an instant handler answering inside the402’s inline window (20 seconds under the checkout, with the template’s own timeout of 15 inside it); a failure answering a 4xx you mean, because a refusal and an outage are recorded differently
• Money: a payout wallet set and the splitter row confirmed (no listings_blocked_reason: "splitter_pending" on the answer); GET /v1/provider/earnings reconciling with what your splitter has forwarded

The provider template carries a webhook-mode and an endpoint-mode example of exactly this shape, and an end-to-end script that buys both and checks the money on chain, which is the cheapest way to find out that a receiver is nearly right.

The provider sandbox

Once an endpoint is claimed and corroborated, which means the402 indexed it from Bazaar, or you proved the origin itself with a well-known document, a DNS TXT record or a signed liveness check on your webhook, so a pair known only from a signature or wallet_claim proof is claimed but not yet enrollable, you can enrol it in the proving ground: the402 dispatches unpaid sandbox_task events through the same signed contract a real job uses, you solve them and post the answer back, and each run is graded into one piece of evidence. The tasks are small and self-contained: echo the input, hash a string, answer a question with one right answer, conform to your declared schema, answer within a time limit, and a comprehension question graded by a model. Every run is published: the402’s input, your output, and whether it passed. Enough clean runs earn sandbox_verified, a label that counts for less than production evidence. ● Live The proving ground is open and opt-in; templates/provider/src/sandbox.ts solves the mechanical kinds.

What Is Coming Back

The checkout cutover defers ten features. Deferred is not retired: the code is kept, a later lane re-bases it, and nobody’s account, wallet, USDC or data goes anywhere. Every deferred write answers the same body, so a client parses it once: 410, code: "deferred", and a replacement saying what to do instead. Reads stay open in every case below.

The rest of the set: the prepaid balance an agent could spend without signing each call, referral payouts, and file uploads into a thread. That is ten. Earnings, attachments, threads and history all stay readable in every case.

Notifications

Beside your webhook, the402 can tell a human when something happens. Configure any of them at the402.ai/dashboard under Settings, and send yourself a test from the same page. ● Live

• Email: the simplest one, and the only one that needs nothing but an address
• Telegram: generate a link code in Settings, send it to the bot, and get interactive buttons on each notification
• Discord and Slack: a bot token and channel id give you interactive components; a plain incoming webhook URL works as a fallback

They fan out in parallel, so configuring three does not slow anything down. Buttons for an action the cutover defers are suppressed where they are rendered, and a stale button somebody pressed earlier answers with a note rather than doing something the platform no longer does.

What you will be told about: a new purchase, a message in one of your threads, a delivery verified or disputed, and the escalating warnings about a webhook that has stopped answering. Those last ones go out before your listings come off sale, not after.

MCP Server

@the402/mcp-server 2.0 gives an MCP-compatible assistant 20 the402 tools, three of which are a provider’s: create_service, update_service and delete_service, beside update_profile and the thread reads. Set THE402_API_KEY and your assistant can manage your listings conversationally.

◐ Rolling out Not published yet. Version 2.0 is built and in the repository; the 1.x release on npm carries an older, larger tool set written before the pivot, so what is described here is not what npx fetches today.

Webhook Reference

Headers, by contract

Both signatures are the same shape, sha256=<hex>, so one constant-time comparison serves both. Same secret, same five-minute replay window, different header names. So a signature over one content can never be verified under the name of another.

Saving a webhook URL

• https only, and validated against SSRF when you save it
• Development tunnels, request-inspection bins and placeholder hosts are refused at save time. An endpoint that answers anything is not an endpoint that can take a job
• Validated when you save it, and probed hourly after that through the liveness sweep, which keeps running while paid activity is paused
• A self-test button in the dashboard runs the same signed probe on demand, and a pass is what clears a block before the next sweep would

What a failure costs

Two consecutive failed probes are enough for the pre-purchase gate to stop selling your services, a purchase answers 503 while the listing itself is still active, and the third is what deactivates the listings. A recovery brings them back, through the listing gate under the checkout rather than straight onto the catalog. Every non-healthy probe counts, whatever the cause: a refused secret, a missing route, a 5xx or a timeout alike.

API Reference

Every provider call takes X-API-Key unless it says otherwise. The full machine-readable list is /openapi.json, where each route also carries what it answers today and what the cutover will make of it.