Prerequisites
- A Hedera testnet operator account ID and DER-encoded private key (from the Quickstart).
- A small amount of testnet HBAR (ℏ) to cover the fees
- Topic creation: ≈
$0.01 - Each message: <
$0.001
- Topic creation: ≈
NoteYou can always check the ”✅ Code Check” section at the bottom of each page to view the entire code if you run into issues. You can also post your issue to the respective SDK channel in our Discord community here.
Install the SDK
- JavaScript
- Java
- Go
- Python
Open your terminal and create a directory Initialize a Ensure you have Node.js Update your Create a
hedera-examples directory. Then change into the newly created directory:node.js project in this new directory:v18 or later installed on your machine. Then, install the JavaScript SDK.package.json file to enable ES6 modules and configure the project:createTopicDemo.js file and add the following imports:Environment Variables
Set your operator credentials as environment variables. YourOPERATOR_ID is your testnet account ID. Your OPERATOR_KEY is your testnet account’s corresponding ECDSA private key.
Step 1: Initialize Hedera Client
Load your operator credentials from environment variables and configure your Hedera testnet client. The client manages your connection to the Hedera test network and uses your operator account to sign transactions and pay transaction fees.Step 2: Create a new topic
TopicCreateTransaction builds and sends the transaction to register a new HCS topic with the provided memo, and once it reaches consensus you retrieve the transaction receipt to extract the new topicId.
Why messages?
Messages on HCS are consensus-timestamped and immutable. Once published, they become part of the permanent record that anyone can verify and subscribe to in real-time.What just happened?
- The SDK built a TopicCreateTransaction.
- Your operator key signed and paid the fee.
- Hedera nodes reached consensus and returned a unique topic ID (
shard.realm.num).
Step 3: Submit Message to Topic
TopicMessageSubmitTransaction constructs and sends a transaction that submits your payload (string, bytes, or Uint8Array) as a message to a specified HCS topic. Once it reaches consensus, the message becomes part of that topic’s immutable record.
NoteMessages can be up to 1 KiB each. Larger payloads must be chunked automatically by the SDK or split manually
Step 4: Query Messages Using Mirror Node API
Use the Mirror Node REST API to verify your message was published to the topic. Mirror nodes provide free access to network data without transaction fees. Mirror nodes stream every consensus-timestamped message in order, letting your app react in real time. API endpoint:{topicId}- Your topic ID from the creation transaction
Why this endpoint? This endpoint retrieves all messages published to a specific topic, ordered by consensus timestamp. It returns detailed information including message content, timestamp, and sequence number, making it ideal for verifying your message was published successfully.Example URLs:
✅ Code check
Before running your project, verify your code matches the complete example:JavaScript
JavaScript
Java
Java
Go
Go
Python
Python
Run Your Project
Ensure your environment variables are set:- JavaScript
- Java Maven
- Java Gradle
- Go
- Python
JavaScript
Expected sample output:
‼️ Troubleshooting
Common ERROR messages and solutions ⬇️
Common ERROR messages and solutions ⬇️
| Error message | Likely cause | Fix | | ---------------------------- |
---------------------------------------------- |
-------------------------------------------------------------- | |
INSUFFICIENT_PAYER_BALANCE | Not enough HBAR for topic creation fee | Top up
your operator account on the testnet faucet | | INVALID_SIGNATURE | Operator
key doesn’t match operator account | Verify OPERATOR_KEY matches your
OPERATOR_ID | | INVALID_ACCOUNT_ID | Malformed account ID in environment
variables | Verify OPERATOR_ID format is 0.0.1234 | | INVALID_PRIVATE_KEY |
Malformed private key in environment variables | Verify OPERATOR_KEY is a
valid DER-encoded private key string | | INVALID_TOPIC_ID | Topic ID not
found or malformed | Ensure topic was created successfully and ID is correct |
| No messages found yet | Mirror Node sync delay | Wait a few more seconds
and try again - this is normal |What Just Happened?
- The SDK built a
TopicCreateTransactionand signed it with your operator key. - A consensus node validated the signature and charged the topic creation fee.
- After network consensus, a unique topic ID was assigned and returned in the receipt.
- Your message was submitted to the topic and became part of the immutable record.
- The Mirror Node API confirmed your message was published with consensus timestamp
Next steps
- Subscribe to the topic from your backend or front-end to process messages as they come in
- Encrypt messages if you need privacy before publishing
- Explore more examples in the SDK repos (JavaScript, Java, Go)
🎉 Great work! You have created a new topic and broadcasted your first message on Hedera testnet. Keep building!