> ## 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".

# Scaffold HBAR: CLI for bootstrapping Hedera dApps

> Scaffold Hedera dApps from the command line. Pick a template, frontend, and Solidity framework—then get a runnable project in one step.

## What is Scaffold HBAR?

Scaffold HBAR is an interactive CLI tool (similar to `create-next-app` or `create-react-app`) for the Hedera ecosystem. It generates monorepo projects with:

* **Smart contracts** (Hardhat or Foundry)
* **Frontend** (Next.js App Router with RainbowKit, wagmi, and viem)
* **Hedera network configuration** (Testnet or Mainnet with Hashio RPC)
* **Pre-built UI components** for wallet connection, address display, and HBAR input

<CardGroup cols={2}>
  <Card title="Quick Start" icon="rocket" href="#quick-start">
    Create your first Hedera dApp in under a minute
  </Card>

  <Card title="Templates" icon="layer-group" href="#available-templates">
    Browse pre-built templates for common use cases
  </Card>

  <Card title="Scaffold UI" icon="puzzle-piece" href="/solutions/tools/scaffold-hbar/scaffold-ui">
    Shared components, hooks, and MCP server for AI agents
  </Card>

  <Card title="GitHub" icon="github" href="https://github.com/hedera-dev/create-scaffold-hbar">
    Source code and contributing guide
  </Card>
</CardGroup>

***

## Quick Start

### Prerequisites

Before using Scaffold HBAR, ensure you have:

* **Node.js** ≥ 20.18.3 — [nodejs.org](https://nodejs.org/)
* **Git** with `user.name` and `user.email` configured — [git-scm.com](https://git-scm.com/)
* **Package manager** — Yarn is recommended; npm is also supported. Node.js already includes npm. To use Yarn:
  ```bash theme={null}
  corepack enable && corepack prepare yarn@stable --activate
  ```

If you choose **Foundry** as the Solidity framework:

```bash theme={null}
curl -L https://foundry.paradigm.xyz | bash
foundryup
```

### Create a New Project

Run the CLI with `npm create`:

```bash theme={null}
npm create scaffold-hbar@latest
```

`npx create-scaffold-hbar@latest` is equivalent.

You'll be prompted to select:

1. **Project name** — Directory name for your new project
2. **Template** — Starting point for your dApp (blank, HTS token, NFT, etc.)
3. **Frontend** — `nextjs-app` or `none` (contracts only)
4. **Solidity framework** — `foundry`, `hardhat`, or `none`
5. **Network** — `testnet` or `mainnet`
6. **Package manager** — `yarn` (recommended) or `npm`

<Accordion title="Non-Interactive Mode">
  For CI pipelines or scripting, use flags to skip prompts:

  ```bash theme={null}
  # Accept all defaults (blank template, Foundry, testnet)
  npm create scaffold-hbar@latest -- --yes

  # Full customization
  npm create scaffold-hbar@latest my-scheduler-app -- \
    --template payments-scheduler \
    --frontend nextjs-app \
    --solidity-framework foundry \
    --network testnet \
    --package-manager yarn
  ```

  | Flag | Description |
  | - | - |
  | `-y, --yes` | Use defaults for all prompts |
  | `-t, --template <key>` | Template key (see [Available Templates](#available-templates)) |
  | `-f, --frontend <fw>` | `nextjs-app` or `none` |
  | `-s, --solidity-framework <fw>` | `foundry`, `hardhat`, or `none` |
  | `--network <network>` | `testnet` or `mainnet` |
  | `--package-manager <pm>` | `yarn` (recommended) or `npm` |
  | `--skip-install` | Don't install dependencies after scaffolding |
  | `--skip-hedera-skills` | Don't install [Hedera Skills](#hedera-skills-ai-assisted-development) after scaffolding |
</Accordion>

### Start Development

After scaffolding, start the development servers. Examples use Yarn; if you chose npm, replace `yarn <script>` with `npm run <script>`.

<Tabs>
  <Tab title="Foundry">
    ```bash theme={null}
    cd my-hedera-dapp

    # Terminal 1: Start local chain
    yarn foundry:chain

    # Terminal 2: Deploy contracts
    yarn foundry:deploy

    # Terminal 3: Start frontend
    yarn next:start
    ```
  </Tab>

  <Tab title="Hardhat">
    ```bash theme={null}
    cd my-hedera-dapp

    # Terminal 1: Start local chain
    yarn hardhat:chain

    # Terminal 2: Deploy contracts
    yarn hardhat:deploy

    # Terminal 3: Start frontend
    yarn next:start
    ```
  </Tab>
</Tabs>

Open [http://localhost:3000](http://localhost:3000) to see your dApp.

***

## Available Templates

Scaffold HBAR includes starter templates for common Hedera use cases. The CLI fetches templates dynamically from `templates/*` branches:

| Template | CLI Value | Description | Framework |
| - | - | - | - |
| **Blank Starter** | `blank` | Minimal baseline scaffold with no opinionated features—ideal starting point for custom dApps | Foundry or Hardhat |
| **Hedera Native** | `hedera-demo` | Demo focused on Hedera-native services (HTS, HCS, Mirror Node) with end-to-end UI—no Solidity contracts | Next.js only |
| **Onchain Cron Job** | `payments-scheduler` | Scheduled payments using Hedera Schedule Service (HSS) with a ScheduledVault pattern and pluggable strategies (e.g., DCA) | Foundry |
| **Cross-chain DCA** | `cross-chain-dca` | Hedera-orchestrated recurring DCA: `DcaOrchestrator` uses Schedule Service to trigger cross-chain swaps on Sepolia via Axelar GMP and Uniswap v3 | Hardhat |
| **Bridge** | `bridge` | Cross-chain bridge connecting Ethereum Sepolia and Hedera Testnet with Axelar, CCIP, or LayerZero providers | Foundry |
| **Oracles** | `oracles` | Provider-agnostic oracle pattern with adapters for Chainlink, Supra, and Pyth price feeds | Foundry |
| **Tokenize Subscriptions** | `tokenise-subscriptions` | SubRent NFT marketplace—tokenize subscriptions (gym, WiFi, streaming) as HTS NFTs with rental and sales | Hardhat |
| **x402 Pay-Per-Use** | `x402-pay-per-use` | Pay-per-download file marketplace using the x402 protocol with HashPack payments and MinIO storage | Hardhat |

<Tip>
  **Template selection:**

  ```bash theme={null}
  # Interactive mode shows all available templates
  npm create scaffold-hbar@latest

  # Or specify directly
  npm create scaffold-hbar@latest -- --template payments-scheduler
  npm create scaffold-hbar@latest -- --template cross-chain-dca
  npm create scaffold-hbar@latest -- --template hedera-demo
  ```
</Tip>

<Note>
  Templates are maintained in the [scaffold-hbar repository](https://github.com/hedera-dev/scaffold-hbar) as separate branches (`templates/*`). The CLI fetches templates at runtime, so you always get the latest version.
</Note>

***

## External Templates

Beyond the built-in templates, Scaffold HBAR supports **external templates** from any GitHub repository. This allows the community to create and share specialized templates.

### Using External Templates

Specify an external template using the `owner/repo` or `owner/repo#branch` format:

```bash theme={null}
# Use the main branch
npm create scaffold-hbar@latest -- --template hedera-dev/template-hedera-lz-app

# Use a specific branch
npm create scaffold-hbar@latest -- --template hedera-dev/template-hedera-lz-app#main
```

The CLI fetches the template via [giget](https://github.com/unjs/giget), so any public GitHub repository can serve as a template.

### Featured: LayerZero on Hedera Template

The [template-hedera-lz-app](https://github.com/hedera-dev/template-hedera-lz-app) is a comprehensive tutorial template for building cross-chain applications using LayerZero V2 on Hedera.

```bash theme={null}
npm create scaffold-hbar@latest my-lz-app -- --template hedera-dev/template-hedera-lz-app
```

**What you'll build:**

| Chapter | Topic | Description |
| - | - | - |
| 1 | Cross-Chain OFT | Send native ETH from Base Sepolia to Hedera as an HTS-wrapped token |
| 2 | Cross-Chain Vault | ERC4626 vault with omnichain deposits and share token redemptions |
| 3 | ETF Strategy | Auto-investing vault that swaps deposits into a 50/50 HBAR + HUSTLERS basket via SaucerSwap |

**Architecture:**

```
BASE (Spoke)                           HEDERA (Hub)
┌─────────────────┐                   ┌─────────────────────────┐
│ MyNativeOFT     │◄──── LayerZero ──►│ MyHTSConnector          │
│ Adapter         │                   │ (wraps ETH as HTS)      │
└─────────────────┘                   └─────────────────────────┘
```

<Note>
  This template uses **pnpm** (not Yarn) and requires testnet funds on both Base Sepolia and Hedera Testnet. See the [template README](https://github.com/hedera-dev/template-hedera-lz-app) for complete setup instructions.
</Note>

### Creating Your Own Template

Any GitHub repository can be used as an external template. To make your template compatible:

1. **Structure** — Use a monorepo layout with `packages/` for contracts and frontend
2. **Manifest** (optional) — Add a `template.json` to specify capabilities:

```json theme={null}
{
  "create-scaffold-hbar": {
    "capabilities": {
      "frontend": ["nextjs-app"],
      "solidityFramework": ["hardhat"],
      "packageManager": ["pnpm", "yarn"]
    },
    "defaults": {
      "frontend": "nextjs-app",
      "solidityFramework": "hardhat"
    }
  }
}
```

3. **Share** — Users can scaffold with `npm create scaffold-hbar@latest -- --template your-org/your-repo`

***

## Project Structure

A scaffolded project has this structure:

```
my-hedera-dapp/
├── packages/
│   ├── foundry/          # OR hardhat/ (Solidity contracts)
│   │   ├── contracts/    # Smart contract source files
│   │   ├── script/       # Deployment scripts (Foundry)
│   │   ├── deploy/       # Deployment scripts (Hardhat)
│   │   └── test/         # Contract tests
│   │
│   └── nextjs/           # Frontend application
│       ├── app/          # Next.js App Router pages
│       ├── components/   # React components
│       ├── contracts/    # Auto-generated contract ABIs
│       ├── hooks/        # Custom React hooks
│       └── services/     # Web3 service utilities
│
├── package.json          # Workspace configuration
└── yarn.lock             # or package-lock.json if you chose npm
```

### Key Features

**Auto-generated Contract Types**

After deploying contracts, ABIs are automatically generated to `packages/nextjs/contracts/deployedContracts.ts`. This provides full TypeScript support when interacting with your contracts.

**Pre-built Hooks**

The frontend includes scaffold hooks for common operations:

```typescript theme={null}
import { useScaffoldReadContract, useScaffoldWriteContract } from "~~/hooks/scaffold-hbar";

// Read contract state
const { data: greeting } = useScaffoldReadContract({
  contractName: "YourContract",
  functionName: "greeting",
});

// Write to contract
const { writeContractAsync } = useScaffoldWriteContract({
  contractName: "YourContract",
});

await writeContractAsync({
  functionName: "setGreeting",
  args: ["Hello, Hedera!"],
});
```

**Hedera-Optimized Configuration**

Projects come pre-configured with:

* Hashio JSON-RPC endpoints for Testnet and Mainnet
* Mirror Node API integration
* Proper gas estimation for Hedera's fee model
* RainbowKit with Hedera wallet support

***

## Common Commands

Examples use Yarn. With npm, run `npm run <script>` instead.

| Command | Description |
| - | - |
| `yarn foundry:chain` / `yarn hardhat:chain` | Start local development chain |
| `yarn foundry:deploy` / `yarn hardhat:deploy` | Deploy contracts |
| `yarn next:start` | Start Next.js frontend |
| `yarn next:build` | Build frontend for production |
| `yarn lint` | Run linters on all packages |
| `yarn format` | Format code with Prettier |
| `yarn foundry:test` / `yarn hardhat:test` | Run contract tests |

***

## Deploying to Testnet

1. **Get testnet HBAR** from the [Hedera Portal Faucet](https://portal.hedera.com/faucet)

2. **Configure your account**:

<Tabs>
  <Tab title="Foundry">
    ```bash theme={null}
    # Generate a new account
    yarn foundry:account:generate

    # Or import an existing key
    yarn foundry:account:import
    ```

    Set your account alias in `packages/foundry/.env`:

    ```bash theme={null}
    ACCOUNT=your_keystore_alias
    ```
  </Tab>

  <Tab title="Hardhat">
    ```bash theme={null}
    # Generate a new account
    yarn hardhat:account:generate

    # Or import an existing key
    yarn hardhat:account:import
    ```

    Set your private key in `packages/hardhat/.env`:

    ```bash theme={null}
    DEPLOYER_PRIVATE_KEY=your_private_key
    ```
  </Tab>
</Tabs>

3. **Deploy to testnet**:

```bash theme={null}
yarn foundry:deploy --network hedera_testnet
# or
yarn hardhat:deploy --network hederaTestnet
```

4. **Verify contracts** (optional):

```bash theme={null}
yarn foundry:verify:testnet 0xYourContractAddress contracts/YourContract.sol:YourContract
# or
yarn hardhat:verify:testnet
```

***

## Hedera Skills (AI-Assisted Development)

All scaffolded projects include [Hedera Skills](https://github.com/hedera-dev/hedera-skills) by default—a collection of AI coding assistant skills that help you build on Hedera faster.

**What's included:**

* **Agent prompts** — Pre-configured prompts for Cursor, Claude Code, and other AI assistants
* **Code generation skills** — Hedera-specific patterns for HTS, HCS, smart contracts, and more
* **Documentation context** — Embedded Hedera docs for accurate AI responses

Skills are installed automatically during scaffolding via:

```bash theme={null}
npx skills add hedera-dev/hedera-skills --all
```

<Tip>
  To skip Hedera Skills installation (e.g., for CI pipelines), use:

  ```bash theme={null}
  npm create scaffold-hbar@latest -- --yes --skip-hedera-skills
  ```
</Tip>

***

## Ecosystem

<CardGroup cols={2}>
  <Card title="Scaffold UI" icon="palette" href="/solutions/tools/scaffold-hbar/scaffold-ui">
    Shared React components and hooks for Hedera dApps, plus an MCP server for AI-assisted development
  </Card>

  <Card title="Hedera Skills" icon="wand-magic-sparkles" href="https://github.com/hedera-dev/hedera-skills">
    AI coding assistant skills for Hedera development
  </Card>
</CardGroup>

***

## Resources

* [GitHub: create-scaffold-hbar](https://github.com/hedera-dev/create-scaffold-hbar) — CLI source and issues
* [GitHub: scaffold-hbar](https://github.com/hedera-dev/scaffold-hbar) — Templates repository
* [Hedera Portal](https://portal.hedera.com/) — Account creation and testnet faucet
* [HashScan](https://hashscan.io/) — Block explorer for Hedera