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), all paid transparently via x402. Drop it into Claude Desktop, Cursor, or any MCP-compatible agent runtime and your agent gets eight tools:

| Tool | What it returns | Price | |---|---|---| | 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). 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 and funded, the agent sees the tools and calls them on its own when relevant. You just ask in natural language:

• "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 is a paid call. | | 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.