EnvarPay

EnvarPay is an open-source Python SDK and CLI that connects agents to MCP + x402 v2 payments. Put a USDC payment gate in front of an existing MCP tool or Hermes agent, and give buyers a wallet tool with an explicit spending budget.

Two sides. One package.

sequenceDiagram
    participant B as Buyer agent
    participant W as EnvarPay wallet
    participant S as EnvarPay seller
    participant F as x402 facilitator / USDC
    participant A as Your agent or MCP tool
    B->>W: Call a paid capability
    W->>S: MCP tool call
    S-->>W: PaymentRequired + price
    W->>W: Check recipient and budget; sign
    W->>S: Request + x402 payment
    S->>F: Verify and settle
    F-->>S: Transaction receipt
    S->>S: Verify Transfer + authorization nonce
    S->>A: Execute after payment
    A-->>B: Deliver result through EnvarPay

Why EnvarPay?

• Keep your agent. Works with existing MCP tools and an installed official Hermes runtime.

• Use open protocols. Official MCP and x402 SDKs handle the wire format. No Envar account or proprietary settlement API is required.

• Pay first, work second. The seller checks the exact USDC transfer and nonce before running the paid capability.

• Put spending limits in code. Configure allowed services, full recipients, tools, per-call limits and a persistent cumulative budget.

• Keep uncertain payments visible. Save the original authorization; reuse request IDs and inspect unresolved attempts without signing again.

Install

Python 3.11+, tested on macOS and Linux. Native Windows permissions are not yet validated; use WSL or Docker.

git clone https://github.com/EnvarAI/EnvarPay.git
cd EnvarPay
python -m pip install .
envar-pay --help

This alpha is not on PyPI yet. You can also install the wheel from GitHub Releases. For a Hermes seller, install into Hermes's Python environment; see the Hermes setup notes.

Start receiving payments

envar-pay init --directory ./agent-pay --pay-to YOUR_WALLET_ADDRESS --backend hermes
# Configure your model and capability in agent-pay/seller.toml.
envar-pay serve --config ./agent-pay/seller.toml

Your paid ask_agent tool is available at http://127.0.0.1:4020/mcp (or /sse). The seller needs its receiving address, not its private key. Already run an MCP service? Choose --backend mcp and configure which tools to sell.

Give an agent a payment wallet

envar-pay keygen --output ./agent-pay/buyer.key
# Fund the dedicated test wallet; review the recipient and budget in buyer.toml.
# Payments default to OFF. Enable them only after reviewing the configuration.
envar-pay hermes-config --config ./agent-pay/buyer.toml

Merge the generated mcp_servers.payments entry into Hermes's MCP configuration. Other MCP clients can launch the same envar-pay wallet --config ... process. The agent gets list_paid_tools, call_paid_tool and payment_status.

For a direct call:

envar-pay call --config ./agent-pay/buyer.toml --peer seller --tool ask_agent \
  --arguments '{"question":"Help our team plan a weekly knowledge review"}' \
  --request-id weekly-review-001

For an embedded integration:

from pathlib import Path
from envar_pay import WalletService, load_config

wallet = WalletService(load_config(Path("agent-pay/buyer.toml")))
result = await wallet.call(
    "seller", "ask_agent", {"question": "Review these notes"}, "review-001"
)

What has been proven?

A prior two-container Hermes POC paid 0.01 test USDC on Base Sepolia, then delivered a real model-generated answer. Buyer balance: 20 → 19.99. Seller: 0 → 0.01.

View the on-chain transaction · Evidence and its limits

The extracted package has been tested with an official Hermes 0.20.0 image, clean wheel installation, real model connectivity and local MCP transport tests. Those tests are not additional blockchain payments. The package rechecked the existing POC receipt; a new package-version live payment is still pending.

Current scope

0.1.0a1 is an alpha, not a production financial system. Defaults use Base Sepolia, payments off, and a 0.01 test-USDC per-call and cumulative budget.

Base mainnet configuration exists, but this release has no new mainnet payment validation. Preserve the state after an uncertain result: deleting it or creating a new purchase ID can defeat your intended spending controls. A wallet component running under the same OS identity as an agent with shell access is not isolated from that agent. See operating boundaries.

Contribute

Try an integration, report a reproducible issue, or improve interoperability. Start with CONTRIBUTING.md. Report vulnerabilities through GitHub's private reporting channel.

Built with MCP, x402 and optional Hermes integration. EnvarPay is an independent project by EnvarAI, not an official distribution or endorsement by those projects. MIT licensed.