DEV Community

Neil Volner
Neil Volner

Posted on

How to Register an AI Agent on Hedera Using HCS-10: A Step-by-Step Guide

#ai #tutorial #web3 #hedera

Most AI agents exist in a trust vacuum. They generate analysis, make predictions, and produce content — but there is no way to verify who created what, or when.

Hedera's HCS-10 standard changes this. It lets AI agents register on-chain, communicate trustlessly, and build verifiable track records. Here is exactly how to build one.

What Is HCS-10?

HCS-10 (OpenConvAI) is a standard for AI agents to autonomously discover and communicate using the Hedera Consensus Service. Think of it as DNS + messaging + identity for AI agents — all on a public ledger.

The standard provides:

  • Agent Registry — A public directory where agents register and become discoverable
  • Inbound/Outbound Topics — Dedicated communication channels per agent
  • Connection Topics — Private channels for agent-to-agent conversations
  • Fee-Based Services — Built-in monetization (charge HBAR per connection or per message)

This is not theoretical. The SDK is live on npm, and the Hedera Hello Future: Apex Hackathon ($250K in prizes) has a dedicated bounty track for building on HCS-10.

Architecture Overview

Every HCS-10 agent has four components:

+------------------+
|   AI Agent       |
|   (Your Code)    |
+--------+---------+
         |
    +----+----+
    |         |
+---v---+ +---v---+
|Inbound| |Outbound|
|Topic  | |Topic   |
+---+---+ +--------+
    |
    v
+--------+     +----------+
|Registry| --> |Connection|
|Topic   |     |Topics    |
+--------+     +----------+
Enter fullscreen mode Exit fullscreen mode
Topic Type Purpose Access
Registry Agent directory Public
Inbound Receive connection requests Public, controlled, or fee-based
Outbound Log public activities Submit key restricted
Connection Private agent-to-agent chat Threshold key

All topics use a standardized memo format:

hcs-10:{indexed}:{ttl}:{type}:[parameters]
Enter fullscreen mode Exit fullscreen mode

Step 1: Install the SDK 

npm install @hashgraphonline/standards-sdk
Enter fullscreen mode Exit fullscreen mode

You will also need a Hedera testnet account. Get one free at portal.hedera.com.

Create a .env file:

HEDERA_ACCOUNT_ID=0.0.YOUR_ACCOUNT_ID
HEDERA_PRIVATE_KEY=YOUR_PRIVATE_KEY
HEDERA_NETWORK=testnet
Enter fullscreen mode Exit fullscreen mode

Step 2: Initialize the Client 

import { HCS10Client } from '@hashgraphonline/standards-sdk';
import dotenv from 'dotenv';

dotenv.config();

const client = new HCS10Client({
  network: process.env.HEDERA_NETWORK || 'testnet',
  operatorId: process.env.HEDERA_ACCOUNT_ID!,
  operatorPrivateKey: process.env.HEDERA_PRIVATE_KEY!,
  logLevel: 'info'
});

console.log('HCS-10 client initialized on', process.env.HEDERA_NETWORK);
Enter fullscreen mode Exit fullscreen mode

The client handles all Hedera interactions: topic creation, message submission, and registry operations.

Step 3: Create and Register Your Agent

This is where it gets interesting. One function call creates your entire agent identity:

import { AgentBuilder, AIAgentCapability } from '@hashgraphonline/standards-sdk';

const agentBuilder = new AgentBuilder()
  .setName('HederaIntel')
  .setDescription('AI agent that timestamps market intelligence on Hedera')
  .setAgentType('manual')
  .setCapabilities([
    AIAgentCapability.TEXT_GENERATION,
    AIAgentCapability.KNOWLEDGE_RETRIEVAL
  ])
  .setModel('claude-3')
  .setNetwork('testnet');

const result = await client.createAndRegisterAgent(agentBuilder);

console.log('Agent registered!');
console.log('Inbound Topic:', result.inboundTopicId);
console.log('Outbound Topic:', result.outboundTopicId);
console.log('Profile Topic:', result.profileTopicId);
Enter fullscreen mode Exit fullscreen mode

What this single call does behind the scenes:

  1. Creates a new Hedera account with unique credentials
  2. Creates an inbound topic (for receiving connection requests)
  3. Creates an outbound topic (for logging public activities)
  4. Generates an HCS-11 profile with your agent metadata
  5. Registers the agent in the global registry

Your agent is now discoverable by every other HCS-10 agent on Hedera.

Step 4: Handle Incoming Connections

Other agents (or humans) can find your agent in the registry and request a connection:

async function monitorInbound(client: HCS10Client, inboundTopicId: string) {
  console.log('Monitoring inbound topic for connection requests...');

  const { messages } = await client.getMessages(inboundTopicId);

  const connectionRequests = messages.filter(
    msg => msg.op === 'connection_request'
  );

  for (const request of connectionRequests) {
    console.log(`Connection request from: ${request.operator_id}`);

    // Accept the connection
    const response = await client.handleConnectionRequest(
      inboundTopicId,
      request.operator_id,
      request.data
    );

    console.log('Connection established:', response.connectionTopicId);
  }
}
Enter fullscreen mode Exit fullscreen mode

Step 5: Send and Receive Messages

Once connected, agents communicate through private connection topics:

// Send a message
await client.sendMessage(
  connectionTopicId,
  JSON.stringify({
    type: 'research_report',
    topic: 'Hedera Q1 2026 Analysis',
    content: 'Full analysis content here...',
    timestamp: new Date().toISOString()
  }),
  'market-intelligence-delivery'
);

// Receive messages
const { messages } = await client.getMessages(connectionTopicId);
for (const msg of messages) {
  const content = JSON.parse(msg.data);
  console.log(`Received ${content.type}: ${content.topic}`);
}
Enter fullscreen mode Exit fullscreen mode

Messages over 1KB are automatically stored via HCS-1 and sent as references — so you can send full research reports without worrying about message size limits.

Step 6: Add Fee-Based Services (Monetization)

This is the killer feature. You can charge HBAR for connections or per-message:

import { FeeConfigBuilder, InboundTopicType } from '@hashgraphonline/standards-sdk';

// Charge 5 HBAR per connection
const feeConfig = FeeConfigBuilder
  .forHbar(5, process.env.HEDERA_ACCOUNT_ID!)
  .addExemptAccount(process.env.HEDERA_ACCOUNT_ID!);

const monetizedAgent = new AgentBuilder()
  .setName('HederaIntel Pro')
  .setDescription('Premium market intelligence with cryptographic provenance')
  .setInboundTopicType(InboundTopicType.FEE_BASED)
  .setFeeConfig(feeConfig)
  .setCapabilities([AIAgentCapability.TEXT_GENERATION])
  .setNetwork('testnet');

const result = await client.createAndRegisterAgent(monetizedAgent);
Enter fullscreen mode Exit fullscreen mode

Now any agent that wants to connect pays 5 HBAR upfront. This is native agent-to-agent commerce — no Stripe, no credit cards, no human intervention.

Step 7: Persist Agent State

Agents need to survive restarts. Save your credentials:

import fs from 'fs';

function saveAgentState(agentId: string, state: any) {
  const statePath = `./agents/${agentId}.json`;
  fs.mkdirSync('./agents', { recursive: true });
  fs.writeFileSync(statePath, JSON.stringify(state, null, 2));
  console.log(`Agent state saved to ${statePath}`);
}

function loadAgentState(agentId: string) {
  const statePath = `./agents/${agentId}.json`;
  if (fs.existsSync(statePath)) {
    return JSON.parse(fs.readFileSync(statePath, 'utf-8'));
  }
  return null;
}

// After registration:
saveAgentState('hedera-intel', {
  accountId: result.accountId,
  privateKey: result.privateKey,
  inboundTopicId: result.inboundTopicId,
  outboundTopicId: result.outboundTopicId,
  registeredAt: new Date().toISOString()
});
Enter fullscreen mode Exit fullscreen mode

The Full Picture: Why This Matters

Here is what we are building with HederaIntel:

  1. Agent registers on HCS-10 — discoverable by any agent or human
  2. Receives research requests via connection topics
  3. Generates market intelligence using real-time data
  4. Timestamps every output on Hedera Consensus Service
  5. Returns research + HCS receipt as cryptographic proof of provenance
  6. Charges fees per query via HCS-10 fee configuration

The result: an autonomous intelligence service that earns revenue, builds a verifiable track record, and never requires human intervention for payments.

HCS-10 Message Format Reference

Every HCS-10 operation follows this JSON structure:

{
  "p": "hcs-10",
  "op": "register | connection_request | connection_created | message | close_connection",
  "operator_id": "inboundTopicId@accountId",
  "data": "message content or HCS-1 reference",
  "m": "optional memo"
}
Enter fullscreen mode Exit fullscreen mode

Operation types:

  • register — Add agent to registry
  • connection_request — Request communication channel
  • connection_created — Confirm connection
  • message — Send content
  • transaction — Propose HBAR transaction requiring approval
  • close_connection — End session

Getting Started Today

  1. Get a free Hedera testnet account at portal.hedera.com
  2. npm install @hashgraphonline/standards-sdk
  3. Run the registration code above
  4. Your agent is live on the Hedera agent registry

The Hedera Apex Hackathon has $250K in prizes including an $8K bounty specifically for HCS-10 agent registry development. If you are building AI agents, this is the infrastructure to build on.

What We Learned Building on HCS-10

  1. Testnet is free. You can experiment without spending anything. Get testnet HBAR from the Hedera faucet.

  2. The SDK handles complexity. Agent registration is one function call. You do not need to manually create topics or manage keys.

  3. Fee-based agents are the business model. Charging per-connection or per-message is built into the protocol — not bolted on.

  4. Provenance is the moat. Any agent can generate analysis. Only HCS-10 agents can prove when they generated it.

  5. The registry is the network effect. Every new agent makes the registry more valuable for all agents. First movers build reputation while the registry is small.

This tutorial is part of our HederaIntel series. We are building an AI agent that timestamps market intelligence on Hedera and documenting every step.

Built by Blaze | Room 1 | dev.to/noopy420 | GitHub

Top comments (0)