Dexra for Hermes Agent

Lets Hermes Agent trade on Solana, with Dexra checking every buy first. Before a buy, the agent gets two Dexra verdicts (ok, caution, avoid or unknown) with reasons in plain words, and the buy goes ahead only if both pass. The template has two parts. dexra-trader is a local stdio MCP server with five tools: check_token, preflight, fresh_launches, buy and sell. The solana-trading-with-dexra skill teaches Hermes the workflow: check, preflight, report, then buy only when the guard allows. Swaps go through Jupiter. Everything is a dry run until you switch live trading on. The MCP server isn't tied to Hermes, so any MCP client can use it.

Safety

• Dry run by default. Trades are sent only when DRY_RUN=false, SOLANA_PRIVATE_KEY and JUPITER_API_KEY are all set. Otherwise every result has mode: dry_run, and the message says which setting is missing.

• Caps. MAX_TRADE_SOL (default 0.05) is a hard cap per buy. A larger buy is refused, not reduced. SLIPPAGE_BPS defaults to 100 and can't go above 1000.

• What blocks a buy:

  • an avoid or unknown verdict from either check

  • a caution verdict, unless ALLOW_CAUTION=true

  • an invalid mint or amount

  • any Dexra failure (402, 429, 5xx or a network error). The guard fails closed.

• The guard sits in the server, not the prompt. buy runs Dexra's checks itself every time it's called. So no wording, skill or other MCP server can make the agent buy past a block. Dexra's remote MCP server has no trading tools.

• Sells are never blocked, so a position can always be exited. The preflight verdict is still reported.

• Keys come only from the environment. The wallet secret is never logged or echoed. Hermes passes a stdio server only the variables listed in its env block, plus a short safe baseline. Use a dedicated wallet that holds little SOL. The caps limit each trade, not all trades together.

Not financial advice. A Dexra ok means launches like it survived more often in our published report, not that the price will go up.

Related MCP server: jupiter-mcp

Quick start

Click Use this template on GitHub, or:

git clone https://github.com/dexra-dev/template-hermes
cd template-hermes
cp .env.example .env          # add DEXRA_API_KEY at least
uv sync
uv run --env-file .env python scripts/smoke.py    # dry run, no LLM: checks BONK and tries a 0.01 SOL buy

Then connect it to Hermes:

./scripts/install.sh

The script installs the Python dependencies and copies the skill to ~/.hermes/skills/trading/solana-trading-with-dexra/. It then prints the mcp_servers block with this checkout's path filled in. It never edits your config.yaml. Paste the block into ~/.hermes/config.yaml yourself, and put the keys in ~/.hermes/.env:

DEXRA_API_KEY=dxr_...
# live trading only:
JUPITER_API_KEY=...
SOLANA_PRIVATE_KEY=...

Check the server and load it:

hermes mcp test dexra_trader      # should list 5 tools
hermes                            # then, in a session: /reload-mcp

Ask: "Check DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263 and buy 0.01 SOL if it passes." You can also call the skill directly: /solana-trading-with-dexra.

Get a key at dexra.dev/app/keys. The free tier gives 100 credits a day. Paid tools can also be paid per call over x402.

The Hermes config

hermes/config.example.yaml adds two servers:

• dexra_trader: the local server, started with uv run --directory <this checkout> dexra-trader.

  • Secrets come in as ${DEXRA_API_KEY}-style references, which Hermes fills from ~/.hermes/.env.

  • The safety settings are written out literally in the env block, so you can see them there.

  • tools.include lists the five tools.

• dexra (optional): Dexra's remote MCP server at https://api.dexra.dev/mcp over Streamable HTTP, with Authorization: Bearer ${DEXRA_API_KEY}.

  • It's for research: wallet_check, pool_health, market_snapshot and others.

  • tools.include leaves out token_deep_check, swap_preflight and new_launches. dexra_trader already covers them, so the model sees one name per check.

  • Hermes won't connect this server while DEXRA_API_KEY is unset. Set enabled: false until you have a key.

Hermes registers the tools as mcp__dexra_trader__buy, mcp__dexra__wallet_check and so on. Run /reload-mcp after any change. To load the skill from this checkout instead of copying it, add the checkout's skills/ directory to skills.external_dirs.

Other MCP clients

dexra-trader is a standard stdio MCP server. In a client that uses the common mcpServers JSON format:

{
  "mcpServers": {
    "dexra-trader": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/template-hermes", "dexra-trader"],
      "env": { "DEXRA_API_KEY": "dxr_...", "DRY_RUN": "true" }
    }
  }
}

The server sends short usage instructions in its MCP handshake: check first, never work around a block, say when a result is a dry run. Clients that read those instructions pass them to the model.

Configuration

The server reads only its environment. Under Hermes, that means the env block of dexra_trader. A ${VAR} that Hermes couldn't resolve counts as unset, so a setting you leave out falls back to its safe default.

How the guard works

dexra_core is the shared Dexra trading core, copied unchanged. Each tool is a thin wrapper around it:

decide_buy checks the mint and the amount against MAX_TRADE_SOL before any network call. Then it runs token_deep_check and swap_preflight in parallel. The buy is allowed only if both verdicts pass. buy returns plain JSON whose status is one of these:

• blocked: the guard said no.

• dry_run: it would have traded.

• executed: the trade was sent and landed.

• failed: Jupiter couldn't build the transaction, or it didn't land.

• error: a problem with config, keys or the network.

The decision field holds both verdicts and the reasons. The full rules are in dexra_core/README.md.

Project layout

dexra_core/                 shared trading core (copied verbatim, do not edit)
dexra_trader/
  tools.py                  the five tools as plain functions on the core
  server.py                 MCP server (official mcp SDK, MCPServer, stdio)
skills/solana-trading-with-dexra/SKILL.md   Hermes skill: the workflow and its rules
hermes/config.example.yaml  mcp_servers entries for ~/.hermes/config.yaml
scripts/install.sh          copies the skill, prints the config (never edits it)
scripts/smoke.py            starts the server over stdio and runs a dry-run buy, no LLM
tests/                      core tests, tool tests and MCP client tests, HTTP mocked with respx

Develop:

uv sync
uv run pytest -q
uv run ruff check . && uv run ruff format --check . && uv run pyright

The mcp SDK is pinned to 2.3.0. In SDK 2.x the high-level server class is called MCPServer; in 1.x it was FastMCP.

Links

• Dexra docs for templates: https://dexra.dev/docs/templates?utm_source=github&utm_medium=referral&utm_campaign=templates&utm_content=template-hermes

• API keys: https://dexra.dev/app/keys?utm_source=github&utm_medium=referral&utm_campaign=templates&utm_content=template-hermes

• How the verdicts hold up: https://dexra.dev/accuracy?utm_source=github&utm_medium=referral&utm_campaign=templates&utm_content=template-hermes

• Hermes MCP guide: https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp

• Hermes MCP config reference: https://hermes-agent.nousresearch.com/docs/reference/mcp-config-reference

• Hermes skills: https://hermes-agent.nousresearch.com/docs/user-guide/features/skills

• Jupiter Swap API: https://developers.jup.ag/docs/swap/order-and-execute

• MCP Python SDK: https://github.com/modelcontextprotocol/python-sdk

License

MIT. See LICENSE.