> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hedera.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Hedera is a public, proof-of-stake distributed ledger that uses hashgraph consensus. Do not call it a blockchain.
> Always search the current Hedera documentation over training data before generating code, especially for SDK imports and package names.
> For JavaScript, import from `@hiero-ledger/sdk`, not `@hashgraph/sdk`; new SDK releases ship as `@hiero-ledger/sdk`. The Java SDK keeps the `com.hedera.hashgraph:sdk` Maven coordinates. Verify the exact import against the docs.
> Write HBAR in uppercase and always singular ("10 HBAR", never "10 HBARs" or "10 hbar"). Write tinybars in lowercase and plural.
> Write network names in lowercase, even after "Hedera": "Hedera mainnet", "Hedera testnet", "Hedera previewnet", not title case.
> For EVM-oriented accounts, create the account with an ECDSA key and set the EVM Address from Public Key at creation. This address is immutable and is not updated by key rotation. Do not use retired terms like "EVM alias" or "Account Number Alias".

# Configuring Hardhat for Hedera

> What you need to know before pointing Hardhat at Hedera: the JSON-RPC relay, why deployments require ECDSA keys, and the Hedera-specific behavior that surprises EVM developers.

Hardhat talks to Hedera through the [Hiero JSON-RPC Relay](/evm/development/json-rpc), which translates Ethereum JSON-RPC calls into Hedera transactions. Once you point Hardhat at a relay endpoint, the workflow is the same as any other EVM chain: `npx hardhat build`, deploy scripts, ethers.js, and tests all behave normally.

This page covers what is Hedera-specific. For a full local walkthrough, the Solo team maintains an end-to-end Hardhat guide.

<Card title="Using Solo with EVM tools" href="https://solo.hiero.org/docs/using-solo/using-solo-with-evm-tools/" arrow>
  Deploy a local Solo network, generate funded ECDSA accounts, configure `hardhat.config.ts`, deploy a contract, and connect MetaMask.
</Card>

## Pick a relay endpoint

| Target | RPC URL | Chain ID |
| - | - | - |
| Local network (Solo) | `http://localhost:37546` | `298` |
| Testnet (Hashio) | `https://testnet.hashio.io/api` | `296` |
| Mainnet (Hashio) | `https://mainnet.hashio.io/api` | `295` |

Solo's relay port changed in version 0.63; deployments on 0.62 and earlier use `7546`. Solo also forwards to the next free port if `37546` is taken, so confirm the assignment printed at the end of your deploy. See [Local Development](/native/local-dev/index) for the current endpoint list, and the [JSON-RPC relay page](/evm/development/json-rpc) for third-party and self-hosted options.

<Warning>
  Hashio is intended for development and testing. For production, use a [commercial-grade relay](/evm/development/json-rpc#community-hosted-json-rpc-relays) or host your own [Hiero JSON-RPC Relay](https://github.com/hiero-ledger/hiero-json-rpc-relay).
</Warning>

## Use ECDSA keys

Hedera supports both ED25519 and ECDSA (secp256k1) keys, but only ECDSA keys work over the JSON-RPC relay. An ED25519 account has no EVM address that Hardhat or ethers.js can sign for, so deployments from one fail.

* **Local network:** Solo writes pre-funded ECDSA accounts to the `createdAccounts` array in `~/.solo/one-shot-<deployment-name>/accounts.json`. Each entry includes the private key (`0x` plus 64 hex characters), its public key, and the derived EVM address.
* **Testnet and mainnet:** create an ECDSA account in the [Hedera Portal](https://portal.hedera.com/) and use its **HEX Encoded Private Key**, not the DER-encoded one.

Read [Addresses](/evm/development/addresses) for how Hedera account IDs and EVM addresses relate.

## Configure the network

Hardhat 3 requires `type` and `chainId` on HTTP networks. Without both, connecting to the relay fails with `HHE40000: No network with chain id "298" found`. Define one network entry per target rather than swapping the URL, since `chainId` has to move with it:

```typescript hardhat.config.ts theme={null}
import type { HardhatUserConfig } from "hardhat/config";
import { configVariable } from "hardhat/config";

const config: HardhatUserConfig = {
  solidity: "0.8.28",
  networks: {
    hederaLocal: {
      type: "http",
      url: "http://127.0.0.1:37546",
      chainId: 298,
      accounts: [configVariable("HEDERA_PRIVATE_KEY")],
    },
    hederaTestnet: {
      type: "http",
      url: "https://testnet.hashio.io/api",
      chainId: 296,
      accounts: [configVariable("HEDERA_PRIVATE_KEY")],
    },
  },
};

export default config;
```

The network key is what you pass to `--network`, so `npx hardhat run scripts/deploy.ts --network hederaLocal` targets the local relay.

Store the private key with Hardhat's keystore rather than committing it:

```bash theme={null}
npx hardhat keystore set HEDERA_PRIVATE_KEY
```

<Accordion title="Migrating from Hardhat 2 to Hardhat 3">
  * **compile → build**: `npx hardhat compile` is now `npx hardhat build`.
  * **project init**: `npx hardhat init` is now `npx hardhat --init`.
  * **keystore commands**: the keystore plugin (`npx hardhat keystore set ...`) is new in v3.
  * **Solidity tests**: v3 runs Foundry-compatible Solidity tests alongside TypeScript integration tests.
  * **Network management**: v3 tasks can open and manage multiple network connections at once.

  See the [Hardhat documentation](https://hardhat.org/docs/getting-started) for the full migration guide.
</Accordion>

## Hedera-specific gotchas

* **Gas price units.** The relay returns `msg.value` and `gasPrice` with 18 decimals, while native Hedera APIs use 8 decimals for HBAR. See [HBAR decimal places](/evm/development/json-rpc#hbar-decimal-places).
* **Foundry and Hardhat print "ETH".** Tooling hardcodes the label. The currency being spent is HBAR.
* **Contract verification.** Sourcify supports mainnet (`295`) and testnet (`296`). It does not support a local network, so verification has to wait until you deploy to a public network.
* **Token association.** Transferring an HTS token to an account requires that account to be associated with the token first. See [token association](/native/tokens/associate).

## Further learning

1. [**How to Mint and Burn an ERC-721 Token** (Part 1)](/evm/tutorials/advanced/erc721-hardhat/part1-mint-burn)\
   Create a basic ERC-721 NFT, mint it, and burn it on Hedera.
2. [**Access Control, Token URI, Pause & Transfer** (Part 2)](/evm/tutorials/advanced/erc721-hardhat/part2-access-control)\
   Extend your NFT with pausing, token URIs, and role-restricted minting.
3. [**Upgrade Your NFT with UUPS Proxies** (Part 3)](/evm/tutorials/advanced/erc721-hardhat/part3-upgradeable)\
   Add upgradeability using OpenZeppelin's UUPS proxy pattern.

<Columns cols={2}>
  <Card title="Writer: Michiel, DevRel Engineer" arrow>
    [GitHub](https://github.com/michielmulders) |
    [LinkedIn](https://www.linkedin.com/in/michielmulders/)
  </Card>

  <Card title="Editor: Krystal, Senior DX Engineer" arrow>
    [GitHub](https://github.com/theekrystallee) |
    [X](https://x.com/theekrystallee)
  </Card>

  <Card title="Editor: Kiran, Developer Advocate" arrow>
    [GitHub](https://github.com/kpachhai) |
    [LinkedIn](https://www.linkedin.com/in/kiranpachhai/)
  </Card>
</Columns>