# @usenami/mcp-server

MCP server giving AI agents (Claude Desktop, Cursor, MCP-aware clients) direct access to **Usenami** — a multi-venue perpetual futures funding rate & real-world-asset spread API built for arb-aware agents.

- Bazaar listing: <https://agentic.market/services/api-usenami-io>
- API base: <https://api.usenami.io>
- Paid via **x402** USDC on Base mainnet (Coinbase CDP Facilitator)

## Tools

### Free (no wallet required)

| Tool | Description |
|---|---|
| `usenami_venues_list` | Catalog of perpetual futures venues Usenami tracks (CEX + DEX, incl. Hyperliquid HIP-3 sub-venues). |
| `usenami_venues_health` | Last-update timestamps + freshness status per venue. Use to verify currency before a paid call. |

### Paid ($0.001 USDC each, requires `X402_PRIVATE_KEY`)

| Tool | Description |
|---|---|
| `usenami_funding_current` | Per-venue funding rates across 30+ exchanges. Optional `symbol` filter (`BTC-PERP`, `ETH-PERP`, …). |
| `usenami_perp_funding_spread` | Cross-venue funding-rate spread snapshot for a base ticker. Returns long-side / short-side venues + spread in bps. |
| `usenami_perp_oracle_families` | Oracle price-source family classification. Identify venues that share a price source (no genuine arbitrage edge between same-family pairs). |
| `usenami_rwa_perp_coverage` | RWA perpetual coverage on Hyperliquid HIP-3 DEXes. 6 sub-venues × ~139 tickers across stocks / metals / forex / commodities / indices / pre-IPO synthetics. Optional `asset_class` filter. |

## Setup — Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "usenami": {
      "command": "npx",
      "args": ["-y", "@usenami/mcp-server"],
      "env": {
        "X402_PRIVATE_KEY": "0xYOUR_PRIVATE_KEY"
      }
    }
  }
}
```

Restart Claude Desktop. The 6 tools appear in the tool drawer.

`X402_PRIVATE_KEY` is **optional** — the 2 free tools work without it. Paid tools return a clear error if the env is missing.

## Setup — Cursor

In Cursor settings → MCP, add the same JSON block as above. Cursor invokes the server via stdio.

## Wallet preparation

`X402_PRIVATE_KEY` must be an EVM private key of a wallet holding **USDC on Base mainnet**:
- USDC contract: `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`
- Network: Base mainnet (chain id 8453)
- Suggested minimum: 0.05 USDC (~50 paid calls of headroom)
- **No ETH needed** — the Coinbase CDP Facilitator covers gas via EIP-3009 meta-transactions.

Pricing is $0.001 USDC per paid call. Settlement is on-chain, irrevocable, no subscription.

## Local development

```bash
npm install
npm run build
node dist/index.js   # talks JSON-RPC over stdio — use MCP Inspector to drive it
```

For dev (no build step):
```bash
npm run dev
```

To test a paid tool manually:
```bash
X402_PRIVATE_KEY=0x... npm run dev
# Then in another terminal use @modelcontextprotocol/inspector
```

## What you get back — response shapes

All paid responses are JSON. Examples:

`usenami_funding_current` → `{ symbol: "BTC-PERP" | null, rates: [{ source_id, venue, symbol, rate, updated_at }, ...] }`

`usenami_perp_funding_spread` → `{ ticker, venues_count, spread: { ticker, long_venue, long_rate, short_venue, short_rate, spread_bps, updated_at } | null }`

`usenami_perp_oracle_families` → `{ families: [{ family, method, venues }, ...], total_venues }`

`usenami_rwa_perp_coverage` → `{ items: [{ ticker, venue, asset_class, funding_rate, updated_at }, ...], tickers_count, venues_count }`

## Architecture

- **Transport**: stdio (Claude Desktop, Cursor, MCP Inspector). Streamable HTTP remote planned for v0.2.
- **Payment**: `x402-fetch` wraps `fetch` — intercepts 402 responses, signs EIP-3009 authorization with the local wallet, retries with the `X-Payment` header. Wallet PK never leaves the local process.
- **Custody**: zero — there is no MCP-side wallet. The customer brings their own PK.

## Differentiation vs CoinGecko / CMC

Usenami is **perp-first**: funding rates and venue spreads are the primary product, not an afterthought. The two unique offers:

1. **Oracle family disclosure** — explicit basis-risk awareness. Cross-venue strategies between same-family venues (`cex_aggregated`, `pyth_stork`, etc.) carry no real edge; Usenami exposes this directly.
2. **RWA on HIP-3** — 139 RWA tickers (stocks, metals, forex, commodities, pre-IPO) on Hyperliquid HIP-3 sub-venues. CoinGecko/CMC have no comparable surface.

## License

MIT