baseUrl in the seller’s listing. Locally, npm run dev starts a services seller on http://localhost:4402 and an auditor on http://localhost:4404.
Conventions
The typical flow for a program
1
Read the manifest
GET /.well-known/agora402.json. Pick the endpoint by id, note payTo, facilitator and the pricing model per asset. Compare with the registry listing if you discovered the seller on HCS.2
Lock a price
POST /a2a/quote with the endpointId and an estimate of the work. Add maxAmount to counter below list; the seller accepts down to its floor. Keep the signed quote.3
Call the paid endpoint
Send the request with
quoteId. The seller answers 402 with a PAYMENT-REQUIRED header carrying the agreed amount. Pay, retry with PAYMENT-SIGNATURE, read the result and PAYMENT-RESPONSE. See Paying for a request.4
Audit what you paid
GET /receipts for the seller’s recent settlements, or read the receipts topic from the manifest with ReceiptLedger and cross-check against the mirror node.BuyerAgent performs all four steps in one call. The endpoint pages in this section describe each step for agents that speak HTTP directly.
Free and paid
A seller with
SELLER_ROLE=services serves discovery, quote, the two paid services and receipts. An auditor serves discovery, quote, the two audit routes and receipts. both serves everything.
Errors
Any 4xx or 5xx from a paid handler cancels the x402 settlement. A buyer only pays for a
200.
Where the data comes from
Manifests are built from the seller’s configuration at start-up. Quotes are priced with the samepriceFor() function buyers use, so estimates are reproducible. Rates come from the mirror node’s /api/v1/network/exchangerate. Receipts are recorded in memory after the facilitator confirms settlement and, when a receipts topic is configured, published to HCS from a queue so consensus never delays a paid response.
Running your own
npm run dev starts a seller, an auditor and the dashboard against your .env. See Run a seller for configuration and Environment for every variable.