@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):

{
  "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

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):

npm run dev

To test a paid tool manually:

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