SODAX Builders MCP Server

SODAX MCP server for AI coding assistants. Access live cross-network (cross-chain) API data: swap tokens across 20+ networks, query money market rates, look up solver volume, and search intent history. Includes full cross-chain SDK documentation that auto-syncs from SODAX developer docs. Build cross-network DeFi integrations with real-time protocol data directly in your development workflow. With a SODAX API key, it also quotes and tracks swaps that the user's own wallet signs.

One-liner: SODAX MCP server: live cross-network DeFi API data and auto-updating SDK docs for 20+ networks. Query swaps, lending, solver volume, and intent history, and make swaps the user's wallet signs, from your AI coding assistant.

Quick Start

Add the MCP server URL to your AI coding assistant's configuration:

{
  "mcpServers": {
    "sodax-builders": {
      "type": "http",
      "url": "https://builders.sodax.com/mcp"
    }
  }
}

Works with Claude, Cursor, VS Code, Windsurf, ChatGPT, and other MCP-compatible agents. One connection gives you access to all cross-network API tools and SDK documentation.

SSE Transport (Legacy)

For clients that don't support streamable HTTP (e.g. Gemini CLI), use the SSE endpoint instead:

{
  "mcpServers": {
    "sodax-builders": {
      "type": "sse",
      "url": "https://builders.sodax.com/sse"
    }
  }
}

API Key

Send your SODAX API key in an x-api-key header. The builder tools work without one; the swap tools need it. An organisation's Owner or Admin creates one in the partner portal, under API keys → Create key. The server forwards it on its calls to the SODAX data API, solver and Swaps API, and nowhere else (not to the relay either). Over stdio, set SODAX_API_KEY instead. A value that isn't a SODAX key (sodax_…) is ignored, except by the swap profile, which refuses it.

SSE clients send x-api-key on GET /sse and on every POST /messages: each message runs only with the key it carries, and a session opened with a key refuses a message without that key (HTTP 403). The MCP SDKs' SSE clients already send their headers on both.

{
  "mcpServers": {
    "sodax-builders": {
      "type": "http",
      "url": "https://builders.sodax.com/mcp",
      "headers": { "x-api-key": "<your key>" }
    }
  }
}

In Claude Code: claude mcp add --transport http sodax-builders https://builders.sodax.com/mcp --header "x-api-key: <your key>".

Profiles

A connection picks which tools it gets with ?profile=<name> on the URL or the x-sodax-profile header (stdio: --profile <name> or MCP_PROFILE).

An unknown profile is refused with HTTP 400; swap without a key with HTTP 403.

Partner fee

A builder can take a fee on the swaps its agent quotes: ?partnerAddress=<EVM address>&partnerFeeBps=<1-100> on the URL, or the x-sodax-partner-address and x-sodax-partner-fee-bps headers (stdio: SODAX_PARTNER_FEE_ADDRESS and SODAX_PARTNER_FEE_BPS). Set both or neither; anything else is refused with HTTP 400. The fee is taken from the amount sent, is part of the quote, and is never a tool input.

Swapping

With the swap profile, or all with a key, an agent swaps for a user like this. The user's wallet signs and sends every transaction; the server never signs.

1. sodax_swap_quote with the chains, tokens, amount and the user's fromAddress, plus toAddress for a non-EVM destination (an EVM one defaults to fromAddress). A ready quote returns steps (an approve when one is needed, after a reset_approve when the token needs its allowance zeroed first, then the swap), a quoteId, the intentHash the hub will know the swap by, and expiresAt, by which the swap must be mined and tracked. Without the addresses it returns a price only.

2. The user's wallet, on the source chain (each step's tx carries its chainId), signs and sends each step in order, each confirmed before the next. A wallet that supports EIP-5792 can send the quote's batch in place of the steps its replaces lists, adding calls to its params: those steps' {to, value, data}, in order. A reset_approve still goes first.

3. Right after the swap is sent, sodax_swap_submit_and_track with the swap transaction's txHash (from a batch, the hash wallet_getCallsStatus reports, not the batch id) and the quoteId (the quote's afterSend says so). Nothing submits the swap to SODAX until this call, and a first call after expiresAt (within 30 minutes of it) relays the deposit for a refund instead; later than that, the server has dropped the quote and alerts its operators. While the result has retryAfterSec, call it again after that many seconds.

4. To cancel a swap that hasn't been filled, sodax_swap_cancel returns the cancel transaction for the wallet to send; then call it again with cancelTxHash.

sodax_get_balance reads a wallet's balance when the user isn't sure they hold enough (the quote doesn't check), and sodax_resolve_token looks a token up when another swap tool returns UNKNOWN_TOKEN. Swaps start on an EVM spoke chain for now (not Sonic, the hub), and a quote from another chain returns UNSUPPORTED_SOURCE naming the ones that can; the destination can be any SODAX swap chain. Every result the tools return carries a nextStep for the agent; an input that fails a tool's schema gets the MCP SDK's validation error instead.

The server only returns transactions, so the agent also needs a wallet tool (or your app's signer) that can:

• give the user's address on the source chain, for fromAddress;

• switch to the chain a step's tx.chainId names, then send that tx (to, value, data) and return its hash;

• tell when a transaction is mined, since each step must be mined before the next;

• optionally, send an EIP-5792 wallet_sendCalls, to use the quote's batch.

Safety

The swap tools never sign or move funds. They also:

• refuse inputs that look like a private key, seed phrase or API key, and say so without echoing them;

• trust only their own quote cache and chain data when tracking or cancelling;

• reject slippage and deadlines outside their bounds instead of clamping them;

• warn, never block, when a quote is worth more than SODAX_SWAP_USD_WARN USD;

• refuse a quote whose output is worth under 90% of the amount sent (net of any partner fee) at the oracle's prices, and warn when the oracle can't price both sides;

• pick canary or production once, at startup (SODAX_ENV), never per request;

• take no RPC URL and no partner fee as a tool input;

• keep keys and RPC URLs out of logs, and addresses out of analytics and alerts.

Related MCP server: 1inch Cross-Chain Swap MCP Server

Tools

Network Configuration (9 tools)

Intents & Solver (9 tools)

Intent Relay (3 tools)

AMM & Liquidity (2 tools)

Money Market (6 tools)

Partners & Token (6 tools)

Swaps (need an API key)

See Swapping for the order they're called in.

Cross-Chain SDK Documentation (dynamic)

Tools prefixed with docs_ are automatically proxied from the SODAX docs MCP at docs.sodax.com. They update automatically when documentation changes — no manual sync needed.

Example Prompts

Once connected, try asking your AI coding assistant:

Cross-Network Swaps & Tokens

• "What networks does SODAX support for cross-chain swaps?"

• "Get available swap tokens across chains on Base"

• "How do I integrate cross-chain swaps with the SODAX SDK?"

Swaps (with an API key)

• "Swap 10 USDC on Arbitrum for ETH on Base from 0x..."

• "How much USDC does 0x... hold on Polygon?"

• "Is my swap done? The tx hash is 0x..."

• "Cancel that swap"

Solver Volume & Intent History

• "Show me cross-network solver volume for today"

• "Look up this intent transaction: 0x..."

• "Get intent history for this wallet address"

• "Quote me 100 USDC into SODA on Sonic"

• "What's the current oracle price the solver has for bnUSD on Avalanche?"

Cross-Chain Relay

• "Track the relay packets for this source tx: 0x..."

• "Has packet conn_sn=42 from this tx been executed yet?"

Money Market & Lending

• "What are the lending rates on SODAX money market?"

• "Show me borrowing APY rates across assets"

• "Get my money market position"

SDK Documentation

• "How do I integrate with the SODAX cross-chain SDK?"

• "Show me code examples for cross-network token swaps"

• "What SDK methods are available for intent-based execution?"

Data Sources

Local Development

# Install dependencies
pnpm install

# Run in development mode
pnpm dev

# Build for production
pnpm build

# Start production server
pnpm start

# Run the unit tests
pnpm test

CI & Local Checks

Every pull request, into any branch, runs .github/workflows/ci.yml, which executes the same four checks you can run locally:

Canary swap E2E

.github/workflows/e2e-canary.yml runs pnpm e2e:canary every day, and on demand, against a server it starts in the runner with SODAX_ENV=canary. Canary runs on mainnet chains, so it moves real funds: 5 USDC from whichever of Arbitrum and Base holds more to the other, so runs alternate. It never runs on pull requests. A failure posts the failing stage to Discord: setup means the swap never started (install, build or the server start failed, or an env value is missing or malformed); read_wallet means the balance reads failed; balance_floor means the wallet needs a top-up (USDC, or ETH for gas); quote means no ready quote came back, its steps weren't the USDC approve and swap this route needs, or its minimum output was under 97% of the amount. Nothing was signed in any of these. send means the swap wasn't sent, or the node refused it and no node had it (an approve may have been mined): check the logged swap hash, if there is one; track means a swap may be on chain and needs a look; arrival means it was solved but the funds haven't reached the destination yet. The script's output is printed after the run, and the server log after a failure, unless a secret (the API key, the wallet key with or without 0x, an RPC URL's host or path) shows up in either: that fails the run on its own, Discord gets the stage a secret in the logs, and neither is printed.

The secrets live in the canary-e2e GitHub environment, limited to the default branch: E2E_WALLET_PRIVATE_KEY (a wallet used only here), E2E_SODAX_API_KEY (a canary key), DISCORD_WEBHOOK_URL, and optionally SODAX_RPC_URL_42161 / SODAX_RPC_URL_8453, which the workflow passes to the server and the script as their RPC_CONFIG. AMOUNT is at most 20. A manual run with an amount the wallet doesn't hold makes a deliberate red run that sends nothing; a manual dry run only quotes, to check the environment and key before the wallet is funded.

To run it locally, start a server with pnpm build && SODAX_ENV=canary node dist/index.js (not pnpm start, which loads .env), then MCP_URL=http://127.0.0.1:3000/mcp?profile=swap SODAX_API_KEY=… pnpm e2e:canary with E2E_WALLET_PRIVATE_KEY exported from read -rs (not typed on the command line, where shell history keeps it). E2E_DRY_RUN=1 stops after the quote and needs no wallet. Don't run it while the workflow runs: both use the same wallet's nonces.

Git hooks (husky + commitlint + lint-staged)

pnpm install installs the hooks automatically via the prepare script:

• pre-commit — runs pnpm checkTs, pnpm test, then lint-staged (which runs biome check --write on staged files, applying both formatting and safe lint fixes).

• commit-msg — runs commitlint against the Conventional Commits spec. Messages like feat: add X pass; bad message is rejected.

To skip the hooks in a one-off emergency:

HUSKY=0 git commit -m "your message"

Don't make a habit of it — CI will still enforce the same checks on the PR.

Environment Variables

The server auto-loads a .env file on startup (via Node's --env-file-if-exists flag; the OpenTelemetry SDK that ships the logs needs Node ≥ 22.15.0). Copy .env.example to .env for local development; if no .env exists, every variable falls back to the default below. In production, Coolify injects these directly into the process environment.

Deployment

Environments

The server is deployed via Coolify with a branch-based promotion flow:

• Production — tracks master, serves https://builders.sodax.com

• Staging — tracks development (internal-only)

Promotion flow:

1. Feature branches → PR into development → auto-deploys to staging on merge.

2. development → PR into master → auto-deploys to production on merge.

Hotfixes can branch off master and PR directly into master, then be merged back into development.

Docker

docker build -t builders-sodax-mcp-server .
docker run -p 3000:3000 builders-sodax-mcp-server

Docker Compose

docker-compose up -d

Deployment notes

Coolify builds the Dockerfile, the same image CI builds. The image sets NODE_ENV=production; PORT defaults to 3000. With Coolify's "Include Source Commit in Build" on, the image also sets GIT_SHA, the version the log records carry (see Logging). nixpacks.toml is kept for a nixpacks build, which sets no GIT_SHA.

Operating the swap tools

Swap quotes live in the server's memory, so:

• Run one replica. Another replica doesn't have the first one's quotes.

• A merge deploys (into development for staging, into master for production), so check GET /health before merging, and before a restart. swapQuotes.open counts the quotes whose deposit hasn't reached the backend yet, signed or not, and swapQuotes.openUntil is when the last of them expires (its deadline plus 30 minutes). New quotes keep arriving while you wait, so on a busy server the count may not reach 0: deploy at a quiet moment, or once the openUntil you read has passed, accepting that quotes made since then are lost. A lost quote only matters if its deposit was sent: that deposit stays on chain until someone relays it.

• Set DISCORD_WEBHOOK_URL in production. The stop message and a crash alert say how many quotes were lost (a kill without SIGTERM, such as running out of memory, sends nothing). When an agent then tracks such a deposit with its chain and quoteId (a call with the quoteId alone is first asked for the chain), Discord gets "Swap deposit without its quote: relay it by hand", with the chain and the tx hash. Swap alerts are capped per hour: 20 for deposits this server checked, 5 for deposits it has no quote for (any key can name one) and 5 for tool errors. Past its cap an alert is held and listed in one post at the end of the hour; past 12 held per cap, it is only in the logs (alert: <kind>), so check them after a restart that lost many quotes.

• To recover one, relay the deposit tx with sodax_relay_submit_tx (the chain's relay id is in sodax_get_relay_chain_id_map). That puts the intent on the hub; past its deadline the backend's canceller refunds it, as it does when track relays an expired deposit.

• SODAX_SWAP_TOOLS_ENABLED=false turns the swap tools off without a rollback. It takes a restart, so the same wait applies.

Logging

Logs go to stderr as JSON (one line per record, URLs and keys redacted). With OTEL_LOGS_ENABLED=true the same records also ship to unified logging, with SeverityText in lowercase (info, warn, error) as the backend sends it. Every record of one HTTP request (or one stdio tool call) carries request.id, so a call can be followed from the agent's request to the answer; a swap's quote, track and cancel calls are joined by quote.id, tx.hash and intent.hash. Each MCP response carries its request's id in an X-Request-Id header, for a builder to quote when reporting a problem (over SSE, the tool calls' ids are on the POST /messages responses, not on the stream), and calls to SODAX's own APIs send it in the same header. Names follow the OpenTelemetry conventions where one exists. The records to query and alert on:

A record's body is a constant (Body = 'Tool call'); what varies is in its attributes. One failure is one record of each kind: the data services don't log what Upstream call, Chain read and Tool call already say.

error.type says why:

• HTTP request, the guard that refused it: UNKNOWN_PROFILE, SWAP_PROFILE_OFF, API_KEY_REQUIRED, API_KEY_MALFORMED, INVALID_PARTNER_FEE, SSE_KEY_MISMATCH, SSE_SESSION_LIMIT, SSE_SESSION_NOT_FOUND, BATCH_TOO_LARGE, RATE_LIMITED, METHOD_NOT_ALLOWED, INVALID_JSON, BODY_TOO_LARGE, INVALID_REQUEST, INTERNAL. A refusal the MCP SDK's transport sends itself (406, 415) has only its status.

• Tool call the SDK refused before a handler ran: TOOL_NOT_FOUND, INVALID_ARGUMENTS, TOOL_DISABLED, TOOL_CALL_REFUSED.

• A swap tool's failure: the code the tool returned.

• A data or docs tool's failure, by its cause:

  • UPSTREAM_NOT_FOUND, UPSTREAM_4XX, UPSTREAM_5XX, UPSTREAM_TIMEOUT, UPSTREAM_UNREACHABLE, UPSTREAM_BAD_RESPONSE;

  • RATE_LIMITED (a 429 on the caller's key) or UPSTREAM_RATE_LIMITED (a 429 on a keyless call, so this server's shared egress);

  • INVALID_INPUT;

  • DOCS_RPC_ERROR, DOCS_TOOL_ERROR, DOCS_UNAVAILABLE (a 4xx from the docs server: its endpoint moved or gone);

  • INTERNAL when nothing explains it.

A Tool call is at warn when the failure is on SODAX's side: UPSTREAM_RATE_LIMITED, UPSTREAM_5XX, UPSTREAM_TIMEOUT, UPSTREAM_UNREACHABLE, UPSTREAM_BAD_RESPONSE, DOCS_UNAVAILABLE, UPSTREAM_UNAVAILABLE, CHAIN_UNAVAILABLE, SWAP_MISMATCH, PRICE_OFF_MARKET, INTERNAL.

Export is batched and bounded: a gateway outage drops records and never slows a tool call; a stop or crash flushes what it can; a failure to start leaves the logs on stderr and the server serving. GET /health reports unifiedLogging (on, records written, exported and failed, lastFailureAt), so a token or allowlist problem shows there before Grafana; the heartbeat keeps a quiet server from looking like a stopped producer. A batch the gateway accepted but partly rejected counts as exported and is logged as a warning. The hub's unified-logging-connect skill has the connect check.

API Endpoints

Errors and limits

/mcp answers HTTP errors with a JSON-RPC error, {"jsonrpc":"2.0","error":{"code":…,"message":"…"},"id":null}. Read error.message; error is an object here.

Every MCP response carries an X-Request-Id header (over SSE, on the POST /messages responses). Quote it when reporting a problem: the server's logs find the request by it.

On /sse and /messages, the rate limits, an unknown session and server errors answer {"error":"…"}; the SSE transport's own errors (a message it can't parse, for one) are plain text.

Limits are per client IP (IPv6 per /56): 100 requests a minute on all routes, and 60 a minute on /mcp, /sse and /messages, where each message of a /mcp batch counts. A rate-limit 429 carries Retry-After and RateLimit-* headers. SSE allows 10 open sessions per client and 200 in all, and closes a session after an hour without a message.

Related

• SODAX — sodax.com

• SDK Documentation — docs.sodax.com (proxied automatically)

License

MIT