OmniRoute Bridge MCP

One terminal for cross-chain funding, platform onboarding, and multi-wallet gas.

Web App · Source · Relay

Zero API keys. Zero npm runtime dependencies. MIT-licensed Node.js SDK, CLI, and MCP server. Supports Ethereum, Base, Arbitrum, Optimism, Polygon, BNB Smart Chain, HyperEVM, and Solana.

Free to install and use: no subscription or API-key purchase. Every Relay quote includes a 30 bps (0.30%) integrator fee, plus applicable Relay and network fees. It is not fee-free bridging. Fast routes may settle in roughly 2 seconds, but sub-3-second execution is not guaranteed; quote latency, approvals, network confirmation and final settlement vary. Always use the live quote estimate.

Quick start

Run directly from GitHub without cloning or waiting for an npm publication. No secret or environment variable is needed.

Claude Desktop, Cursor and Windsurf

Use this entry in your client's MCP configuration:

{
  "mcpServers": {
    "omniroute": {
      "command": "npx",
      "args": ["-y", "github:c-viper-work/omniroute-bridge-mcp", "mcp"]
    }
  }
}

Or run these one-line CLI commands:

npx -y github:c-viper-work/omniroute-bridge-mcp chains --json
npx -y github:c-viper-work/omniroute-bridge-mcp mcp

From a local source checkout (no installation required):

node bin/omniroute.js chains --json
node bin/omniroute.js quote --from base --to arbitrum --token USDC --to-token ETH --amount 10 --json
npm test
npm start

For a local MCP checkout, use "command": "node" and "args": ["/absolute/path/to/omniroute-bridge-mcp/bin/omniroute.js", "mcp"].

Try asking: “Quote 10 USDC from Base to native POL on Polygon,” or “Plan gas funding for these three wallets.” All six tools return unsigned plans and never hold keys, sign, broadcast, or trade.

Publication and GitHub Pages deployment are separate maintainer actions; this repository does not automatically publish itself.

Related MCP server: persistenceone-bridgekitty

Verify safety in 60 seconds

1. Zero npm dependencies: package.json has "dependencies": {}, no devDependencies, and no install scripts.

2. Compact, unminified source: approximately 850 lines of readable ESM JavaScript across src/ and docs/ (excluding byte-identical browser copies of shared modules), with zero build step.

3. Read-only MCP & CLI: all 6 tools never accept, store, or touch private keys or seed phrases; executeUrl deep links carry only route intent parameters, never raw transaction calldata. Inspect src/service.js.

4. Strict browser CSP: docs/index.html locks connect-src exclusively to https://api.relay.link, with default-src 'none' and script-src 'self'.

5. Bounded wallet preflight: docs/lib/wallet.js verifies before any EVM eth_sendTransaction that ERC-20 approve/transfer calls target only the quoted input token and never exceed the quoted input amount. docs/app.js caps deep-link slippage at <= 500 bps (5.00%) and warns on custom recipients.

Browser wallet signing in the Web Terminal supports all 7 EVM source chains: Ethereum, Base, Arbitrum, Optimism, Polygon, BNB Smart Chain, and HyperEVM, using an injected EIP-1193 wallet. Solana source routes return unsigned transaction plans for external signing.

CLI

# List supported chains and tokens
node bin/omniroute.js chains --json

# Read-only bridge preview
node bin/omniroute.js quote --from solana --to base --token USDC --to-token ETH --amount 10 --json

# Include real source and destination wallet addresses for executable quote data
node bin/omniroute.js quote --from base --to arbitrum --token USDC --to-token ETH --amount 10 --sender YOUR_EVM_ADDRESS --recipient YOUR_EVM_ADDRESS --json

# Polymarket: Polygon USDC.e plus an additional approximately $2 source spend for POL
node bin/omniroute.js polymarket --from base --token USDC --amount 50 --recipient YOUR_POLYGON_ADDRESS --json
# Skip the extra gas route
node bin/omniroute.js polymarket --from base --token USDC --amount 50 --no-gas --json

# HyperEVM native HYPE
node bin/omniroute.js hyperliquid --from arbitrum --token USDC --amount 25 --mode hyperevm_hype --json
# Prepare Arbitrum USDC for the official Hyperliquid deposit flow
node bin/omniroute.js hyperliquid --from base --token USDC --amount 25 --mode arbitrum_usdc --json

# Spend 2 source USDC per destination wallet to buy Polygon POL
node bin/omniroute.js refuel --from base --token USDC --to polygon --amount-per-wallet 2 --recipients ADDRESS_1,ADDRESS_2 --sender YOUR_SOURCE_ADDRESS --json

node bin/omniroute.js status --request-id RELAY_REQUEST_ID --json
node bin/omniroute.js --help

--sender is supported by all quote-producing commands. Without it, returned data is marked previewOnly; do not sign preview calldata. For cross-VM routes, also specify the real destination recipient. --slippage-bps 50 means 0.50% on the quote command. --gas-usd changes the additional Polymarket gas budget (0–50 USD); --no-gas ignores that budget. Value flags also accept --flag=value. --mode both quotes two full-size Hyperliquid funding routes and doubles the source input budget.

Onboarding boundaries

• Polymarket: the preset targets Polygon bridged USDC.e (0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174), distinct from native USDC. Optional gas is a separate POL route, skipped when the source is already native Polygon POL. Use the intended platform wallet; a transfer to an arbitrary EOA does not create or fund every kind of Polymarket account automatically. Account setup, approvals and current platform deposit requirements still apply.

• HyperEVM: native HYPE on chain 999 funds EVM gas. This is not Hyperliquid L1 perpetuals collateral.

• Arbitrum USDC: prepares funds for the official Hyperliquid deposit flow; it does not call Bridge2. Keep Arbitrum ETH for the separate deposit transaction and check the platform's current minimums.

• Gas refuel: amountPerWallet is input in the source token. Output native gas is quoted after fees. Up to 20 recipients, four concurrent quote requests, ordered unsigned steps. Duplicate recipients mean repeated allocations. Execution is not atomic; track each submitted transaction separately.

• USD gas budget: estimated using the primary quote's source USD valuation. The gas route is additional spend, not deducted from the primary amount. It is not a guarantee of that many dollars of POL after fees; missing or invalid USD pricing causes an explicit error. The primary input/output USD ratio must be between 0.5 and 2.0.

See Polymarket's official bridge guide and Hyperliquid onboarding for the destination platform flows.

Node.js SDK

import {
  getBridgeQuote,
  getPolymarketOnboardPlan,
  getHyperliquidOnboardPlan,
  planMultiWalletGasRefuel,
  checkBridgeOrderStatus,
  fetchAppFeeBalances
} from 'omniroute-bridge-mcp';

const quote = await getBridgeQuote({
  fromChain: 'base', toChain: 'arbitrum',
  fromToken: 'USDC', toToken: 'ETH', amount: '10',
  userAddress: 'YOUR_SOURCE_ADDRESS',
  recipientAddress: 'YOUR_DESTINATION_ADDRESS',
  slippageBps: 50
});
console.log(quote.currencyOut, quote.fees, quote.steps);
// No signing occurs. Review and execute with your own wallet integration.

In a source checkout, import from ./src/index.js. The illustrative address placeholders must be replaced with valid addresses. To preview instead, omit the address fields.

All network methods accept a final options object: { fetchImpl, timeoutMs, signal, feeRecipient, feeBps }. Default timeout is 15 seconds. Injectable fetch supports deterministic offline tests. Fee overrides are explicit testing/configuration options; CLI and MCP expose no fee override. There is no automatic retry of quotes or transactions.

resolveToken(chain, rawAddress, customDecimals) supports custom tokens with explicit decimals. getBridgeQuote accepts fromTokenDecimals / toTokenDecimals for raw addresses. Registered tokens use the audited registry decimals; arbitrary mint/contract metadata is not fetched. Address validation checks syntax and Solana decoded length, not ownership or token safety.

Use decimal strings for exact amounts. parseUnits returns BigInt, rejects zero, negatives, scientific notation, excess decimals and uint256 overflow. JavaScript numbers cannot recover precision already lost before the call. formatUnits returns an exact decimal string, with support for zero and negative values for display.

Quote result

Every quote and onboarding/refuel plan includes an executeUrl: a clickable Web Terminal link containing only route intent, never calldata. MCP agents should always show this link. Opening it fetches a fresh quote; preview quotes must never be executed.

Results include requestId, chain metadata, input/output amounts and USD values, minimum output, rate, impact, estimated seconds, gas/relayer/app fees, payload, quotedAt, previewOnly and ordered steps. Missing upstream estimates are null, never invented. Relay step data and check endpoints are preserved, including non-EVM data. A signature or Solana transaction cannot be passed to EVM eth_sendTransaction.

MCP tools

Each tool has a title, read-only/non-destructive/idempotent annotations and descriptions on every parameter. openWorldHint is false only for the local registry tool. The idempotent annotation describes absence of transaction side effects; live quotes and request IDs can change. Metadata coverage is locally tested; no external Glama grade is claimed.

The stdio server accepts modern newline-delimited JSON and legacy Content-Length framing (UTF-8 byte counts), fragmented frames, notifications, and initialize, ping, tools/list, tools/call, resources/list, prompts/list. Responses use each request's framing. Stdout contains only protocol responses in MCP mode. Messages are limited to 1 MiB.

Fees and Relay integration

Every HTTP quote request includes:

{
  "appFees": [{
    "recipient": "0x8c2279495094C284e1293cdE9DBC52cc4f55C6bd",
    "fee": "30"
  }]
}

The dedicated project wallets are EVM 0x8c2279495094C284e1293cdE9DBC52cc4f55C6bd and Solana FJCcoqJHmoJyuthUY773gnxBsAY8yQuAgfYwL3zETVVW; both are disclosed by listSupportedRoutes().integratorFee.

The Relay app fee recipient is always an EVM address, including Solana routes. The default is centralized and the HTTP boundary reconstructs the fee field even when a low-level caller omits it. Default balances can be queried with fetchAppFeeBalances(); there is no automatic fee withdrawal.

Endpoints: POST https://api.relay.link/quote, GET /intents/status/v2?requestId=..., GET /app-fees/{wallet}/balances. This project intentionally uses the requested /quote endpoint. Relay currently documents it as deprecated; compatibility and public rate limits are upstream concerns. The project does not promise unlimited API access or perpetual upstream availability. HTTP, JSON, timeout and cancellation errors propagate clearly; no private key or API key is required.

Architecture

CLI / MCP client / Node.js application
                 |
             service.js      presets, validation, batch aggregation, tool schemas
                 |
              relay.js       HTTP boundary, fees, timeout, normalization
                 |
          api.relay.link      unsigned quote / status

constants.js                 chain registry and exact amount arithmetic

src/index.js exports the public SDK. src/mcp-server.js provides stdio transport. src/cli.js handles CLI arguments; bin/omniroute.js is the executable entry. No signing keys, telemetry, database, server account or hosted backend are needed.

Development and release

npm test
node --check src/service.js
npm pack --dry-run
# Optional, with Docker installed:
docker build -t omniroute-bridge-mcp .
docker run --rm -i omniroute-bridge-mcp

Tests use native node:test, node:assert, deterministic Relay fixtures, stream fragmentation and CLI subprocesses. They never spend funds. They cover fee injection, EVM/Solana directions, input precision and validation, all service/tool/CLI entry points and protocol framing. Mock tests do not establish live liquidity, settlement performance, browser wallet compatibility or platform crediting.

Always verify recipient addresses and wallet transaction details before signing, never execute stale quotes, and never resend a transaction whose submission status is unknown. Nothing in the SDK, CLI, or MCP server automatically broadcasts a transaction.

License

MIT · maintained by c-viper-work.

Static web app

Open an executeUrl to prefill the route and automatically request a fresh live quote when an amount (and refuel recipients) is present. Copy route link shares the current reviewed route; the link also appears in the unsigned JSON / CLI details. Links can contain wallet addresses. Unsupported chains or custom tokens require manual review rather than automatically quoting a different token. Wallet network changes preserve the connection; account changes update the sender. Both invalidate stale quotes. Signing still requires explicit wallet confirmation.

Serve docs/ over HTTPS (GitHub Pages) or a local HTTP server, for example python3 -m http.server 8080 --directory docs. Open http://localhost:8080. The app calls Relay directly, with no keys or third-party JavaScript. Wallet execution requires an injected EIP-1193 provider; CLI/JSON export also works without a wallet. CLI commands request fresh unsigned plans, never broadcast. Quotes must pass the 60-second freshness check before the first send. Subsequent transactions use that first-send time for quote freshness, with a batch limit of transaction count × receipt timeout (120 seconds per transaction by default). Chain/account changes require a new quote. Direct native values and input-token ERC-20 approve/transfer calls are bounded by the quoted input. Transaction hashes remain visible after failures; never automatically retry a submitted plan. Source confirmation and Relay destination delivery are separate.

After changing shared quote modules, synchronize the deployed browser copies:

cp src/constants.js src/relay.js src/service.js docs/lib/
npm test

Tests enforce byte equality for these modules. No build step is required.