Hermes

The @ampersend/hermes package adds support for x402 payments within Hermes Agent workflows. It includes built-in tools for MCP-based payment proxying, agent identity management via the ampersend dashboard, and client-side controls to validate transactions before submitting requests.

Developed as a typed wrapper around @ampersend_ai/ampersend-sdk, this offers sensible defaults for common Hermes workflows. Features include automated agent setup through an approval process, Hermes configuration patching for MCP payment proxying, and pre-flight spend validation.

While it is optimized for use with Hermes, the package is also flexible enough to integrate with other agent frameworks.

---

Overview

By default, the package uses:

• Base mainnet
• Production ampersend API

No flags required for production use.

Setup (Recommended Flow)

Use the two-step bootstrap flow for Hermes, CI environments, and non-TTY shells.

1. Clone and install

git clone https://github.com/edgeandnode/ampersend-hermes.git
cd ampersend-hermes
pnpm install

---

2. Start Bootstrap

pnpm bootstrap start --name my-hermes-agent

The command generates a key and requests approval.

---

3. Approve the agent

Open the user_approve_url in the ampersend dashboard and approve the request.

---

4. Finish bootstrap

pnpm bootstrap finish

This polls for approval and activates the agent.

Run these commands from the repository root directory that contains package.json.

---

One-Command Setup

Run the full setup flow in a single command:

pnpm setup --name my-hermes-agent

This command:

1. Requests approval
2. Waits for approval
3. Patches the Hermes config
4. Starts the MCP proxy

After setup completes:

1. Switch back to Hermes
2. Run:

/reload-mcp

---

Manual Installation

1. Configure environment variables

cd ampersend-hermes
cp .env.example .env

Fill in:

• AMPERSEND_AGENT_KEY
• AMPERSEND_AGENT_ACCOUNT

---

2. Install dependencies and build

pnpm install && pnpm build

---

Configuration

All environment variables are validated at startup using Zod.

Required variables:

• AMPERSEND_AGENT_KEY
• AMPERSEND_AGENT_ACCOUNT

All other values default to Base mainnet and the production ampersend API.

Variable	Required	Default	Description
AMPERSEND_AGENT_KEY	Yes	—	0x-prefixed session key private key (66 chars)
AMPERSEND_AGENT_ACCOUNT	Yes	—	0x-prefixed smart account address (42 chars)
AMPERSEND_API_URL	No	https://api.ampersend.ai	ampersend API base URL
AMPERSEND_NETWORK	No	base	Network: base or base-sepolia
AMPERSEND_CHAIN_ID	No	8453	Chain ID derived from the network
AMPERSEND_MCP_PROXY_PORT	No	3000	MCP proxy listen port
AMPERSEND_ENV_FILE	No	—	Absolute path to .env
HERMES_CONFIG_DIR	No	~/.hermes	Hermes config directory

Override config in tests

import { loadConfig } from "@ampersend/hermes";

const cfg = loadConfig({
  AMPERSEND_AGENT_KEY: "0x...",
});

---

Patch Hermes Config

Register ampersend under mcp_servers.ampersend.

Default stdio transport

Recommended configuration:

import { patchHermesConfig } from "@ampersend/hermes";

await patchHermesConfig("~/.hermes");

This writes an stdio server entry that runs the ampersend MCP proxy via npx with agent credentials set in the environment.

The proxy handles:

• SIWE authentication
• x402 payments

HTTP transport

Connect to an existing proxy:

await patchHermesConfig("~/.hermes", {
  transport: "http",
  proxyPort: 3000,
});

Reload the MCP configuration.

Apply changes in Hermes:

/reload-mcp

---

Setup Options

pnpm setup --name my-agent --proxy-port 4000

Use a custom proxy port.

pnpm setup --name my-agent --no-proxy

Patch configuration only.

pnpm setup --name my-agent --daily-limit 10000000

Set a daily limit of 10 USDC.

pnpm setup --name my-agent --network base-sepolia

Use Base Sepolia for development.

pnpm setup -h

Show all setup options.

---

Fetch Paid x402 URLs

Do not use getApiClient() for arbitrary HTTPS URLs.

Use one of the following instead:

Method	Use case
ampersend fetch <url>	CLI usage and quick tests
getPaidFetch()	TypeScript paid fetch support

Use getPaidFetch

import { getPaidFetch } from "@ampersend/hermes";

async function main() {
  const fetchPaid = getPaidFetch();

  const res = await fetchPaid(
    "https://example.com/x402-endpoint"
  );

  console.log(await res.text());
}

void main();

Inspect pricing without paying

ampersend fetch --inspect https://example.com/x402-endpoint

---

Authorize Payments

Use the ampersend API to authorize payments with spend limits.

Direct authorization

import {
  authorizePayment,
} from "@ampersend/hermes";

const result = await authorizePayment({
  requirements: [
    {
      scheme: "exact",
      network: "base",
      maxAmountRequired: "1000000",
      resource: "https://api.example.com/resource",
      description: "Example resource",
      mimeType: "application/json",
      payTo: "0x0000000000000000000000000000000000000001",
      maxTimeoutSeconds: 60,
      asset: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    },
  ],
  context: {
    method: "tools/call",
    serverUrl: "https://api.example.com",
  },
});

Create a configured treasurer

import { getTreasurer } from "@ampersend/hermes";

const treasurer = getTreasurer();

---

Client-Side Guardrails

Validate payments before sending API requests.

Create a spending policy

import {
  validatePayment,
  buildSpendPolicy,
} from "@ampersend/hermes";

const policy = buildSpendPolicy({
  perTxLimit: "1000000",
  dailyLimit: "10000000",
  networks: ["base"],
});

Validate a payment

Valid payment:

validatePayment(
  {
    amount: "500000",
    network: "base",
    resource: "/api/data",
  },
  policy,
);

Invalid payment:

validatePayment(
  {
    amount: "2000000",
    network: "base",
    resource: "/api/data",
  },
  policy,
);

Throws:

SpendLimitViolationError (PER_TX_LIMIT_EXCEEDED)

---

Agent Management

Create and manage agents through the ampersend approval flow.

Request approval

import {
  requestAgentApproval,
  waitForApproval,
  getAgentStatus,
} from "@ampersend/hermes";

const pending = await requestAgentApproval(
  "0xAgentKeyAddress",
  {
    name: "my-agent",
    dailyLimit: "10000000",
  },
);

console.log(
  "Approve at:",
  pending.userApproveUrl,
);

Wait for approval

. const result = await waitForApproval(
  pending. token,
  {
    timeoutMs: 600_000,
  },
);

Check agent status

const status = await getAgentStatus();

---

Development Commands

pnpm dev

Run in watch mode.

pnpm test

Run tests.

pnpm test: watch

Run tests in watch mode.

pnpm build

Compile to dist/.

pnpm bootstrap start --name agent

Request approval.

pnpm bootstrap finish

Poll and activate the agent.

pnpm setup --name agent

Run the full setup flow.

pnpm proxy

Start the MCP proxy only.

---

Architecture

src/
  config.ts
  client.ts
  dotenv-path.ts
  errors.ts
  bootstrap.ts
  bootstrap-cli.ts
  setup.ts
  mcp/
    index.ts
    hermes-config.ts
    proxy-cli.ts
  payment/
    index.ts
    guardrails.ts
    history.ts
  agents/
    index.ts
  index.ts

---

Module Overview

Path	Purpose
config.ts	Zod-validated config and needsBootstrap()
client.ts	API clients, paid fetch support, treasurer creation
dotenv-path.ts	.env resolution logic
errors.ts	Typed error classes
bootstrap.ts	Two-phase bootstrap flow
bootstrap-cli.ts	CLI for bootstrap commands
setup.ts	Unified setup CLI
mcp/hermes-config.ts	Hermes config patching
mcp/proxy-cli.ts	MCP proxy runner
payment/guardrails.ts	Spend limit validation
agents/index.ts	Agent approval flow
index.ts	Public exports

---

Additional Technical Information

For full source code, configuration files, and the latest updates, visit the official repository.

---