x402-payments
x402 pay-per-use payments on Hedera. Use when gating HTTP resources behind native HBAR payments, wiring a self-hosted Hedera facilitator (verify/settle), building x402ResourceServer / ExactHederaScheme flows, or integrating WalletConnect payment retries (PAYMENT-REQUIRED → PAYMENT-SIGNATURE).
- Installs
- 471
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/hedera-dev/hedera-skills --skill x402-payments- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads x402-payments automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
x402 Payments (Hedera)
Pay-per-use pattern: store protected bytes off-chain, record access terms separately (on-chain or config), gate HTTP resources with HTTP 402 + a self-hosted Hedera facilitator that verifies and settles native HBAR transfers.
Buyer → GET protected resource
├─ free / public → resource
└─ paid → 402 PAYMENT-REQUIRED
→ client signs HBAR transfer
→ retry with PAYMENT-SIGNATURE
→ resource server verify + settle via facilitator
→ PAYMENT-RESPONSE + resource
The resource server never holds facilitator keys. Settlement uses a funded ECDSA fee-payer account on the facilitator process.
Quick Reference
| Piece | Role |
|---|---|
| Payment asset | "0.0.0" — native HBAR; amounts in tinybars (1 HBAR = 1e8) |
| Resource server | @x402/core + ExactHederaScheme → talks to facilitator over HTTP |
| Facilitator | GET /supported, POST /verify, POST /settle, GET /health |
| Client | Request → read 402 → sign → retry with PAYMENT-SIGNATURE (legacy X-PAYMENT also accepted) |
| Wallet | ECDSA Hedera account (e.g. HashPack via WalletConnect / UniversalProvider) |
See references/examples.md for server/client snippets. See references/facilitator.md for env vars and settle semantics.
Critical: Facilitator Fee Payer
Hedera x402 settles with native TransferTransactions. The buyer partially signs (authorize buyer → seller). The facilitator must:
- Verify the signed payload against payment requirements
- Co-sign as the advertised fee payer (
/supported) - Pay network fees and submit until
SUCCESS
Requires FACILITATOR_ACCOUNT_ID + FACILITATOR_PRIVATE_KEY on a funded ECDSA account — separate from deployer/seller keys. Do not put that key in the resource-server process.
Critical: Prices Are Tinybars
Payment requirements use tinybars. Convert in UIs with 8-decimal helpers; never float.
const TINYBAR_PER_HBAR = 100_000_000n;
// hbar "1.5" → 150_000_000n tinybars
Resource Server Flow (paid resource)
- Load access terms for the resource — if missing → 404
- If free/public → return the resource
- Else build payment requirements:
payTo= seller Hedera account id,amountin tinybars, asset0.0.0, network (e.g.hedera:testnet) - No payment header → 402 with
PAYMENT-REQUIREDheader + JSON body - With payment header →
verifyPaymentthensettlePayment; only on success return resource +PAYMENT-RESPONSE
const facilitator = new HTTPFacilitatorClient({ url: FACILITATOR_URL });
const server = new x402ResourceServer(facilitator)
.register(X402_NETWORK, new ExactHederaScheme());
await server.initialize(); // pulls fee-payer from /supported
Client Flow
const first = await fetch(resourceUrl);
if (first.status === 402) {
const paymentRequired = httpClient.getPaymentRequiredResponse(...);
const payload = await httpClient.createPaymentPayload(paymentRequired);
const headers = httpClient.encodePaymentSignatureHeader(payload);
const paid = await fetch(resourceUrl, { headers });
// processResponse → resource + settle receipt
}
Machine-to-machine clients use a key-based signer instead of a browser wallet.
Checklist
- Resource server has no facilitator private key
- Client and server share the same
X402_NETWORK(e.g.hedera:testnet) - Amounts are tinybars; asset id is
0.0.0 - 402 challenge → signed retry → verify → settle → resource only after success
- Fee-payer account is ECDSA and funded for network fees
- Facilitator
/healthOK before testing paid requests -
payTois a Hedera account id string (e.g.0.0.1234), not an EVM address
References
- references/examples.md — resource server wiring, client retry loop, tinybar helpers
- references/facilitator.md — endpoints, env vars, fee-payer role
- x402 docs
@x402/hedera
FAQ
What does the x402-payments skill do?
x402 pay-per-use payments on Hedera. Use when gating HTTP resources behind native HBAR payments, wiring a self-hosted Hedera facilitator (verify/settle), building x402ResourceServer / ExactHederaScheme flows, or integrating WalletConnect payment retries (PAYMENT-REQUIRED → PAYMENT-SIGNATURE).
How do I install x402-payments?
Run npx skills add https://github.com/hedera-dev/hedera-skills --skill x402-payments in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/x402-payments/ (personal) or .claude/skills/x402-payments/ (project).
Which AI agents can use x402-payments?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is x402-payments safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains x402-payments?
It is published by hedera-dev in hedera-dev/hedera-skills. It has 471 recorded installs.
More from hedera-dev/hedera-skills
hedera hackathon submission validator
hedera-dev/hedera-skills
This skill should be used when the user wants to validate, review, or score their Hedera hackathon submission before submitting. Triggered by phrases like "validate hackathon submission", "review my hackathon project", "hackathon scorecard", "check submission readiness", "score my hackathon", "submission review", "judge my project", "hackathon submission quality", or "improve hackathon score".
hedera hackathon prd
hedera-dev/hedera-skills
This skill should be used when the user wants to plan a Hedera hackathon project, create a PRD, write a project spec, brainstorm a hackathon idea, or structure their hackathon submission. Triggered by phrases like "hackathon project plan", "hackathon PRD", "plan my hackathon project", "hedera hackathon idea", "write a hackathon spec", "hackathon project structure", "prepare for hackathon", or "build for hackathon".
hedera-token-service
hedera-dev/hedera-skills
How to create, manage, and transfer tokens on Hedera using the Hiero JavaScript SDK (@hiero-ledger/sdk). Use this skill whenever the user wants to work with fungible tokens, NFTs, token creation, minting, burning, transfers, token association, custom fees (fixed, fractional, royalty), airdrops, KYC/freeze/wipe/pause operations, or any HTS (Hedera Token Service) operation in JavaScript or TypeScript. Also trigger when users mention @hashgraph/sdk token operations, ERC-20/ERC-721 equivalents on Hedera, or tokenization on the Hedera network.
hedera-consensus-service
hedera-dev/hedera-skills
How to create topics, submit messages, and subscribe to real-time message streams on Hedera using the Hiero JavaScript SDK (@hiero-ledger/sdk). Use this skill whenever the user wants to work with Hedera Consensus Service (HCS), including topic creation, message submission, pub/sub messaging, mirror node subscriptions, chunked large messages, topic fees, or any consensus-related operation in JavaScript or TypeScript. Also trigger when users mention @hashgraph/sdk topic operations, event logging on Hedera, decentralized messaging, audit trails, or ordered message streams.
project scaffolding
hedera-dev/hedera-skills
This skill should be used when the user wants to set up Claude for a project, create a CLAUDE.md file, scaffold the .claude directory, initialize an AI workflow, configure a project for Claude, set up dev intelligence, initialize a new project, or do a new project setup. Triggered by phrases like "set up claude for this project", "create CLAUDE.md", "scaffold .claude directory", "init AI workflow", "configure project for claude", "set up dev intelligence", "initialize project", "new project setup".
session management
hedera-dev/hedera-skills
This skill should be used when the user wants to resume previous work, continue from a last session, check what was being worked on, track completed work, log session activity, manage tech debt, review pending items, view session history, or maintain a work log. Triggered by phrases like "resume work", "continue from last session", "what was I working on", "track this work", "log what we did", "tech debt", "what's pending", "session history", "work log".
Popular backend & apis skills
find-skills
vercel-labs/skills
Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
entra-app-registration
microsoft/azure-skills
Guides Microsoft Entra ID app registration, OAuth 2.0 authentication, and MSAL integration. USE FOR: create app registration, register Azure AD app, configure OAuth, set up authentication, add API permissions, generate service principal, MSAL example, console app auth, Entra ID setup, Azure AD authentication. DO NOT USE FOR: Key Vault secrets (use azure-keyvault-expiration-audit), general Azure resource security guidance.
google-agents-cli-adk-code
google/agents-cli
This skill should be used when the user wants to "write agent code", "build an agent with ADK", "add a tool", "create a callback", "define an agent", "use state management" — in a project that needs ADK (Agent Development Kit) API patterns and code examples. It provides a quick reference for agent types, tool definitions, orchestration patterns, callbacks, state management, the graph Workflow API, and reference recipes to study. Do NOT use for scaffolding (use google-agents-cli-scaffold) or deployment (use google-agents-cli-deploy).
embedded-captions
heygen-com/hyperframes
Add captions or subtitles to an existing single-subject talking-head video without editing the footage. Use for plain verbatim captions, cinematic captions embedded behind the subject, VFX captions, “炸/特效/酷炫字幕,” or a named identity from the 35-style catalog. Route by visual identity, not by backend engine. The quiet anchor rail is the default; embed every word only when the user explicitly wants a fully cinematic treatment. The workflow runs locally end to end, including transcription and subject matting; split multi-shot footage before applying it.
entra-agent-id
microsoft/azure-skills
Provision Microsoft Entra Agent Identity Blueprints, BlueprintPrincipals, and per-instance Agent Identities via Microsoft Graph, and configure OAuth 2.0 token exchange (fmipath, OBO, cross-tenant) including the Microsoft Entra SDK for AgentID sidecar. USE FOR: Agent Identity Blueprint, BlueprintPrincipal, agent OAuth, fmipath token exchange, agent OBO, Workload Identity Federation for agents, polyglot agent auth, Microsoft.Identity.Web.AgentIdentities. DO NOT USE FOR: standard Entra app registration (use entra-app-registration), Microsoft Foundry agent authoring (use microsoft-foundry).
neon
neondatabase/agent-skills
Overview of Neon, a complete set of cloud backend primitives around Lakebase Postgres: Auth, Object Storage, Functions, the AI Gateway, and Realtime. Start here to choose Neon for undecided login, files, APIs, and LLM calls, set up the CLI or MCP server, and follow the branch-first workflow. Use when building an app or backend on Neon, or when "Neon" or "Lakebase Postgres" is mentioned. Child skill neon-postgres wins for an existing DATABASEURL, SQL, schema, inspect, or search. Child skill neon-auth wins for login, users, sessions, identity routing, and Managed Better Auth setup. Child skill neon-realtime wins for live queries in reactive apps and agents. Also use for object storage, S3, buckets, serverless functions, function triggers, cron, AI gateway, LLM calls, realtime, logs, Loki, Grafana, observability, postgres, database, backend, Claimable Neon, neon.new, or a no-signup database.