Hermes PayGuard: security tool for Hermes Agent

Safe-by-design USDC and x402 payment plugin for Hermes Agent with human approval for larger transfers

What Hermes PayGuard does

PayGuard installs as an add-on and does not patch Hermes core. It gives Hermes payment tools with an explicit operator boundary: the agent can prepare payment intents, inspect their status and execute them only if policy allows. Larger transfers need a separate human approval stamp created with payguard approve, and that step sits outside the model loop, so the agent cannot approve its own payment. Small x402 micropayments below a configured threshold can run automatically.

Supported rails are Circle developer-controlled USDC transfers, Circle user-controlled transfer challenges, Circle CCTP cross-chain route quoting with attestation-aware execution, and x402 paid HTTP fetches. A policy.yaml sets the mode, network profile, per-payment limit, micropayment limit and allowed recipients and hosts. A local audit ledger keeps replayable intent state. Mainnet is the default profile, and setting PAYGUARD_ENV to testnet switches to sandbox defaults. The plugin is MIT licensed.

Key features

Payment intents that are prepared, inspected and executed only when policy allows
Human approval stamp for larger transfers, outside the model loop
Automatic x402 micropayments below a configurable limit
Circle USDC transfers and CCTP cross-chain quoting
Local audit ledger with replayable intent state

When to use it

Paying a vendor invoice in USDC through a staged intent that a person approves
Letting an agent fetch a paid x402 URL when the cost is under the micropayment limit
Quoting a cross-chain CCTP transfer and staging it for approval

Who it is for: Hermes Agent operators who want an agent to handle crypto payments without giving it unchecked spending authority.

How it fits with Hermes Agent

Built for Hermes Agent as a standalone plugin with its own payment tools, installed into the Hermes plugins directory without changes to Hermes core.

How to install Hermes PayGuard

These commands are copied from the project's README. Check the repository for the latest steps before you run them.

pip install hermes-payguard

Requirements: Circle API credentials for USDC transfers, an EVM private key for x402 payments, and a CCTP executor URL for cross-chain burns

Note: It moves real money: mainnet is the default profile, and testnet must be selected by setting PAYGUARD_ENV to testnet.

FAQ

What is Hermes PayGuard?

Hermes PayGuard is a Hermes Agent plugin for USDC and x402 payments. It adds tools for preparing and executing payments, guarded by a local policy file and a human approval step for larger amounts.

How does Hermes PayGuard stop the agent from approving its own payments?

Approval happens outside the model loop. Hermes can stage a payment intent, but a person must run payguard approve with the intent identifier in a separate command before a larger transfer can execute.

How do I install Hermes PayGuard?

Run pip install hermes-payguard, or clone the repository and symlink it into ~/.hermes/plugins. The README's quick path also runs payguard install-plugin, payguard init-policy and payguard doctor.