8DX MCP Server

MCP server that exposes 8DX DEX aggregator REST endpoints as tools for AI agents.

The server is a thin TypeScript wrapper around the 8DX REST API plus safe AI-flow helpers. By default it does not hold keys, sign, or custody funds. It can create WalletConnect requests so the user's own wallet signs and broadcasts after approval; the MCP-side local signer remains opt-in and disabled unless explicitly configured.

Tools

Supported blockchain values for quote, swap, permit, and limit-order tools: ethereum, bsc, and arbitrum.

AI wallet session

These tools help an AI agent keep conversational context for terminal or Telegram-style flows. The session is local in memory and stores only public wallet metadata.

Wallet execution

These tools let an AI client offer a direct wallet path. WalletConnect is the preferred production path: the user's wallet signs and broadcasts after showing its own confirmation UI. The local signer is disabled unless environment variables explicitly enable it.

Token discovery

Quotes and swaps

Permit helpers

Limit orders

Explorer links

Prompts

The server also exposes MCP prompt templates that help host AI agents turn natural language into safe tool sequences:

AI trading flow

Recommended WalletConnect-first market-swap flow for an AI client:

1. Resolve or ask for the target chain before creating a WalletConnect session. If the user names tokens in natural language, call eightdx_search_tokens. If results are ambiguous, ask which token/address to use before quoting.

2. If the request is missing the output token, amount, slippage, or deadline, ask a follow-up question. For example, "обменяй мне 1 биткоин по рынку" is missing the token the user wants to receive. Market swap deadlines are relative seconds from now; use 600 for 10 minutes, not a Unix timestamp.

3. Call eightdx_get_wallet_session and eightdx_walletconnect_get_session.

4. Call eightdx_preview_market_swap as soon as the chain, tokens, amount, slippage, and deadline are known. If no wallet is connected yet, omit dstAddress. Show the quote and routeLink.url as an optional prefilled 8DX web page for users who prefer the 8DX UI; direct MCP execution can continue without opening that page.

5. If WalletConnect is unavailable in the current host, explain that direct wallet confirmation is unavailable there. Call eightdx_preview_market_swap to generate a fresh quote and route metadata, then offer routeLink.url, walletLinks.webUrl, or walletLinks.metamaskMobileDappUrl only as fallback web handoff links. Do not call eightdx_create_swap or eightdx_wallet_send_transaction in this fallback branch.

6. If WalletConnect is available but not connected and the user wants direct MCP execution, call eightdx_walletconnect_create_session for the selected chain and show all returned connectionOptions, including WalletConnect QR, copied URI, and mobile deeplink choices. Ask the user to connect in their wallet, then call eightdx_walletconnect_get_session again.

7. After WalletConnect connects, call eightdx_login_wallet with the connected public account, chain, surface, and wallet app when known. For normal self-swaps, this connected account is both fromAddress and dstAddress.

8. Refresh the quote with eightdx_preview_market_swap and dstAddress set to the connected wallet and show the quote, route, price impact, slippage, deadline, and refreshAfterSeconds: 30. Also show routeLink.url as an optional prefilled 8DX web page for users who prefer the 8DX UI; direct MCP execution can continue without opening that page.

9. Refresh the preview if the user waits longer than 30 seconds before confirming.

10. Ask for explicit confirmation of the fresh quote and swap parameters. If the user explicitly pre-authorizes refreshed quotes for the same swap intent, the agent may refresh stale quotes and continue without another chat confirmation; the wallet UI must still require final transaction approval. Then call eightdx_create_swap with the confirmed quoted path, slippage, deadline, fromAddress, and dstAddress.

11. Show the returned to, data, value, chain, sender, and recipient. Then call eightdx_wallet_send_transaction with confirmedByUser: true; the connected wallet signs and broadcasts only after the user approves in the wallet UI.

12. Use eightdx_local_sign_and_send_transaction only when eightdx_local_signer_status says enabled and the user explicitly asked the MCP server to sign and send.

13. After a transaction hash is returned, call eightdx_build_explorer_link so the terminal or Telegram bot can display a scanner link.

Recommended limit-order flow:

1. Prepare and sign the limit-order typed data outside this server.

2. Submit the signed payload with eightdx_create_limit_order.

3. Poll eightdx_get_order_status or read eightdx_get_limit_order_history for result, filters, and fill transaction hashes.

Telegram and terminal UIs should orchestrate these tools. This package does not run a Telegram bot, but it exposes the MCP tools needed for the bot or AI host to manage wallet connection, quote refresh, transaction confirmation, status, and history.

Install

npm install -g @8dx/8dx-mcp-server

Or run it directly:

npx -y @8dx/8dx-mcp-server

Configuration

All outgoing 8DX REST API requests include:

X-Source: 8dx-mcp/0.1.0

This lets the 8DX backend distinguish MCP traffic from direct API usage.

Claude Desktop

Add this to claude_desktop_config.json:

{
  "mcpServers": {
    "8dx": {
      "command": "npx",
      "args": ["-y", "@8dx/8dx-mcp-server"],
      "env": {
        "EIGHTDX_API_BASE_URL": "https://swap.ggp.gg"
      }
    }
  }
}

Claude Code

claude mcp add 8dx --transport stdio -- npx -y @8dx/8dx-mcp-server

OpenAI Codex

Codex CLI can register this server as a stdio MCP server with codex mcp add.

Local development

Use this while developing the server before it is published to npm.

Build the server first:

cd /absolute/path/to/8dx-mcp-server
npm install
npm run build

Then add the local server to Codex:

codex mcp add 8dx-local \
  --env EIGHTDX_API_BASE_URL=https://swap.ggp.gg \
  --env EIGHTDX_REQUEST_TIMEOUT_MS=30000 \
  -- node /absolute/path/to/8dx-mcp-server/dist/index.js

Confirm that Codex can see the server:

codex mcp list
codex mcp get 8dx-local

Published package

After the package is published to npm, use npx instead of the local node path:

codex mcp add 8dx \
  --env EIGHTDX_API_BASE_URL=https://swap.ggp.gg \
  --env EIGHTDX_REQUEST_TIMEOUT_MS=30000 \
  -- npx -y @8dx/8dx-mcp-server

Cursor

Cursor supports project-level and global MCP configuration:

• Project-level: create .cursor/mcp.json in the project root.

• Global: create ~/.cursor/mcp.json.

Local development

Use this while developing the server before it is published to npm.

Build the server first:

cd /absolute/path/to/8dx-mcp-server
npm install
npm run build

Then create or update .cursor/mcp.json in the project where you want to use the 8DX tools:

{
  "mcpServers": {
    "8dx-local": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/8dx-mcp-server/dist/index.js"],
      "env": {
        "EIGHTDX_API_BASE_URL": "https://swap.ggp.gg",
        "EIGHTDX_REQUEST_TIMEOUT_MS": "30000"
      }
    }
  }
}

Restart Cursor, open Cursor Settings, go to MCP, and confirm that 8dx-local is enabled.

Try these prompts in Cursor chat:

Call the 8DX health tool.

Use 8DX to get a quote on ethereum from WETH to USDC.

For quote testing, pass exact token identifiers and amount format accepted by the 8DX API.

Published package

After the package is published to npm, use npx instead of the local node path:

{
  "mcpServers": {
    "8dx": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@8dx/8dx-mcp-server"],
      "env": {
        "EIGHTDX_API_BASE_URL": "https://swap.ggp.gg",
        "EIGHTDX_REQUEST_TIMEOUT_MS": "30000"
      }
    }
  }
}

If Cursor does not show the tools, run npm run build again, restart Cursor, and check that the absolute path in args points to an existing dist/index.js file.

See examples/ for ready-to-copy local MCP config templates.

Development

npm install
npm test
npm run typecheck
npm run build
npm run smoke:stdio
npm run smoke:agent
npm run dev

Safety

This MCP server does not provide financial advice. Agents and users must inspect all swap calldata, permit data, signatures, transaction fields, and order payloads before using them with a wallet or broadcasting anything on-chain. Direct execution tools require confirmedByUser: true; WalletConnect still relies on the user's wallet confirmation UI, and the local signer should only be enabled in a trusted environment.

License

MIT