Content
# @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
