Create Agora402 HCS Topics and Optional HTS TOLL Token

Create the two Hedera Consensus Service topics Agora402 needs for discovery and audit, and optionally deploy a TOLL HTS token for alternative settlement.

Agora402 uses two Hedera Consensus Service (HCS) topics to make the marketplace fully on-chain and auditable without any centralised database. The registry topic is where sellers publish their service listings — buyers read it via the public mirror node to discover available services and their prices. The receipts topic is where the seller writes a cryptographic receipt for every settled payment, recording the transaction ID, payer, amount, and a hash of the response so anyone can verify the bill. Both topics are created in a single script, and their IDs are written to your .env automatically.

Create the HCS Topics

1. Run the topics setup script

   From the repository root, run:

   npm run setup:topics
   

   This creates two new HCS topics on Hedera testnet using your seller account credentials and submits the creation transactions to the network.

2. Wait for .env to be updated

   Once both transactions reach consensus, the script writes the new topic IDs to your .env. You will see output like:

   registry topic created:  0.0.4567890
   receipts topic created:  0.0.4567891
   .env updated with REGISTRY_TOPIC_ID and RECEIPTS_TOPIC_ID
   

   The exact topic IDs will differ — Hedera assigns sequential entity numbers on each network.

3. Confirm the variables in .env

   Verify both topic IDs were persisted:

   cat .env | grep TOPIC_ID
   

   Expected output:

   REGISTRY_TOPIC_ID=0.0.4567890
   RECEIPTS_TOPIC_ID=0.0.4567891
   

HCS topics are public and permissionless by default. Any Hedera account can submit a message to a topic, but the Agora402 registry’s trust model does not rely on topic-level access control. Instead, the buyer agent verifies that the payTo account in each listing matches the Hedera account that paid for the HCS submission — so spoofed listings from third parties are automatically discarded.

Optional: Deploy the TOLL HTS Token

By default, Agora402 settles all payments in native HBAR. If you want to add an on-chain royalty layer to every transfer — enforced automatically by the Hedera Token Service at the protocol level — you can deploy the TOLL token, a custom HTS fungible token with a fixed fee attached to every transfer.

1. Run the token setup script

   npm run setup:token
   

   The script creates a new HTS fungible token from the seller account, configures a custom fixed fee on the token so a portion of every TOLL transfer flows back to the fee collector, associates the buyer account with the token, and funds the buyer with an initial TOLL balance.

2. Check .env for the token ID

   After the script completes, your .env will contain:

   .env

   TOLL_TOKEN_ID=0.0.4567892
   

   Once TOLL_TOKEN_ID is set, the seller’s endpoints advertise TOLL as an accepted payment asset alongside HBAR, and the buyer agent selects the preferred asset at runtime.

Running npm run setup:token is entirely optional. If you leave TOLL_TOKEN_ID empty in .env, Agora402 settles every request in HBAR with no change to any other part of the system. You can add the TOLL token at any time without restarting the seller or re-publishing the registry listing.

The TOLL token adds an on-chain royalty layer to every transfer: the Hedera Token Service enforces the fixed fee automatically at the point of settlement, before the transaction ever reaches the seller. This means the fee is collected even if the seller’s application logic never runs — it is a protocol-level guarantee, not an application-level check.

Verify Your Topics on HashScan

After creating the topics, you can inspect them in the Hedera block explorer. Replace <TOPIC_ID> with the value from your .env:

https://hashscan.io/testnet/topic/<TOPIC_ID>

For example:

https://hashscan.io/testnet/topic/0.0.4567890

HashScan shows every message submitted to the topic, the submitting account, the consensus timestamp, and the decoded JSON payload. Use this to confirm that your listing was published successfully after running npm run setup:register, and to audit the receipts topic after running paid requests.

Bookmark both topic pages. The registry topic page lets you see all active seller listings on the network; the receipts topic page gives you a full public audit trail of every settled payment your seller has processed.