What is this?

@y0exchange/mcp is a Model Context Protocol server that gives AI agents real-time access to DeFi — balances, prices, gas, swap quotes, transaction history, and the ability to execute swaps and transfers.

Connect it to Claude, ChatGPT, or any MCP-compatible AI client. Your users talk to AI, AI talks to the blockchain.

User  →  AI Agent  →  @y0exchange/mcp  →  Blockchain
                            ↓
                     y0 Signing Service (user signs on their device)

Non-custodial by design. y0 never touches private keys. Write operations build unsigned transactions — the user always signs on their own device.

Quick Start

1. Get your API key

Sign in at app.y0.exchange → API Keys → copy your key.

2. Add connector (recommended)

The simplest way — works on Claude Desktop, claude.ai, Claude Mobile, and ChatGPT:

1. Open your AI app → Settings → Connectors → Add custom connector
2. Name: y0
3. URL: https://mcp.y0.exchange/mcp?key=YOUR_API_KEY
4. Save — done!

No installs, no config files, no terminal. The API key links to your wallet — the AI agent automatically knows your address and permissions.

For developer IDEs (Cursor, Windsurf)

Add to your MCP config (e.g. .cursor/mcp.json):

{
  "mcpServers": {
    "y0": {
      "command": "npx",
      "args": ["-y", "@y0exchange/mcp"],
      "env": {
        "Y0_API_KEY": "y0_your_api_key_here"
      }
    }
  }
}

Claude Code

claude mcp add --transport http y0 https://mcp.y0.exchange/mcp?key=YOUR_API_KEY

Any MCP client (stdio)

Y0_API_KEY=y0_... npx @y0exchange/mcp

The server communicates over stdio — compatible with any MCP client.

Read-only mode

Without Y0_API_KEY, read-only tools (balances, prices, gas, quotes, history) still work. Omit the key to experiment without an account.

Remote Server (HTTP)

The hosted remote server at mcp.y0.exchange powers the connector approach above. You can also self-host it.

Self-host the remote server

# Build
pnpm --filter @y0exchange/mcp build

# Run
pnpm --filter @y0exchange/mcp start:remote

# Or with Docker
docker build -f mcp/Dockerfile -t y0-mcp-remote .
docker run -p 3100:3100 \
  -e SIGNING_SERVICE_URL=https://api.y0.exchange \
  -e ZEROX_API_KEY=your_key \
  y0-mcp-remote

The remote server exposes:

• POST /mcp — Streamable HTTP MCP endpoint
• GET /health — health check

Environment variable PORT controls the listening port (default: 3100).

How it differs from stdio

| | stdio (npx) | Remote (HTTP) | |--|---------------|---------------| | Runs on | User's machine | Your server | | Transport | stdin/stdout | Streamable HTTP | | Works on mobile | No | Yes | | Works on claude.ai | No | Yes | | Auth | Y0_API_KEY env var | ?key= in URL or Authorization header | | Deployment | None (npm) | Docker / any Node.js host |

Tools

Read-only — work out of the box, no API keys required

| Tool | Description | |------|-------------| | get_balance | Native + ERC-20 token balances for any wallet | | get_portfolio | Aggregated portfolio across all chains with USD values | | get_price | Real-time token prices with 24h change | | get_quote | Swap quotes with routing preview, fees, and gas estimate | | get_gas | Gas prices across chains with USD cost estimates | | get_history | Transaction history with smart classification |

Write — requires Y0_API_KEY

| Tool | Description | |------|-------------| | swap | Build unsigned swap tx → user approves on device | | send | Build unsigned transfer tx → user approves on device |

Write tools use your API key to identify your wallet. The AI agent never needs to ask for your address — it's resolved automatically from the key.

Supported Chains

| Chain | ID | Status | |-------|----|--------| | Ethereum | 1 | Production | | BNB Chain | 56 | Production | | Arbitrum | 42161 | Production | | Base | 8453 | Production | | Polygon | 137 | Production |

Configuration

All configuration is via environment variables. None are required for read-only tools.

Core

| Variable | Description | Default | |----------|-------------|---------| | Y0_API_KEY | Your y0 API key (required for swap/send) | — | | SIGNING_SERVICE_URL | y0 Signing Service endpoint | https://api.y0.exchange |

Swap Providers

| Variable | Description | |----------|-------------| | ZEROX_API_KEY | 0x swap API key (tried first) | | ONEINCH_API_KEY | 1inch swap API key (fallback) |

Block Explorers (for get_history)

| Variable | Description | |----------|-------------| | ETHERSCAN_API_KEY | Etherscan API key | | BSCSCAN_API_KEY | BSCScan API key | | ARBISCAN_API_KEY | Arbiscan (falls back to Etherscan key) | | BASESCAN_API_KEY | BaseScan (falls back to Etherscan key) | | POLYGONSCAN_API_KEY | PolygonScan (falls back to Etherscan key) |

Pricing

| Variable | Description | |----------|-------------| | COINGECKO_API_KEY | CoinGecko Pro key (optional, free tier works) |

How Swaps Work

1. User says: "Swap 1 ETH to USDC"

2. AI calls get_quote → shows price, fees, slippage

3. User confirms → AI calls swap (no wallet address needed — resolved from API key)

4. MCP authenticates with y0 Signing Service via Y0_API_KEY
   → builds unsigned transaction
   → sends push notification to user's mobile app

5. User reviews and signs on their device (biometric + wallet)

6. Transaction executes on-chain

Your keys never leave your device. The MCP server and y0 Signing Service only handle unsigned transaction payloads.

Example Conversations

"What's my portfolio worth?"

AI calls get_portfolio → returns breakdown by chain, token allocations, total USD value

"How much gas would a swap cost on Base right now?"

AI calls get_gas with chainId 8453 → returns gas price + USD estimates for different tx types

"Swap 500 USDC to ETH on Arbitrum"

AI calls get_quote → shows expected output → user confirms → swap builds unsigned tx → user signs

"Send 0.5 ETH to vitalik.eth"

AI calls send → builds unsigned transfer → user signs on device

Skill: Smarter DeFi Workflows

The MCP server gives Claude access to DeFi tools. The y0 DeFi Skill teaches Claude how to use them well — checking balances before swaps, warning about gas costs, recommending optimal chains, and following DeFi best practices automatically.

What it adds

• Pre-swap safety checks (balance, gas, slippage recommendations)
• Portfolio analysis with concentration risk warnings
• Cross-chain gas comparison and routing suggestions
• Confirmation gates before any write operation
• Domain expertise: stablecoin slippage, native token reserves, test transaction recommendations

Install the skill

Claude.ai:

1. Download the skill/ folder from this repo (or download ZIP)
2. Go to Settings → Capabilities → Skills
3. Click Upload skill and select the zipped skill/ folder
4. Make sure your y0 MCP connector is also connected

Claude Code:

# Place the skill folder in your Claude Code skills directory
cp -r skill/ ~/.claude/skills/y0-defi-assistant/

Verify it works

Ask Claude: "Check my crypto portfolio" — it should automatically call get_portfolio, present a clear breakdown, and note any concentration risks or gas optimization opportunities.

For B2B Partners

Building an AI-powered trading product? y0 provides the infrastructure:

• MCP server — this package, plug into any AI agent
• Signing UI — white-label transaction approval widget
• Signing Service — managed backend for transaction building + lifecycle
• B2B Portal — API keys, usage dashboards, billing

Get in touch to set up your integration.

Architecture

┌───────────────────────────────────────────────────────────┐
│                    AI Agents                               │
│  Claude Desktop / Claude Code / Cursor / GPT / custom     │
│  claude.ai / Claude Mobile                                │
└──────────┬───────────────────────────────┬────────────────┘
           │ stdio (local)                 │ HTTP (remote)
           │ npx @y0exchange/mcp           │ .../mcp?key=YOUR_API_KEY
           ▼                               ▼
┌──────────────────────────────────────────────────────────┐
│                   @y0exchange/mcp                         │
│                                                          │
│  ┌─────────────────┐  ┌──────────────────┐               │
│  │   Read Tools     │  │   Write Tools    │               │
│  │                  │  │                  │               │
│  │  get_balance     │  │  swap ─────────────► y0 Signing  │
│  │  get_portfolio   │  │  send ─────────────► Service     │
│  │  get_price       │  │                  │               │
│  │  get_quote       │  └──────────────────┘               │
│  │  get_gas         │                                     │
│  │  get_history     │                                     │
│  └────────┬─────────┘                                     │
└───────────┼───────────────────────────────────────────────┘
            │
   ┌────────▼─────────┐
   │   Blockchain RPCs │
   │   CoinGecko API   │
   │   0x / 1inch APIs │
   │   Block Explorers │
   └───────────────────┘

Mobile / Web (claude.ai, Claude Mobile):
  Uses remote HTTP server — no local process needed.

Desktop / CLI (Claude Desktop, Claude Code, Cursor):
  Can use either stdio (npx) or remote HTTP.

Development

# Clone the monorepo
git clone https://github.com/y0exchange/y0exchange.git
cd y0exchange

# Install dependencies
pnpm install

# Build
pnpm --filter @y0exchange/mcp build

# Run stdio server (local dev)
pnpm --filter @y0exchange/mcp start

# Run remote HTTP server (local dev)
pnpm --filter @y0exchange/mcp start:remote

# Watch mode (rebuilds on change)
pnpm --filter @y0exchange/mcp dev

License

MIT — use it freely in your products. See LICENSE for details.