# hermes-mcp

MCP server for the [Hermes](https://hermes.swap.io/llms.txt) paid swap API.
Gives any MCP host (Claude Desktop, Claude Code, ChatGPT with MCP
connectors, Cursor and others) Solana swap tools: ranked quotes, transaction
building, broadcasting and status tracking.

Payment is per request in USDC via the x402 protocol: no accounts, no API
keys. The server pays from a local keypair and the model never sees the key,
only tool results. API payments are gasless for the payer wallet (USDC only,
no SOL needed).

## Tools

| Tool                 | Cost | Purpose                                        |
|----------------------|------|------------------------------------------------|
| hermes_info          | free | Endpoints and current base prices              |
| swap_quote           | paid | Ranked multi-provider quotes -> quoteId        |
| swap_build_tx        | paid | Unsigned transaction for a quote -> transactionId |
| swap_sign_and_submit | paid | Sign, broadcast and track (requires confirm)   |
| swap_status          | free | Broadcast status by hash                       |

Quotes and built transactions stay cached inside the server and are referred
to by opaque ids, so bulky provider payloads never enter the model context.

## Setup

1. Create a dedicated Solana wallet for payments and fund it with a few
   dollars of USDC. No SOL is needed for API payments. (To also broadcast
   swaps owned by this wallet, add a little SOL for the swap network fee.)
2. Save its keypair JSON somewhere private, e.g. `~/.keys/hermes-payer.json`.

### Claude Desktop

Add to `claude_desktop_config.json` (Settings -> Developer -> Edit Config):

```json
{
  "mcpServers": {
    "hermes-swap": {
      "command": "npx",
      "args": ["-y", "github:swap-dot-io/hermes-mcp"],
      "env": {
        "PAYER_KEYPAIR": "/absolute/path/to/hermes-payer.json"
      }
    }
  }
}
```

### Claude Code

```
claude mcp add hermes-swap --env PAYER_KEYPAIR=/absolute/path/to/hermes-payer.json -- npx -y github:swap-dot-io/hermes-mcp
```

(Claude Code users may prefer the [hermes-swap plugin](https://github.com/swap-dot-io/agent-skills) instead.)

### ChatGPT desktop (and Codex CLI)

ChatGPT desktop shares MCP configuration with Codex CLI on the same machine.
Add to `~/.codex/config.toml`:

```toml
[mcp_servers.hermes-swap]
command = "npx"
args = ["-y", "github:swap-dot-io/hermes-mcp"]

[mcp_servers.hermes-swap.env]
PAYER_KEYPAIR = "/absolute/path/to/hermes-payer.json"
```

Or let Codex write the entry: `codex mcp add hermes-swap -- npx -y github:swap-dot-io/hermes-mcp`
(then add the env block).

ChatGPT web supports only remote MCP connectors (developer mode). We do not
offer a hosted connector: it would require custody of your payment key,
which defeats the design. Use ChatGPT desktop or any local MCP host instead.

### Environment

| Variable        | Default                              | Purpose                       |
|-----------------|--------------------------------------|-------------------------------|
| PAYER_KEYPAIR   | (required for paid tools)            | Path to payer keypair JSON    |
| HERMES_URL      | https://hermes.swap.io               | API base URL                  |
| SOLANA_RPC_URL  | https://api.mainnet-beta.solana.com  | RPC for payment transactions  |
| X402_NETWORK    | solana                               | x402 network id               |

## Safety model

- The keypair path is configuration; the key itself never reaches the model.
- `swap_sign_and_submit` refuses to run without `confirm: true` and is meant
  to be called only after the user explicitly confirmed the swap.
- A paid call is trusted only when it carries an on-chain settlement receipt
  (X-PAYMENT-RESPONSE). Failed requests are never charged by Hermes.

## Links

- Agent guide: https://hermes.swap.io/llms.txt
- Live payment terms: https://hermes.swap.io/v1/info
- x402 protocol: https://www.x402.org