@y0exchange/mcp
Let AI agents trade crypto. Non-custodial. Multi-chain. One MCP server.
---
## What is this?
**@y0exchange/mcp** is a [Model Context Protocol](https://modelcontextprotocol.io/) 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](https://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`):
```json
{
"mcpServers": {
"y0": {
"command": "npx",
"args": ["-y", "@y0exchange/mcp"],
"env": {
"Y0_API_KEY": "y0_your_api_key_here"
}
}
}
}
```
### Claude Code
```bash
claude mcp add --transport http y0 https://mcp.y0.exchange/mcp?key=YOUR_API_KEY
```
### Any MCP client (stdio)
```bash
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
```bash
# 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](https://0x.org) swap API key (tried first) |
| `ONEINCH_API_KEY` | [1inch](https://1inch.io) 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 skill.zip](https://github.com/y0exchange/mcp/raw/main/skill.zip)
2. Go to **Settings → Capabilities → Skills**
3. Click **Upload skill** and select the downloaded `skill.zip`
4. Make sure your y0 MCP connector is also connected
**Claude Code:**
```bash
# 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](https://www.npmjs.com/package/@y0exchange/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](https://y0.exchange) 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
```bash
# 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](./LICENSE) for details.
---
Built by y0.exchange — AI-native DeFi infrastructure