# Orcpin

> Agent-native x402 API on Base: factual, block-anchored on-chain wallet and DeFi position snapshots with transparent derived metrics; pre-flight endpoint-reliability checks that vet any x402 endpoint before an agent pays it; deterministic trade-log calculators; and the books an agent wallet does not keep — a local meter (the orcpin-ledger package), a signed statement of account read independently from the chain, and a signed four-part audit of any x402 endpoint. Built for autonomous agents to pay per call in USDC over the x402 protocol.

Orcpin charges per request via x402 (USDC on Base): pennies per endpoint call, ledger documents by the piece (a statement is priced by the window it covers; a door report is one price). Every response is a block-anchored fact or transparent arithmetic whose formula is published at /methodology; ledger documents are ed25519-signed and hash-logged. No accounts, no API keys — agents pay per call. Custom consulting is available on request.

## Paid endpoints
- [/v1/wallet-snapshot](https://orcpin.dev/v1/wallet-snapshot) ($0.02 USDC): On-chain wallet snapshot on Base: native ETH and tracked ERC-20 token balances (USDC, WETH) plus account flags (contract status, transaction count) and derived metrics (wallet type, activity tier, gas runway), anchored to a specific block. Factual wallet balance and holdings lookup for AI agents — portfolio and on-chain data API.
- [/v1/defi-snapshot](https://orcpin.dev/v1/defi-snapshot) ($0.05 USDC): DeFi position and wallet risk snapshot on Base: token balances, account flags, and live Aave v3 collateral, debt, borrowing power, and health factor read directly from the protocol at a specific block, plus derived risk metrics — net equity, LTV utilization, leverage multiplier, health-factor band, and collateral drawdown tolerance (how far collateral can fall before liquidation). For agents assessing portfolio exposure and liquidation risk.
- [/v1/batch-snapshot](https://orcpin.dev/v1/batch-snapshot) ($0.16 USDC): Batch wallet snapshots for multiple Base addresses in one paid call, all anchored to a single block: native and ERC-20 balances, account flags, and derived metrics per address. Efficient multi-wallet portfolio and balances lookup for AI agents. Billed per address, with volume discounts at 10+/50+/100+ addresses.
- [/v1/endpoint-reliability](https://orcpin.dev/v1/endpoint-reliability) ($0.01 USDC): x402 endpoint reliability pre-flight: factual service-delivery measurements of a target x402 endpoint before an agent pays it — reachability/uptime rate, valid-402 rate, response latency (p50/p95/p99), last status, and sampled paid delivery verification. Facts only (no trust score, no 'scam' label). Check whether an endpoint is live and delivers before spending on it.
- [/v1/endpoint-reliability/batch](https://orcpin.dev/v1/endpoint-reliability/batch) ($0.08 USDC): Batch x402 endpoint reliability: factual delivery measurements (uptime, valid-402 rate, latency, last status) for an agent's whole tool list of x402 endpoints in one paid call. Endpoints with no stored history are probed live, so every billed URL returns real facts. Sweep every endpoint you depend on before relying on them. Billed per endpoint, with volume discounts at 10+/50+/100+ URLs. Facts only — not an endorsement or rating.
- [/v1/holding-period](https://orcpin.dev/v1/holding-period) ($0.02 USDC, POST + JSON body): Trade-lot holding-period and realized-gain calculator for trading agents: per-lot days held, the exact date each lot's gain character turns long-term, and FIFO / specific-identification allocation of a proposed sell with realized gain per lot and per-character totals. Deterministic arithmetic on caller-supplied lots with the published threshold cited (IRC §1222: held more than one year) — counts, dates, and dollars only, never advice. Nothing is stored.
- [/v1/settlement-dates](https://orcpin.dev/v1/settlement-dates) ($0.02 USDC, POST + JSON body): T+1 settlement-date calculator for trading agents: the settlement date for each caller-supplied equity trade and whether it has settled as of a given date, on the versioned NYSE holiday calendar, with SEC Rule 15c6-1 cited as a published rule. Dates and counts only, never a violation determination. Nothing is stored.
- [/v1/settlement-date](https://orcpin.dev/v1/settlement-date) ($0.02 USDC): Single-trade T+1 settlement date, as a one-line GET: given a trade date and an as-of date, returns the settlement date and whether it has settled, on the versioned NYSE holiday calendar with SEC Rule 15c6-1 cited. The low-integration sibling of the batch settlement-dates route — no request body. A dates fact, never a violation determination. Nothing is stored.
- [/v1/wash-sale-status](https://orcpin.dev/v1/wash-sale-status) ($0.05 USDC, POST + JSON body): Wash-sale preflight for trading agents: evaluates a proposed buy against the operator's realized-loss sales across ALL accounts (caller-supplied) for the 61-day IRC §1091 window — would_trigger with the matched loss sales, an honest clear, or insufficient_data naming the gap. Tax status with the rule cited, never advisability; a disallowed loss defers, not forfeits. Exact-ticker v1; nothing stored. Agent account silos can't see the cross-account window — this check can.
- [/v1/statement](https://orcpin.dev/v1/statement) ($5 USDC, POST + JSON body): Signed statement of account for an agent wallet: every outgoing USDC settlement in a window, read independently from the public Base chain, totalled by counterparty and by day, block-anchored and ed25519-signed so anyone can verify it without Orcpin. Optionally attests the requester's own meter figures as reported, by digest, kept apart from the verified chain facts. The books a wallet does not keep. Counts and amounts only, never advice; nothing stored.
- [/v1/door-report](https://orcpin.dev/v1/door-report) ($50 USDC, POST + JSON body): Signed four-part audit of one x402 endpoint, by buying from it: the quote (what the 402 asks, and whether the seller's manifest and public catalog agree), real purchases with Orcpin's audit wallet (quoted vs signed vs settled vs chain vs delivered; replay and bad-payment behaviour), the door's inbound books from the chain (settlements, revenue, distinct and repeat payers), and unit cost against priced doors listed. Ed25519-signed and logged; facts, no verdict. No purchase settled, no charge.

## Discovery
- [x402 resource directory](https://orcpin.dev/v1/x402/discovery/resources): FREE searchable index of ~1,000 public x402 endpoints, ordered by 30-day unique payers. Filter with `?q=`, `?network=`, `?max_price=`. The upstream CDP Bazaar catalog supports neither text search nor lookup-by-URL; this does.
- [x402 Index (JSON)](https://orcpin.dev/x402-index.json): FREE capability-grouped catalog of live x402 services — search, commerce, prediction markets, market data, and more — ranked by real 30-day usage (single-use/wash listings demoted). One object per category with a deep-link back into the search endpoint. Human page at https://orcpin.dev/x402-index.
- [Service catalog](https://orcpin.dev/catalog): machine-readable endpoint list, pricing, and x402 flow
- [OpenAPI spec](https://orcpin.dev/openapi.json): full request/response schema
- [x402 resources](https://orcpin.dev/.well-known/x402): x402 discovery manifest (CDP Bazaar / x402scan compatible)
- [Agent manifest](https://orcpin.dev/.well-known/agent.json): open-402 agent.json capability manifest
- [MCP manifest](https://orcpin.dev/.well-known/mcp.json): FREE. The MCP registry server.json for `orcpin-mcp`: the package to install, its version, and the environment variables it reads. There is no hosted MCP endpoint. The server runs where you run it, and it pays with your wallet key, not ours.
- [Methodology](https://orcpin.dev/methodology): exact formula, inputs, and edge cases for every derived metric
- [Signing keys](https://orcpin.dev/.well-known/orcpin-signing-keys.json): FREE. Every key that has ever signed a /v1/statement or /v1/door-report, with status (active / retired / revoked) and dates. Check a document's signature.kid here before trusting it.
- [Statement reader](https://orcpin.dev/statement): FREE. Renders a signed statement of account as a readable report and verifies it in the browser (signature, key status, log entry); nothing is uploaded. POST /v1/statement with `Accept: text/html` returns this page with the document embedded.
- [Door Report reader](https://orcpin.dev/door-report): FREE. Renders a signed door report and verifies it in the browser (signature, key status, log entry); nothing is uploaded. POST /v1/door-report with `Accept: text/html` returns this page with the document embedded.
- [Transparency log](https://orcpin.dev/v1/statement/log): FREE. Hash-chained record of every signed document issued (payload hash, key id, time — nothing identifying). Look one up at /v1/statement/log/{payload_sha256}; a hash that is not here is a forgery.

## Research
- [Monthly Snapshot](https://orcpin.dev/research): "The Agent Economy: Purchasing vs. Watching" — a monthly measured overview of the agent-payments ecosystem: every rail where agents transact, a full survey of the listed x402 paid-endpoint universe with usage per listing, and the split between purchasers, evaluators, and crawler traffic. Counts and cited sources, never advice. Live aggregates at https://orcpin.dev/research.json.

## How to pay
- Header: send the signed payment envelope as `PAYMENT-SIGNATURE`, base64(JSON), on a retry of the same request. The x402 v1 name `X-PAYMENT` is honoured too.
- Envelope + signing domain: request ANY paid route with no payment. The 402 body carries a `how_to_pay` object with the exact envelope template, the EIP-712 domain for the EIP-3009 `TransferWithAuthorization`, and the price in both atomic and human units.
- Prices above are rounded labels. The binding figure is the atomic `amount` in the 402 challenge (USDC has 6 decimals, so `"10000"` = $0.01).
- A malformed `X-PAYMENT` returns 400 naming the problem, not another 402, so an integration can be validated before any money moves.
- No sandbox: these are live mainnet prices (`unpaid_dev_mode: false`). There is no free trial mode.

## Integration
- Library: `npm i orcpin-ledger` — `createClient()` calls every endpoint by name, pays via x402 with `ORCPIN_PRIVATE_KEY`, and meters every paid call locally (quote, signature, settlement receipt, response); `buyStatement()` carries the meter's figures into a signed statement and verifies it on return. Hand it your own fetch and it meters any x402 door.
- CLI: `npx orcpin-ledger endpoints | call <endpoint> --param value | report | statement --since --until | verify <file>` — JSON to stdout, key from env only; `verify` needs no key.
- MCP server: `npx -y orcpin-mcp` — drop into Claude Desktop, Cursor, or any agent runtime. Exposes eleven tools — ten paid (payment handled for you, including `orcpin_statement` and `orcpin_door_report`) plus a FREE x402 resource directory that works with no wallet configured. Config env: `ORCPIN_PRIVATE_KEY` (funded Base wallet).
- Raw x402: wrap fetch with `@x402/fetch` + `@x402/evm` (v2+) so 402s are paid and retried automatically (gasless USDC). See the /catalog integration samples.
- Client compatibility: use the SCOPED `@x402/*` packages. The unscoped `x402-fetch` / `x402` packages (1.2.0, last published 2026-04-16) predate CAIP-2 network ids and reject this API's challenge with a schema error before signing.

## Legal
- [Terms](https://orcpin.dev/terms)
- [Privacy](https://orcpin.dev/privacy): queried addresses are never stored; only aggregate, non-personal traffic counters