hermes-mcp

MCP server for the Hermes 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):

{
  "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 instead.)

ChatGPT desktop (and Codex CLI)

ChatGPT desktop shares MCP configuration with Codex CLI on the same machine. Add to ~/.codex/config.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