Hedera Invoice Settlement Agent

Week 2 Hedera AI Agent Bounty submission candidate.

Public repository: https://github.com/trungcodeer/hedera-invoice-settlement-agent

Hosted demo: https://hedera-week2-agent.vercel.app/

Backup static demo: https://trungcodeer.github.io/hedera-invoice-settlement-agent/

Hedera Agent Kit feedback issue: hashgraph/hedera-agent-kit-js#864

Live testnet evidence: LIVE_TESTNET_EVIDENCE.md

Deployment evidence: DEPLOYMENT_EVIDENCE.md

Requirements matrix: REQUIREMENTS_MATRIX.md

Architecture diagram: ARCHITECTURE.md

Judging scorecard: JUDGING_SCORECARD.md

Professional demo video: demo-video/hedera-invoice-settlement-demo.mp4

Final form copy: SUBMIT_THIS.md

Mirror node evidence:

• Topic: https://testnet.mirrornode.hedera.com/api/v1/topics/0.0.9053700
• HCS messages: https://testnet.mirrornode.hedera.com/api/v1/topics/0.0.9053700/messages
• Payment transaction: https://testnet.mirrornode.hedera.com/api/v1/transactions/0.0.9047081-1779724163-012635803

This app demonstrates an enterprise invoice settlement workflow built with the Hedera Agent Kit:

• Custom Agent Kit plugin: invoice_policy_check_tool
• Hedera Agent Kit non-query tools:
  • create_topic_tool
  • submit_topic_message_tool
  • transfer_hbar_tool
• Commercial transaction path: policy-approved HBAR payment to a vendor account
• Audit trail: approval and payment receipt messages written to Hedera Consensus Service
• Enterprise controls: vendor registry, purchase order, department owner, spending limit, recipient-account match, and JSON/CSV invoice import

Judge Walkthrough

1. Open the hosted demo: https://hedera-week2-agent.vercel.app/
2. Watch demo-video/hedera-invoice-settlement-demo.mp4 for the 37-second reviewer walkthrough.
3. Review the Week 2 requirement coverage and live testnet evidence sections.
4. Review the Judging Scorecard section for the 25/25/20/15/15 scoring coverage.
5. In Settlement Request, choose a vendor profile, import the JSON/CSV sample, or use a scenario preset.
6. Click Run agent in mock mode to inspect the deterministic 5-step workflow and policy checks.
7. Download the settlement report to inspect the exportable AP audit package.
8. Open the mirror-node links shown in the live evidence section for the completed Vercel testnet run.
9. Review REQUIREMENTS_MATRIX.md for a requirement-by-requirement evidence map.

Run Locally

npm install
npm run dev

Open http://localhost:3000.

The default mode is deterministic mock execution. It is useful for judging the workflow without spending testnet HBAR.

Verification

npm run lint
npm run typecheck
npm run test
npm run build
npm run smoke
npm run verify:live-guard
npm run verify:security
npm run verify:a11y
npm run verify:public
npm run verify:evidence

npm run smoke starts the production server on a temporary local port, loads the app page, and calls the mock agent API. It passes only if the API returns the expected 5-step workflow.

npm run test runs Vitest unit coverage for the enterprise policy checks, scenario presets, settlement report export, invoice import parsing, invoice validation, and public live-demo guard.

npm run verify:live-guard starts a local production server with public live-demo lock enabled and confirms an oversized live payload is forced to the fixed 0.001 HBAR recipient before any live transaction can run.

npm run verify:security scans committed files for common secret patterns and runs npm audit --audit-level=high --omit=dev.

npm run verify:a11y runs an axe accessibility scan on the hosted demo and verifies keyboard focus starts at the skip link.

npm run verify:public opens the hosted Vercel demo, confirms the live testnet evidence is visible, runs the agent flow, and writes screenshots/public-demo-verified.png.

npm run verify:evidence checks the hosted demo HTML, GitHub repository visibility, and Hedera mirror node evidence for the live Vercel testnet run.

After configuring Hedera testnet credentials, run:

npm run live:testnet

This starts the production server, calls the live /api/agent route, and passes only if Hedera testnet returns five successful workflow steps.

Hosted Demo

The primary Vercel deployment hosts the Next.js app and server API route. Live mode is configured with a disposable Hedera testnet operator and a public-demo guard that locks recipient and amount to a fixed 0.001 HBAR testnet payment. The Node deployment also sends security headers for content type sniffing, framing, referrer policy, browser permissions, and a restrictive CSP.

The GitHub Pages deployment is kept as a static backup. If the server API route is unavailable, the UI falls back to a deterministic client-side mock trace so reviewers can still inspect the full 5-step agent workflow. Both demos show live Hedera testnet evidence from a completed Agent Kit run, with mirror node links for the topic, HCS messages, and payment transaction.

Live Testnet Mode

Copy .env.example to .env.local and fill in:

ACCOUNT_ID="0.0.xxxxx"
PRIVATE_KEY="302e..."
ALLOW_LIVE_TRANSACTIONS="true"
MAX_INVOICE_HBAR="0.25"

Then choose Live testnet in the UI and use a valid Hedera testnet recipient account. The live workflow creates an HCS audit topic, writes the approval payload, transfers HBAR, and writes the payment receipt.

Bounty Submission Notes

Submission form fields to prepare:

• Project name: Hedera Invoice Settlement Agent
• GitHub URL: public repository for this app
• Demo URL: hosted Next.js app
• Demo video: demo-video/hedera-invoice-settlement-demo.mp4
• Wallet address: Hedera wallet/account for HBAR payout
• Feedback link: GitHub issue created from the Hedera Agent Kit feedback template

The hosted URL must stay available for at least 90 days after submission.

See SUBMIT_THIS.md for final form copy, BOUNTY_SUBMISSION.md for the longer submission draft, JUDGING_SCORECARD.md for scoring evidence, REQUIREMENTS_MATRIX.md for requirement-by-requirement evidence, ARCHITECTURE.md for the system diagram, and LIVE_TESTNET_SETUP.md for live testnet setup details.