# Eterna MCP Agent Starter

Build an AI trading agent on [Eterna Hybrid Exchange](https://ehx.app/r/Steve) in under 30 minutes — using Claude (MCP), the official CLI, or sandboxed TypeScript strategies. Ships with its own **MCP server**: fee estimator, venue comparison, setup guides and guarded agent prompts that work without an account, plus an authenticated bridge to the official Eterna MCP endpoint.

Eterna is a no-KYC perpetual futures exchange with flat fees (0.014% maker / 0.035% taker), CEX-grade liquidity routed from Bybit, and native AI-agent tooling: an MCP server, a CLI, and a managed TypeScript sandbox with an injected `eterna.*` SDK.

> **Affiliate disclosure:** links to Eterna in this repo use referral code `Steve`. Signing up through them costs you nothing extra — fees are identical — and supports this project.

---

## Why Eterna for agents

| | Eterna | Typical setup (direct CEX API) |
|---|---|---|
| KYC | None — wallet auth | Full KYC |
| Taker fee | Flat **0.035%** | 0.045%+ before volume tiers |
| Maker fee | Flat **0.014%** | 0.015%+ |
| Agent access | Native MCP server + CLI + sandbox SDK | Roll your own REST/WS client |
| Agent safety | Isolated sub-account, **no withdrawal rights** | API key scoping varies |
| Liquidity | $10B+ routed from Bybit order books, <200ms | Depends on venue |

Run your own numbers: [Eterna vs Hyperliquid fee calculator](https://eterna-referral.com/fee-calculator.html) · [full comparison](https://eterna-referral.com/eterna-vs-hyperliquid.html).

---

## Path 0 — Run the starter MCP server

A stdio MCP server that any client (Claude Desktop, Claude Code, Cursor, Windsurf, Glama) can launch. It needs no credentials to start.

```json
{
  "mcpServers": {
    "eterna-starter": {
      "command": "npx",
      "args": ["-y", "github:stevevstd-oss/eterna-mcp-agent-starter"]
    }
  }
}
```

| Tool | Needs account | What it does |
|---|---|---|
| `eterna_fee_estimate` | No | Monthly fees for a volume and maker/taker mix, plus EHX credited via EHX Payback |
| `eterna_compare_fees` | No | Same volume across Eterna, Hyperliquid, Bybit, Binance — with sources |
| `eterna_setup_guide` | No | Step-by-step for `claude`, `cli`, `generic-mcp` or `starter-server` |
| `eterna_agent_prompt` | No | Guarded trading-agent prompt (1% risk cap, mandatory SL/TP, approval gate) |
| `eterna_connection_status` | No | Whether the bridge is active and how to authenticate |
| Official Eterna tools | Yes | Bridged from `https://mcp.eterna.exchange/mcp` when a token is available |

**Bridge mode.** Set `ETERNA_ACCESS_TOKEN` in the server's `env`, or run `npx @eterna-hybrid-exchange/cli login` once — the server reads `~/.eterna/credentials.json` (override with `ETERNA_CONFIG_DIR`) and refreshes it when needed. Every tool exposed by the official endpoint then appears next to the local ones.

```bash
# From source
git clone https://github.com/stevevstd-oss/eterna-mcp-agent-starter && cd eterna-mcp-agent-starter
npm install && npm run build && npm test

# Docker
docker build -t eterna-mcp-agent-starter .
docker run -i --rm -e ETERNA_ACCESS_TOKEN eterna-mcp-agent-starter
```

Environment variables: `ETERNA_ACCESS_TOKEN` (optional), `ETERNA_CONFIG_DIR` (default `~/.eterna`), `ETERNA_MCP_URL` (default `https://mcp.eterna.exchange/mcp`), `ETERNA_AUTH_ISSUER` (default `https://ai-auth.eterna.exchange`).

## Path 1 — Claude with MCP (no code)

1. Sign up at [ehx.app](https://ehx.app/r/Steve) (wallet signature, ~2 minutes, no KYC).
2. In Claude: **Customize → Connectors → Add Custom Connector**.
3. Name it `Eterna`, set the server URL to:

   ```
   https://mcp.eterna.exchange/mcp
   ```

4. Click **Add → Connect**, sign in, and **Authorize**.
5. Keep **Needs Approval** on at first — approve each trade manually until you trust your prompts.

Works with claude.ai, Claude Desktop, and Claude Code. See [docs/claude-setup.md](docs/claude-setup.md) for details and the generic MCP client config.

## Path 2 — Official CLI

```bash
# Authenticate (browser OAuth, or device code over SSH)
npx @eterna-hybrid-exchange/cli login

# Check auth and endpoint status
npx @eterna-hybrid-exchange/cli status

# Balance and open positions
npx @eterna-hybrid-exchange/cli balance
npx @eterna-hybrid-exchange/cli positions

# Browse the sandbox SDK reference
npx @eterna-hybrid-exchange/cli sdk --search "place order"
npx @eterna-hybrid-exchange/cli sdk --detail full
```

Credentials are stored in `~/.eterna/credentials.json` and auto-refreshed. See [docs/cli-setup.md](docs/cli-setup.md).

## Path 3 — TypeScript strategies in the sandbox

Your code runs in Eterna's managed Deno sandbox with the `eterna.*` SDK injected — no API client to build, no keys in your code.

```bash
# Run a strategy file
npx @eterna-hybrid-exchange/cli execute examples/first-session.ts

# Or pipe code directly
echo 'const balance = await eterna.getBalance(); return balance;' \
  | npx @eterna-hybrid-exchange/cli execute -
```

Starter strategies in [`examples/`](examples/):

- [`first-session.ts`](examples/first-session.ts) — read balance, positions, and a ticker; no orders placed. Run this first.
- [`account-snapshot.ts`](examples/account-snapshot.ts) — a compact account + market report your agent can call on a schedule.

Agent prompts to pair with the MCP connector are in [`prompts/`](prompts/).

---

## Safety model (read this)

- The MCP/CLI agent operates an **isolated sub-account**: it can trade but **cannot withdraw funds**. Your master account keeps custody.
- Start with **Needs Approval** in Claude; switch to Always Allow only for strategies you have watched run.
- Fund the sub-account only with what the strategy needs.
- Perpetual futures with leverage can lose money quickly. Nothing in this repo is financial advice. See [SECURITY.md](SECURITY.md).

## Docs

- [docs/claude-setup.md](docs/claude-setup.md) — Claude / MCP client setup
- [docs/cli-setup.md](docs/cli-setup.md) — CLI reference and auth flows
- [docs/fees.md](docs/fees.md) — fee schedule and comparison, with sources
- [src/](src/) — the MCP server (`index.ts` tools and bridge, `fees.ts` fee model, `auth.ts` token resolution)

## Official resources

- Eterna AI landing: https://ai.eterna.exchange/
- MCP endpoint: `https://mcp.eterna.exchange/mcp`
- Official monorepo: https://github.com/EternaHybridExchange/eterna-ai
- CLI repo: https://github.com/EternaHybridExchange/eterna-cli
- Referral program details: https://eterna.exchange/blog/eterna-referral-program-earn-from-the-volume-you-bring
- 30-minute agent tutorial: https://eterna.exchange/blog/build-your-ai-trading-agent-with-eterna-mcp-in-less-than-30-minutes

## Disclaimer

Community project, not affiliated with or endorsed by Eterna Hybrid Exchange. SDK method names and commands follow the official docs at the time of writing — verify with `npx @eterna-hybrid-exchange/cli sdk` before trading real funds. Trading perpetual futures involves substantial risk of loss.

MIT © 2026