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.

Tool	Description
eightdx_login_wallet	Records a public wallet address, blockchain, optional wallet app, and optional client surface for this MCP run.
eightdx_get_wallet_session	Reads the current local wallet session, if any.
eightdx_logout_wallet	Clears the local wallet session. This does not revoke token approvals or cancel on-chain permissions.

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.

Tool	Description
eightdx_walletconnect_create_session	Creates a WalletConnect session and returns QR/raw URI, copied URI, and mobile direct-connection options.
eightdx_walletconnect_get_session	Reads the current WalletConnect session and connected account, optionally waiting for a pending approval.
eightdx_walletconnect_disconnect	Disconnects the active WalletConnect session.
eightdx_wallet_send_transaction	Requests eth_sendTransaction through the connected wallet. Requires confirmedByUser: true.
eightdx_local_signer_status	Shows whether the opt-in MCP-side signer is enabled and which address/chains are configured.
eightdx_local_sign_and_send_transaction	Signs and broadcasts with the opt-in local signer. Requires env configuration and confirmedByUser: true.

Token discovery

Tool	Description
eightdx_search_tokens<br><sub>GET /api/tokens</sub>	Searches 8DX token metadata so agents can resolve prompts like "BTC", "bitcoin", "USDC", or token names.

Quotes and swaps

Tool	Description
eightdx_health<br><sub>GET /api/health</sub>	Checks whether the 8DX API is reachable and responding normally.
eightdx_get_quote<br><sub>GET /api/{blockchain}/quote</sub>	Performs a read-only quote lookup for a token pair and amountIn or amountInWei.
eightdx_preview_market_swap<br><sub>GET /api/{blockchain}/quote</sub>	Returns quote data plus a 30-second refresh hint, selected slippage/deadline, route-link metadata, and signing guidance.
eightdx_get_wallet_links	Builds an 8DX web URL and MetaMask Mobile dapp deeplink for wallet handoff.
eightdx_create_swap<br><sub>POST /api/{blockchain}/swap</sub>	Returns swap calldata for a previously quoted path. This tool does not sign, custody funds, or broadcast by itself.

Permit helpers

Tool	Description
eightdx_get_permit_address<br><sub>GET /api/{blockchain}/permit/address</sub>	Reads the permit contract address used by the selected blockchain.
eightdx_get_permit_data<br><sub>GET /api/{blockchain}/permit/data</sub>	Returns permit data that a wallet or agent can inspect and sign externally. The server never signs it.

Limit orders

Tool	Description
eightdx_create_limit_order<br><sub>POST /api/{blockchain}/order</sub>	Submits an order payload that has already been signed outside the MCP server.
eightdx_get_limit_orders_by_maker<br><sub>GET /api/{blockchain}/orders/byMaker/{maker}</sub>	Reads active limit orders for a maker address.
eightdx_get_limit_order_history<br><sub>GET /api/{blockchain}/orders/byMaker/history/{maker}</sub>	Reads historical limit orders for a maker address.
eightdx_get_order_status<br><sub>GET /api/{blockchain}/orders/{orderHash}</sub>	Reads one order by hash and returns scanner links for filled transaction hashes when available.
eightdx_cancel_limit_order<br><sub>POST /api/{blockchain}/orders/cancel</sub>	Submits a cancel payload that has already been signed outside the MCP server.

Explorer links

Tool	Description
eightdx_build_explorer_link	Builds Etherscan, BscScan, or Arbiscan links for transactions, addresses, and tokens. Explains off-chain order hashes.

Prompts

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

Prompt	Purpose
eightdx_trading_agent	General operating instructions for safe 8DX trading flows.
eightdx_market_swap_scenario	Checklist for prompts like "обменяй мне 1 биткоин по рынку".
eightdx_limit_order_scenario	Checklist for limit orders, signed order payloads, status, fills, and history.

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

Environment variable	Default	Description
EIGHTDX_API_BASE_URL	https://swap.ggp.gg	8DX REST API base URL.
EIGHTDX_REQUEST_TIMEOUT_MS	30000	Request timeout in milliseconds.
EIGHTDX_WALLETCONNECT_PROJECT_ID	8DX default project	Optional WalletConnect project override. WalletConnect works out of the box.
EIGHTDX_WALLETCONNECT_RELAY_URL	unset	Optional WalletConnect relay override.
EIGHTDX_WALLETCONNECT_METADATA_NAME	8DX MCP	WalletConnect app name shown in wallets.
EIGHTDX_WALLETCONNECT_METADATA_DESCRIPTION	8DX MCP server wallet connection	WalletConnect app description shown in wallets.
EIGHTDX_WALLETCONNECT_METADATA_URL	https://8dx.io	WalletConnect app URL shown in wallets.
EIGHTDX_WALLETCONNECT_METADATA_ICONS	unset	Comma-separated icon URLs for WalletConnect metadata.
EIGHTDX_ENABLE_LOCAL_SIGNER	false	Enables MCP-side transaction signing only when set to true.
EIGHTDX_SIGNER_PRIVATE_KEY	unset	Private key for the opt-in local signer. Never use this in an untrusted host.
EIGHTDX_RPC_URL	unset	Default Ethereum RPC URL for the local signer.
EIGHTDX_ETHEREUM_RPC_URL	unset	Ethereum RPC URL for the local signer. Overrides EIGHTDX_RPC_URL.
EIGHTDX_BSC_RPC_URL	unset	BNB Smart Chain RPC URL for the local signer.
EIGHTDX_ARBITRUM_RPC_URL	unset	Arbitrum RPC URL for the local signer.

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