nativ3ai
hermes-payguard
Safe-by-design USDC and x402 payment plugin for Hermes Agent with human-in-the-loop approval.
Repository last updated Mar 20, 2026
Overview
Hermes PayGuard is a security-focused plugin that enables Hermes Agents to handle USDC and x402 payments through a gated execution model. It separates payment preparation from execution by requiring an out-of-band human approval stamp for transfers exceeding user-defined policy limits.
The system supports Circle developer-controlled wallets, cross-chain CCTP transfers, and automated x402 micropayments for paid HTTP fetches. This architecture ensures that while agents can stage financial intents, they cannot unilaterally move significant funds without explicit operator consent.
PayGuard is designed for operators who want to give their agents payment capabilities while maintaining strict control over fund movements. It is ideal for scenarios involving vendor payments, cross-chain transfers, and paid API access.
Highlights
- Enforces human-in-the-loop approval for high-value USDC transfers
- Supports Circle CCTP for cross-chain USDC routing and execution
- Automates x402 micropayments below configurable policy thresholds
- Separates payment intent preparation from execution
- Provides a local audit ledger and replayable intent state
Features
Gated Execution Model
Payment tools re-check policy and approval state before moving money. Larger transfers require a separate human approval stamp via the CLI.
Circle Integration
Supports developer-controlled and user-controlled USDC transfers, including CCTP cross-chain transfers with route quoting and attestation-aware execution.
x402 Micropayments
Automates paid HTTP fetches for micropayments below a configurable threshold, with explicit operator approval for over-limit requests.
Policy-Driven Configuration
Define per-payment limits, allowed recipients, CCTP destination chains, and x402 hosts in a YAML policy file.
CLI Tooling
Commands for installing the plugin, initializing policy, running diagnostics, and approving payment intents.
Installation
Commands are reproduced exactly as published by the project maintainers. Always check the upstream repository for the current instructions.
git clone https://github.com/nativ3ai/hermes-payguard.git
mkdir -p ~/.hermes/plugins
ln -sfn /path/to/hermes-payguard ~/.hermes/plugins/hermes-payguard
pip install -e /path/to/hermes-payguardpip install hermes-payguardgit clone https://github.com/nativ3ai/hermes-payguard.git
cd hermes-payguard
pip install -e .
payguard install-plugin
payguard init-policy
payguard doctorRequirements
- Python 3.8+
- Hermes Agent installed
- Circle API key and wallet credentials for USDC transfers
- EVM private key for x402 payments
- CCTP executor URL for cross-chain transfers (optional)
How it's built
Hermes PayGuard is a standalone Hermes plugin written in Python. It does not patch Hermes core; instead, it installs as an add-on and registers payment tools via the plugin discovery mechanism. The repository is organized with a hermes_payguard/ package containing modules for Circle API integration (circle.py), CCTP execution (cctp.py), policy enforcement (policy.py), and x402 handling (x402_exec.py).
The plugin uses a local audit ledger (ledger.py) to track payment intents and their approval state. Approval stamps are created via the CLI command payguard approve <intent-id>, which is external to the agent loop. For CCTP transfers, the plugin interacts with a separate executor service via CCTP_EXECUTOR_URL to submit the actual burn transaction.
Configuration is stored in ~/.hermes/payguard/policy.yaml and environment variables. The plugin supports both mainnet (default) and testnet profiles, switchable via PAYGUARD_ENV. It integrates with Circle's developer-controlled wallets, user-controlled transfers, and the Iris API for CCTP attestation tracking.
Source
This summary was written for Neura Market from the project's own repository. Install commands, identifiers and licence details are reproduced unchanged. The nativ3ai/hermes-payguard repository is the authoritative source and the place to file issues or contribute.
Category: Cost & Governance · Licensed under MIT