# Hedera Environment Setup

> Guide complete Hedera testnet/mainnet developer setup — Hedera Portal account, testnet faucet HBAR, OPERATOR_ID/OPERATOR_KEY env configuration, installing @hashgraph/sdk or Hiero Java SDK, verifying connectivity with AccountBalanceQuery, Mirror Node REST smoke tests. Use when the user says setup, testnet, mainnet, faucet, env vars, mirror node URL, SDK install, operator key, portal.hedera.com, cannot connect, INVALID_SIGNATURE, or asks how to start building on Hedera from zero.

- Skill: `evaluris-solutions/hedera-environment-setup` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add evaluris-solutions/hedera-environment-setup`
- Raw SKILL.md: https://api.skillmd.com/api/skills/evaluris-solutions/hedera-environment-setup/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: Evaluris-Solutions (https://skillmd.com/u/evaluris-solutions)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/evaluris-solutions/hedera-environment-setup

---


## Overview

This skill walks developers through a **safe, repeatable** environment bootstrap for Hedera **testnet first**, then documents **mainnet** differences. It aligns with official Hiero SDK patterns ([JavaScript](https://github.com/hashgraph/hedera-sdk-js), [Java](https://github.com/hashgraph/hedera-sdk-java)) and Mirror Node REST usage documented at [docs.hedera.com](https://docs.hedera.com/hedera).

## When to use this skill

- Creating accounts via [Hedera Portal](https://portal.hedera.com/) or programmatic flows later.
- Requesting **testnet HBAR** from the official faucet (linked from docs — verify current URL on [docs.hedera.com — Hedera Testnet Faucet](https://docs.hedera.com/hedera/getting-started-evm-developers/hedera-testnet-faucet)).
- Choosing **ED25519 DER** vs **hex ECDSA** private key encodings for `OPERATOR_KEY`.
- Wiring `.env` for scripts and CI without leaking keys.

## Prerequisites

- Node.js **18+** for JS samples (`npm install` at repo root).
- A Hedera Portal account (email verification).
- For Mirror REST checks: network reachability to public mirror hosts (corporate proxies may block).

## Workflow

1. **Create / recover operator credentials**
   - Register at [portal.hedera.com](https://portal.hedera.com/). Download or copy **testnet** key material for an operator account.
   - **Never** commit keys. Store only in `.env` or a secrets manager.

2. **Fund testnet account**
   - Use the official **testnet faucet** per current docs (portal UI often embeds the link). Confirm balance in a block explorer or via SDK/Mirror.

3. **Choose network in `.env`**

   ```bash
   HEDERA_NETWORK=testnet   # testnet | previewnet | mainnet
   OPERATOR_ID=0.0.12345
   OPERATOR_KEY=302e020100301006072a8648ce3d020106052b8104000a042204...
   MIRROR_REST_URL=https://testnet.mirrornode.hedera.com
   ```

   See [references/env-vars.md](references/env-vars.md) for the full matrix.

4. **Install Hiero JavaScript SDK** (project-local):

   ```bash
   npm install @hashgraph/sdk dotenv
   ```

   Java projects: use Gradle/Maven coordinates from [hashgraph/hedera-sdk-java](https://github.com/hashgraph/hedera-sdk-java) README — mirror this guidance when users pick Java.

5. **Verify consensus connectivity**

   Run from repository root after `npm install`:

   ```bash
   node plugins/hedera-skills/skills/hedera-environment-setup/scripts/verify-connection.js
   ```

   This executes `AccountBalanceQuery` against the operator account — proving signing keys match `OPERATOR_ID`.

6. **Verify Mirror Node REST**

   The same script performs an HTTP GET to `/api/v1/balances?account.id=<OPERATOR_ID>` (see `references/endpoints.md` for hostnames).

7. **Mainnet readiness gate**

   Before **mainnet**: key custody policy, funding source, optional multisig / custody/HSM, fee estimation from [network fees API](https://docs.hedera.com/hedera/sdks-and-apis/rest-api/network.md). Default all tutorials to **testnet**.

## Examples

**Example 1 — student on Udemy**

> “I created a Portal account; how do I set `.env` and prove my SDK works?”

Guide them through sections **Workflow** steps 3–6 and run `verify-connection.js`. Explain DER-encoded ED25519 keys often start with `302e0201…`.

**Example 2 — switching networks**

> “I need previewnet for a HIP prototype.”

Set `HEDERA_NETWORK=previewnet`, update `MIRROR_REST_URL` to previewnet mirror base URL from [references/endpoints.md](references/endpoints.md), rebuild `Client.forPreviewnet()`.

**Example 3 — CI secrets**

> “How do I load keys in GitHub Actions safely?”

Use encrypted secrets (`OPERATOR_KEY`), inject env at runtime, **never** echo secrets in logs; rotate keys if leaked.

## Troubleshooting

| Symptom | Likely cause | Fix |
| --- | --- | --- |
| `INVALID_SIGNATURE` | Wrong key for `OPERATOR_ID`, or mixed ED25519/ECDSA | Regenerate key export from Portal; ensure signing uses same curve |
| `INSUFFICIENT_PAYER_BALANCE` | Unfunded operator | Use faucet (testnet) or transfer HBAR |
| Mirror HTTP 404 / empty | Wrong mirror host for network | Align `MIRROR_REST_URL` with network |
| TLS / proxy errors | Corporate MITM | Trust store update or allowlist mirror hosts |

## References

- Bundled: [references/endpoints.md](references/endpoints.md), [references/env-vars.md](references/env-vars.md), [references/sdk-compatibility.md](references/sdk-compatibility.md)
- Official: [Networks — Testnet](https://docs.hedera.com/hedera/networks/testnet.md), [Build Your Hedera Client](https://docs.hedera.com/hedera/sdks-and-apis/sdks/client.md), [Mirror Node REST API](https://docs.hedera.com/hedera/sdks-and-apis/rest-api.md)
- Portal: [portal.hedera.com](https://portal.hedera.com/), builder hub [hedera.com/start-building](https://hedera.com/start-building)