Hedera Agent Kit + x402 payments example

Multiple AI Bounty Feedbacks request providing an example on using HAK with x402.
Referring to:
- #898
- #894
- #903
- will fill rest after identifying

---

## Proposed example scope

The example should cover the full end-to-end flow that builders are consistently hitting friction on:

1. User connects a Hedera testnet wallet
2. User triggers an action that requires payment
3. Server returns an x402 \`402 Payment Required\` challenge
4. User signs the Hedera payment
5. Server verifies and settles the x402 payment
6. After settlement, server executes Agent Kit tools (e.g. \`submit_topic_message_tool\`, \`mint_fungible_token_tool\`)
7. App returns HashScan links for the payment, HCS record, token, and account

Stack: Next.js App Router + \`@hashgraph/hedera-agent-kit\` + \`@x402/core\` + \`@hashgraph/hedera-wallet-connect\`

---

## Extended scope: x402 + MCP server pattern

Based on feedback from @Utkal059 (#903 — CapScribe, Week 3 bounty), the example should also cover the **x402 payment-gated MCP server** pattern, which is a common architecture for agent-driven micropayment flows:

1. **x402 middleware wired to an MCP server** — tool calls are blocked until a confirmed HBAR micropayment is received; the example should show how to configure the middleware gate so that no tool executes before payment verification succeeds.
2. **Payment receipt verification before tool execution** — demonstrate how to validate the x402 payment receipt server-side and pass the verified context into Agent Kit tool handlers.
3. **Async payment callbacks inside an agent loop** — cover how to handle payment verification callbacks in an async agent loop (e.g. LangGraph ReAct), including how to pause the loop, await settlement confirmation, and resume tool execution after the callback resolves.
4. **x402 + HCS (Hedera Consensus Service) integration** — show how HCS topic messages can be gated behind x402 payments, with the middleware verifying HBAR micropayments before submitting messages to a topic.

This pattern is particularly relevant for Week 3-style bounties and significantly reduces the barrier for builders trying to build payment-gated agent services on Hedera.

---

## Troubleshooting checklist to include

Builders consistently get stuck on surrounding setup rather than the Agent Kit itself. The example should include a troubleshooting section covering the most common blockers:

**Errors seen in the wild:**
- HashPack: \`No applicable accounts\`
- Wallet signing: \`list is locked\`
- x402 settlement: \`TOKEN_NOT_ASSOCIATED_TO_ACCOUNT\`
- Browser/API: \`The provided x402 payment could not be verified.\`

**Pre-flight checklist:**
- [ ] Operator account is funded on testnet
- [ ] Wallet account is funded on testnet
- [ ] Receiver account is associated with the payment token
- [ ] Payer account holds the payment token
- [ ] Correct testnet/mainnet config is set
- [ ] All required environment variables are present and valid
- [ ] Valid fee payer is configured
- [ ] WalletConnect session is active and connected to the correct network

Ref: feedback from @rubayet211 (ProofMint Hedera) — #1019
Ref: feedback from @Utkal059 (CapScribe) — #903

Start by locating the example entry points for the Next.js App Router, Agent Kit, x402, and WalletConnect, then trace the proposed payment-to-tool flow. Done means the example covers wallet connection, payment verification and settlement, gated Agent Kit/MCP actions, HashScan links, async callbacks, HCS integration, and the listed troubleshooting checklist.

Written by the indexing model from the issue text.