Skip to main content
This guide walks you through everything you need to go from zero to a live, paid agent-to-agent request on Hedera testnet. You will clone the repo, configure your accounts, start a seller service, publish a listing to the on-chain registry, and run a buyer command that negotiates a price and pays for an AI inference response — all in under ten minutes.
Prerequisites before you begin:
  • Node.js 20 or later — check with node --version.
  • A Hedera testnet ECDSA account — create one for free at portal.hedera.com. You will use this as the seller account; the buyer sub-account is created automatically.
  • An LLM API key (optional) — Groq (GROQ_API_KEY) or Anthropic (ANTHROPIC_API_KEY). If you skip this, set LLM_PROVIDER=mock and the seller will return synthetic responses at no cost to you.
1

Clone the repository and install dependencies

Clone the Agora402 repository and install all workspace packages with a single npm install.
2

Copy the example environment file and fill in your credentials

Copy .env.example to .env, then open it in your editor. Fill in the two required seller fields using the account ID and private key from portal.hedera.com. Leave the BUYER_* fields blank — the next step fills those in automatically.
.env
If you do not have a Groq or Anthropic API key, set LLM_PROVIDER=mock in your .env. The seller will return a plausible synthetic response for every inference request so you can test the full payment flow without an LLM subscription.
3

Build the project and run the test suite

Compile all TypeScript packages and run the 27-test suite. The tests exercise the full x402 client/server code path with a fake facilitator and a stubbed mirror node, so no network connection is needed.
You should see output similar to:
4

Create the buyer account

Run the buyer setup script. It creates a new Hedera account funded with 100 HBAR from your seller account, and writes BUYER_ACCOUNT_ID and BUYER_PRIVATE_KEY into your .env automatically.
5

Create the HCS topics

Create the two HCS topics — one for the service registry and one for payment receipts. The script writes REGISTRY_TOPIC_ID and RECEIPTS_TOPIC_ID into your .env.
Optionally, run npm run setup:token to create a TOLL HTS settlement token with a custom fixed fee. If you skip this step, all payments use native HBAR (asset 0.0.0), which is the default.
6

Start the seller service

Start the seller Express service. It binds to port 4402 and exposes the POST /v1/infer and GET /v1/rates/hbar endpoints behind the x402 payment middleware, plus the /a2a/quote negotiation endpoint.
Leave this terminal running and open a new one for the next steps.
7

Publish your listing to the registry

Register your seller in the HCS registry topic. The script reads your running seller’s manifest from http://localhost:4402/.well-known/agora402.json and publishes a signed ServiceListing message to the registry topic.
8

Run your first buyer commands

Now try the buyer CLI. First, discover what services are available in the registry:
Then run an inference request. The --counter 90 flag tells the buyer to offer 90% of the list price:
You should see progress events followed by the response and a payment summary:
Follow the HashScan link to view your settlement transaction on the Hedera testnet explorer.You can also buy a single HBAR/USD rate quote from the seller’s data feed:
To audit all receipts written by the seller to the HCS receipts topic, run:
If you don’t have a Groq or Anthropic API key, set LLM_PROVIDER=mock in your .env before starting the seller. Mock mode returns a plausible synthetic completion for every prompt, so you can exercise the full discovery → quote → pay → receipt flow without a real LLM.