DEV Community

Paul Spread
Paul Spread

Posted on

One Command to Hedera: An AI Agent Passport You Can Scaffold in an Afternoon

#hedera #web3 #typescript #blockchain

npm create scaffold-hbar and a few minutes later you have an AI-agent passport live on Hedera testnet: an ERC-721 passport NFT, an append-only event log, snapshot attestations, a Hono API, and a tiny UI — tests green out of the box, every tx verifiable on Hashscan.

We built this for the Hedera Scaffold-HBAR Template Bounty. Here's the what and the why.

Agent passport on Hedera

New-blockchain onboarding has a predictable curve: read the docs, fight the account model, fight the keys, and three hours later you still haven't deployed a contract. Hedera is worth the climb — predictable fees, fast finality — but the climb is still a climb. Scaffold templates flatten it.

What the template gives you 

npm create scaffold-hbar@latest my-agent \
  -- --template spreadzp/template-hedera-agent-passport
cd my-agent && npm install && npm test     # 5/5 contract tests pass
npm run deploy                             # live on Hedera testnet
npm run dev                                # UI + API on :3000
Enter fullscreen mode Exit fullscreen mode

Out of the box:

  • AgentPassportNFT — ERC-721 passport: mint with tier + metadata URI, revoke, and attest content snapshots bound to snapshotHash.
  • AgentEventLog — append-only, HCS-style event stream: every issuance and attestation emits a sequenced topic event only a designated writer may append.
  • Hono API + minimal UI — mint, attest, and read passport state from the browser. Writes go through your operator key; reads via the mirror node are free.
  • DEPLOYMENTS.md — every contract and tx auto-linked to Hashscan.

Pipeline: create → install → test → deploy → smoke

Under the hood

Top: a minimal UI → Hono API → two contracts on Hedera testnet — AgentPassportNFT and AgentEventLog — with the mirror node handling free reads.

Three design choices worth stealing:

  1. Standard EVM tooling, zero Hedera-specific surprises. Hardhat + viem over the JSON-RPC relay. Hedera differences surface only where real (account IDs vs EVM addresses — documented in AGENTS.md).
  2. Operator pays gas; the user just calls. The API holds the testnet operator key server-side — minting is one POST, no wallet UX needed for a demo. Production swaps this for real wallet signing.
  3. Writes cost HBAR; reads cost nothing. ownerOf, tierOf, verifySnapshot go through the mirror node — an attestation written once can be re-verified forever, free.

Architecture

Passport NFT verified

Try it, then verify it

Everything runs on Hedera testnet now — the template's DEPLOYMENTS.md links every claim to a Hashscan page:

Attest once, verify free

Starter kit

Why a scaffold, not a library

Libraries optimize for people who've already decided to build on your chain. Scaffolds win the undecided: one command and "evaluate Hedera" becomes a running dApp with real transactions before your coffee is cold. That's the bet the Scaffold-HBAR bounty is making — and why we entered with a template that does something non-trivial (verifiable agent identity) instead of another counter contract.

Next on our Hedera track: wiring the same passport contracts into the AgentBadge server as a second chain alongside Arc — the passport format is identical by design.

MIT licensed — fork it, break it, ship something better.

Top comments (0)