dreamDEX Perps MCP

An MCP server that lets AI agents trade dreamDEX perpetuals.

Ready configs ship in this repo for the agent harnesses people already use: Claude Code, Claude Desktop, OpenCode, OpenAI Codex, ZCode, and Cursor, plus a generic mcpServers template that also fits Windsurf, Gemini CLI, Cline, and any other MCP client. Connect one of them to dreamDEX perps on the Somnia Hideki testnet and the agent can read markets, inspect a portfolio, and place real on-chain orders through plain tool calls. Per-harness setup is under MCA below.

Built for the dreamDEX Perps Builder Bounty (MVP track).

Why

dreamDEX is built for the agentic era: the order book is on-chain, the APIs are open, and agents are first-class participants. What was missing is a standard, safe way for an LLM agent to actually use the perps book. MCP (Model Context Protocol) is that standard. This server wraps the official @somnia-chain/markets-sdk (v0.32.1, the version the dreamDEX app runs) and exposes a small, auditable tool surface with guardrails an agent cannot talk its way around.

Related MCP server: Context MCP Server

An autonomous agent, not another trading bot

Conventional trading bots are automation. A programmer decides the strategy in advance, the code repeats it forever, and nothing in the system can decide that today is a bad day to trade. Change the behavior and you rewrite and redeploy code.

This project is built the other way around. The server ships no strategy at all. It gives an AI agent a set of guarded tools, and the agent decides: it studies the market, argues both sides of the trade, sizes the position, and can walk away. In live sessions with this build, the agent's own risk team and portfolio manager have rejected trades that a rule-based bot would have taken without a second thought.

Risk routines work the same way. Take-profit and stop-loss watching, margin guarding, funding plays: none of these are baked in as fixed code paths. They are standing instructions to the agent, changed in plain language, and the agent can weigh context a rigid strategy cannot, like closing early because funding flipped hard against the position before the stop was ever touched.

Make it yours

Nothing about how this trades is fixed. The tools are the floor, not the ceiling, and the agent executing for you can be shaped around the way you already trade:

• Your own data. Point it at extra sources beyond the built-in feeds: your own market data, a private feed you subscribe to, notes and levels you track yourself. If the agent can read it, it can weigh it.

• Your behavior. Entry habits, timeframes, the setups you trust and the ones you refuse. Describe them once, in plain language, and they become the standing brief the agent works from.

• Your risk rules. Position sizes, daily loss limits, when to sit out entirely. The hard caps in the server still apply; your rules sit on top and can only make it stricter.

• Your style. Scalper, swing trader, funding farmer, or someone who trades two hours a day. The executor is the same; the style running it is yours.

That is the point of putting an agent in the executor seat instead of a fixed strategy: the system adapts to the trader, not the other way around.

What's inside

The MCP server. Seven tools (below) over the official markets SDK: markets, account state, voucher claim, and guarded order placement, cancellation and closing.

Trading-key mode. Link a bot key to your DreamDEX account in the app (wallet, Link a bot, Perps), set OWNER_ADDRESS, and the server trades for the account through the pool's placeOrderFor entrypoint, the same pattern as the official bot kit. Margin locks from the account, fills settle to the account, and the key pays STT gas only. The key holds no funds and cannot withdraw, and it works with the 1,000 USDso perps credit sitting in the account, which can never be transferred to a bot wallet because it is perps margin, not spot funds.

The agent team. A reference crew that runs on top of the tools: a Market Analyst (funding, open interest), a Technical Analyst (candles, RSI, MACD), news and sentiment readers, a Bull and a Bear that debate the trade in the open, a Trader that posts a sized proposal, a Risk Team with three stances (aggressive, neutral, conservative), and a Portfolio Manager with the final call.

The Trading Desk. A visual front end (npm run ui) with a live BTC chart and TradingView-style drawing tools, the debate streamed as it happens, an order ticket with margin and projected ROE, and a position panel whose ROE tracks the live mark tick by tick. Paper mode runs the full session on live market data with nothing sent on-chain.

Tools

In trading-key mode (OWNER_ADDRESS set), the write tools act on the linked account instead of the key's own account: place_order verifies the pool's operator grant first, pre-flights against the account's margin, and sends placeOrderFor; cancel_order and close_position follow the same path.

Safety model

An agent with a signing key is a loaded weapon, so the server is built defensive by default:

• Read-only unless you say otherwise. No PRIVATE_KEY → no signing at all. Key present but TRADING_ENABLED unset → write tools still refuse.

• Hard notional cap. Every order is rejected if its USD value exceeds MAX_ORDER_NOTIONAL_USD (default $50). The cap is enforced in code, not in a prompt.

• Exchange-side pre-flight. Before sending, each order is checked with the SDK's getMaxPerpOrderSize, the same check the dreamDEX app runs, so margin, position caps and voucher allowlists are respected instead of discovered via reverts.

• A key that holds nothing. In trading-key mode the signing key is a linked bot key: it can place, cancel and reduce orders for the account and pay gas, and that is all. Funds stay in the account, fills settle to the account, and withdrawal is not something the key can do.

• Exact sizing. Quantities and prices are rounded to the market's own lotSize / tickSize, and per-market decimals (6–24 on the base side!) are read from the market row, never assumed.

• Testnet only. The server is wired to the Hideki testnet chain (chain id 50383) and paper USDso. There is no mainnet switch.

Quick start

git clone https://github.com/agasavenue17/dreamdex-perps-mcp
cd dreamdex-perps-mcp
npm install
cp .env.example .env   # fill in PRIVATE_KEY if you want trading enabled
npm run build
npm start

Verify the wiring without any key (talks to the live testnet indexer):

node scripts/smoke.mjs

Use it from an MCP client

{
  "mcpServers": {
    "dreamdex-perps": {
      "command": "node",
      "args": ["/path/to/dreamdex-perps-mcp/dist/index.js"],
      "env": {
        "PRIVATE_KEY": "0x…your-testnet-key…",
        "TRADING_ENABLED": "true",
        "MAX_ORDER_NOTIONAL_USD": "50",
        "OWNER_ADDRESS": "0x…your-dreamdex-account, if the key is a linked bot key…"
      }
    }
  }
}

MCA: plug into the harness you already use

People do not need another app to try this. They need it inside the agent harness they already open every day. MCA ships a ready config for each of the popular ones, with the path to this checkout filled in for you:

npm run mca -- claude     # Claude Code and Claude Desktop
npm run mca -- opencode   # OpenCode (opencode.json)
npm run mca -- codex      # OpenAI Codex (~/.codex/config.toml)
npm run mca -- zcode      # ZCode (~/.zcode/cli/config.json)
npm run mca -- cursor     # Cursor, Windsurf, Gemini CLI, Cline, generic mcpServers clients

Static templates live in configs/ if you prefer to copy by hand: claude.mcp.json, opencode.json, codex.config.toml, and zcode.config.json, with the generic template covering Cursor and the other mcpServers clients. Every variant starts the same stdio server; only the config shape differs, because that is the only thing that differs between harnesses.

Run with Docker

docker build -t dreamdex-perps-mcp .
docker run -i --rm \
  -e PRIVATE_KEY=0x… \
  -e TRADING_ENABLED=true \
  -e OWNER_ADDRESS=0x… \
  dreamdex-perps-mcp

The server speaks MCP over stdio, so run it with -i, or point your MCP client at the docker run command directly. Configuration is environment variables only; see .env.example.

Then ask your agent things like:

• "List the perp markets and show me BTC's max leverage."

• "What's my account state? Any open positions?"

• "Open a $20 long on BTC at market."

Getting testnet funds

1. STT for gas: sign in at app.testnet.dreamdex.io, use Link a Bot with your key's address, and use Send it … for gas / Top up. A perp order costs roughly 0.0003–0.003 STT in gas.

2. Paper USDso: with a fresh wallet (no positions or orders), call the claim_voucher tool once to receive the 1,000 USDso perps credit. Note the credit can only open positions in the markets on its allowlist.

How it works

AI agent ──MCP (stdio)──> this server ──> @somnia-chain/markets-sdk ──> Somnia Hideki testnet
                                            │                             ├─ Indexer (GraphQL): markets, portfolio
                                            └─ trader (viem signer)       └─ PerpPool contracts: orders settle on-chain

Reads go through the unified Somnia Markets indexer; writes are signed locally and sent straight to the perp pool contracts, where fills settle atomically on-chain. In trading-key mode the writes go to the pool's placeOrderFor / cancelOrderFor entrypoints (the markets SDK has no …For writes, so those calls are sent with viem, mirroring the official bot kit) after a read of the pool's operator registry confirms the link. Every placement returns the transaction hash and decoded fills, so an agent's work is verifiable in the testnet explorer.

Network reference

Running behind a proxy

The SDK talks to the chain over a raw WebSocket and has no HTTP fallback, so networks that force traffic through an HTTP(S) proxy break its chain reads (genesis check failed). If that is your environment, run the bundled bridge and point the server at it:

node scripts/ws-bridge.mjs          # ws://127.0.0.1:8787/ws -> Hideki, via HTTPS_PROXY
WS_RPC_URL=ws://127.0.0.1:8787/ws npm start

X posts

Posts about this build, tagging @DreamDEXSomnia:

1. Live demo, 2026-10-26: an agent debates Bull vs Bear, the Risk Team approves 3x, and a real SHORT 0.0005 BTC order settles on-chain on Hideki testnet, under the $50 cap, with no voucher claim. Tx: 0xd258b63f2530ee6b15507c1af5c12a1afb38e795de9e5056b089f0403a8e813f. Video: sketches/screenshots/demo-agent-ui-live-2026-10-26.mp4. https://x.com/agasavenue17/status/2114585546026819596

Credits

The agent team pattern in this project (analysts, Bull vs Bear debate, Trader, Risk Team, Portfolio Manager) is inspired by TradingAgents by TauricResearch, licensed Apache 2.0. The pattern was adapted here for dreamDEX perps; the implementation in this repo is original TypeScript and no TradingAgents code is included. Market data and execution use the official @somnia-chain/markets-sdk.

License

MIT