orcpin-mcp

orcpin-mcp

MCP server for Orcpin — block-anchored on-chain wallet & DeFi snapshots on Base, pre-flight x402 endpoint-reliability checks, and deterministic trade-log calculators for trading agents (holding periods, day-trade counts, T+1 settlement dates), paid transparently via x402 — plus a free x402 resource directory that needs no wallet at all. Drop it into Claude Desktop, Cursor, or any MCP-compatible agent runtime and your agent gets nine tools:

Tool	What it returns	Price
orcpin_x402_directory	Search the public x402 ecosystem: ~1,000 paid endpoints from the CDP Bazaar ranked by distinct paying wallets over 30 days. Filter by text, network and max price. Works with no wallet configured.	Free
orcpin_wallet_snapshot	Native ETH + ERC-20 balances, account flags, derived metrics (wallet type, activity tier, gas runway)	$0.02
orcpin_defi_snapshot	Wallet snapshot + live Aave v3 collateral/debt/health factor + derived risk metrics (net equity, LTV utilization, leverage, health-factor band, drawdown tolerance)	$0.05
orcpin_batch_snapshot	Many addresses in one paid call, anchored to a single block (up to 1,000)	$0.02/addr · 20–40% volume off at 10/50/100
orcpin_endpoint_reliability	Pre-flight an x402 endpoint before paying it: reachability/uptime rate, valid-402 rate, latency p50/p95/p99, last status, sampled paid-delivery check. Facts only — no trust score.	$0.01
orcpin_endpoint_reliability_batch	Sweep a whole tool list of x402 endpoints in one call (up to 150)	$0.01/endpoint · 20–40% volume off at 10/50/100
orcpin_holding_period	Per-lot days held, the exact date each lot's gain turns long-term (IRC §1222 cited), FIFO / specific-ID sell allocation with realized gain per lot (up to 500 lots)	$0.02
orcpin_day_trade_count	Matched same-day buy/sell pairs in the rolling five-TRADING-day window on a versioned NYSE holiday calendar, with FINRA Rule 4210's definition quoted — never applied (up to 1,000 trades)	$0.02
orcpin_settlement_dates	T+1 settlement date per trade and settled/unsettled status as of any date, weekends & market holidays handled (SEC Rule 15c6-1 cited)	$0.02

Building a trading agent only? Add "ORCPIN_TOOLSETS": "trading" to the env and the server exposes just the three calculators ("defi" gives just the five chain/reliability tools; default is all eight paid tools). orcpin_x402_directory is free and always exposed regardless of the toolset — it is the one tool that works before you have a funded wallet. The trading calculators are pure arithmetic on the trades you pass in — counts, dates, and dollars with the governing rule quoted in every response; nothing you send is ever stored.

Payment is handled for you: the server signs a gasless USDC authorization (EIP-3009) with the wallet you configure. No ETH needed — only USDC.

Quick start

You need a Base wallet with a small USDC balance (a few dollars covers thousands of calls).

1. Get a funded wallet. Use a dedicated, low-balance wallet (the key lives in a config file). Fund it with USDC on Base mainnet — buy on Coinbase and withdraw to the Base network, or bridge USDC to Base. No ETH required (settlement is gasless for you). You'll need the wallet's private key (0x + 64 hex).

2. Add the server to your client.

Claude Desktop

Edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):

{
  "mcpServers": {
    "orcpin": {
      "command": "npx",
      "args": ["-y", "orcpin-mcp"],
      "env": {
        "ORCPIN_PRIVATE_KEY": "0xYOUR_FUNDED_BASE_WALLET_KEY",
        "X402_NETWORK": "eip155:8453"
      }
    }
  }
}

Fully quit and reopen Claude Desktop.

Cursor

Add the same block to ~/.cursor/mcp.json (global) or .cursor/mcp.json (per-project).

Claude Code

claude mcp add orcpin -e ORCPIN_PRIVATE_KEY=0xYOUR_KEY -- npx -y orcpin-mcp

How to use it

Once it's loaded, the agent sees the tools and calls them on its own when relevant. The directory tool works immediately; the rest need a funded wallet. You just ask in natural language:

• "What x402 search APIs are there on Base under a cent?" → orcpin_x402_directory (free, no wallet needed)
• "Use orcpin to get the DeFi snapshot for 0xabc…" → orcpin_defi_snapshot
• "What's the balance and gas runway for 0xabc…?" → orcpin_wallet_snapshot
• "Snapshot these 50 treasury addresses at one block." → orcpin_batch_snapshot
• "Before you call https://some-api.example/v1/x, check whether it's reliable." → orcpin_endpoint_reliability
• "Sweep these 20 endpoints for uptime and latency." → orcpin_endpoint_reliability_batch
• "When do these lots go long-term, and what's the realized gain if I sell 150 today?" → orcpin_holding_period
• "How many day trades are in my last five trading days?" → orcpin_day_trade_count
• "Which of yesterday's sale proceeds have settled?" → orcpin_settlement_dates

You don't touch HTTP or payment. Per call: the agent invokes the tool → the server hits Orcpin unpaid → gets a 402 with the price → signs a gasless USDC authorization with your wallet → the facilitator settles on Base → the server returns the block-anchored JSON. Typically ~2–4 seconds.

To confirm it's working after setup, ask the agent to "list your orcpin tools" or run any snapshot on a known address — a returned JSON snapshot means payment + delivery work.

Config

Env	Default	Notes
ORCPIN_PRIVATE_KEY	—	Funded buyer wallet (0x + 64 hex). Required — every tool here is a paid call. Orcpin's free x402 resource directory is a plain HTTP GET and needs no wallet: https://orcpin.dev/v1/x402/discovery/resources?q=search
ORCPIN_URL	https://orcpin.dev	Override for testing.
X402_NETWORK	eip155:8453	Base mainnet.
ORCPIN_TOOLSETS	all	Comma-separated subset: defi (chain + reliability tools) and/or trading (trade-log calculators).

Without ORCPIN_PRIVATE_KEY the server still starts (payments disabled (no key)); paid tools return a clear "funding required" message instead of hanging.

Security

• Your private key stays local — it is read from env and used only to sign x402 payment authorizations to orcpin.dev. It is never logged or transmitted anywhere else.
• Fund a dedicated, low-balance wallet for this; don't use a primary wallet. Rotate it if the config is ever shared.
• Orcpin reads only public on-chain data and never stores the addresses you query (see https://orcpin.dev/privacy).
• The trading calculators are stateless: the lots/trades in a request are computed on and never stored or logged. Formulas and conventions are published at https://orcpin.dev/methodology.