The infrastructure for
x402-paid AI services.
Build AI services that can charge other AI agents per request using x402 on Hedera.
One decorator. Mirror Node verification. HCS receipts. Compliance certification. Production-ready architecture.
API Keys Break
Your agent calls a premium API. The key expired. The subscription lapsed. The billing system was built for humans, not software.
Charging Is Too Hard
You built an MCP tool worth charging for. You're using Stripe, manual invoicing, or giving it away because billing takes weeks to integrate.
Agents Can't Trade
Autonomous agents need to exchange value with each other. No payment primitive exists at the HTTP layer. Every agent is blocked by human auth.
HACK replaces all of this with three lines of Python.
@PaidEndpoint(price="0.5 HBAR")
async def my_service(request: Request):
return {"result": "paid access granted"}Why x402?
HTTP already has a payment status code. We use it.
HTTP 402 Payment Required has existed since 1991. x402 is the protocol that makes it real — payment metadata travels in standard HTTP headers, with no new auth layer, no accounts, no subscriptions.
An AI agent calls an endpoint. Gets a 402. Pays. Gets the result. The entire transaction settles in ~3 seconds on Hedera testnet.
- No new auth layer — standard HTTP semantics.
- Payment metadata in response body + reply headers.
- Machine-verifiable via public Mirror Node — no oracles.
# Request
GET /api/premium-query HTTP/1.1
# Response (402)
HTTP/1.1 402 Payment Required
Content-Type: application/json
{
"quote_id": "3f8a1c2d-9e4b-4a7c-b820-...",
"receiver": "0.0.7972536",
"amount_hbar": 0.5,
"memo": "hack-payment",
"expires_in": 600
}
# Retry with proof (200)
GET /api/premium-query HTTP/1.1
X-Payment-Token: 0.0.7972536@1700000000.000000000
X-Quote-Id: 3f8a1c2d-9e4b-4a7c-b820-...Why Hedera?
Deterministic fees. Public verifiability. On-chain audit trails.
3-Second Finality
Payment verified before your UI updates
Fixed Fees
Agents calculate cost before calling. No gas surprises.
Mirror Node API
Public payment verification. No oracle. No middleware.
HCS Receipts
Tamper-proof, timestamped on-chain audit trail for every payment
Hedera Agent Kit
AI agents as first-class citizens in the Hedera ecosystem
x402 Protocol
Zero new auth layer. Payment in standard HTTP headers.
How it fits together
A thin middleware wraps your endpoint, a state machine guards every payment, and Hedera provides the settlement and audit trail.
| Component | Description | Source |
|---|---|---|
| hack/toolkit/decorators.py | @PaidEndpoint decorator + middleware | Source |
| hack/toolkit/state_machine.py | 6-state payment lifecycle | Source |
| hack/verifier/mirror.py | Mirror Node verification client | Source |
| hack/receipt/hcs.py | HCS topic receipt publisher | Source |
| hack/compliance/rules/ | 5 built-in compliance rules | Source |
| hack/certification/service.py | Report + soulbound certificate | Source |
Built for production from day one
Payment State Machine
Six explicit states. Zero replay attacks.
Every payment moves through 6 explicit states. Replay attacks are rejected at the state level. Grant windows expire. Duplicate transaction IDs are detected and flagged. Nothing leaks.
Compliance Engine
Rules you can trust, certificates you can verify.
5 built-in compliance rules. Pluggable architecture. Every payment can be certified on-chain via HCS. Compliance reports are machine-readable and exportable.
- Replay protection
- Payment expiry
- Idempotency
- Settlement validation
- Quote lifecycle
{
"service_name": "my-mcp-server",
"score": 92,
"passed": true,
"x402_rules": [
{ "id": "replay_protection", "passed": true },
{ "id": "payment_expiry", "passed": true },
{ "id": "idempotency", "passed": true },
{ "id": "settlement", "passed": true },
{ "id": "quote_lifecycle", "passed": true }
],
"certified_at": 1753228800,
"hcs_topic": "0.0.9702133"
}Dependency Injection
Swap any layer without touching business logic.
Every service is injectable. Swap the QuoteStore, the verifier, or the receipt service without touching business logic. Tested with real unit tests — 31 passing.
Tests run on every commit via GitHub Actions.
# service_container.py
class ServiceContainer:
lifecycle: PaymentLifecycle
verifier: MirrorNodeVerifier
certifier: CertificationService
quotes: QuoteStore
receipts: HCSReceiptService
# Swap any implementation:
container.verifier = InMemoryVerifier() # for tests
container.receipts = NoOpReceiptService() # for local devHedera Agent Kit
LangChain agent, on-chain, behind an x402 gate.
The premium endpoint is backed by a real Hedera Agent Kit agent. Account queries, HCS topics, HTS tokens — all accessible via natural language through the paid API.
> "What is my HBAR balance?"
[tool] hedera.mirror.account_info()
[tool] hedera.hcs.topic_info(id="0.0.9702133")
agent: "Your account currently holds 1,204.7183 ℏ.
The associated HCS topic has 42 receipts."See it run
The Playground is a live, three-panel console over the entire backend.
- Every backend endpoint, live
- Real Mirror Node verification
- Real HCS receipt on Hedera testnet
- Every response rendered as structured cards
- Step-by-step x402 payment modal
Open source infrastructure
HACK is MIT licensed. The toolkit, the compliance engine, the state machine, and the Hedera integrations are all importable into your own project.
# Coming soon
pip install hack-hederagit clone https://github.com/De-real-iManuel/Hedera-Agent-Commerce-Kit
./scripts/install.sh