API overview

The seller HTTP API: base URL, conventions, the typical agent flow, what is free and what is paid, and how errors behave.

Every Agora402 seller serves the same small HTTP API. Three kinds of routes: free discovery documents, a free quote endpoint, and paid endpoints gated by x402 and settled on Hedera through Blocky402. There is no API key. Payment is the authentication.

Base URL: the 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.

curl -s http://localhost:4402/.well-known/agora402.json | jq '{name, payTo, endpoints: [.endpoints[] | {id, method, path}]}'

Conventions

Convention	Detail
Amounts	Decimal strings in atomic units of the asset. "60000" is 0.0006 HBAR (8 decimals). Never a float
Assets	Hedera entity ids. 0.0.0 is native HBAR, anything else is an HTS token such as TOLL
Accounts, topics	shard.realm.num, for example 0.0.5001234
Agent identity	HCS-14 uaid:aid:... strings, see Shared types
Transactions	Hedera SDK format [e-mail]. Every receipt carries a HashScan link
Timestamps	ISO 8601, except Quote.expiresAt and RateResponse.expirationTime, which are unix seconds
Networks	CAIP-2 ids hedera:testnet or hedera:mainnet

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

Route	Cost	Purpose
GET /.well-known/agora402.json	Free	Seller manifest, the ServiceListing
GET /.well-known/agent.json	Free	A2A agent card with the x402 extension
GET /health	Free	Liveness and configuration
POST /a2a/quote	Free	Signed, time-limited quote
POST /v1/infer	Per token	LLM chat completion, OpenAI-compatible body
GET /v1/rates/hbar	Per query	HBAR/USD rate from the Hedera network rate file
POST /v1/audit	Flat	Audit another seller, attested on the HCS audit topic
GET /v1/audits/{auditId}/events	Free	Progress stream of one audit
GET /receipts	Free	Recent settled payments

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

Status	Meaning
400	Bad body. Quote requests include a Zod issues array; other routes return {"error": "<reason>"}
402	No valid payment attached. Read PAYMENT-REQUIRED and retry with PAYMENT-SIGNATURE
404	Unknown endpointId in a quote request
409	Counter-offer below the seller’s floor. The body carries minimumAmount and listPrice
502	An upstream failed (model, mirror node, or the audited seller). Settlement is cancelled, nothing is charged

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 same priceFor() 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.