{"openapi":"3.1.0","info":{"title":"Orcpin","version":"1.1.0","description":"Agent-native x402 API: factual, block-anchored on-chain wallet and DeFi position snapshots on Base, plus x402 endpoint-reliability pre-flight checks (uptime, valid-402 rate, latency) so agents can verify an endpoint before paying it."},"externalDocs":{"description":"Derived metrics methodology — exact formulas for every data.derived field.","url":"https://orcpin.dev/methodology"},"servers":[{"url":"https://orcpin.dev"}],"paths":{"/health":{"get":{"summary":"Health check (verifies RPC reachability)","responses":{"200":{"description":"Service and RPC healthy"},"503":{"description":"RPC unreachable"}}}},"/v1/x402/discovery/resources":{"get":{"summary":"Free searchable directory of public x402 resources","description":"FREE — no x402 payment. FREE searchable index of public x402 resources listed on the CDP Bazaar, ordered by 30-day unique payers and re-crawled weekly. The upstream catalog has no text search and no lookup-by-URL; this one does. Filter with q (text), network, max_price (USD), and paginate with limit/offset. Each entry reports whether Orcpin holds reliability measurements for it — the measured facts themselves are the paid /v1/endpoint-reliability route.","parameters":[{"name":"q","in":"query","required":false,"description":"Case-insensitive text match over the resource URL, service name and description.","schema":{"type":"string"}},{"name":"network","in":"query","required":false,"description":"Exact network id as the Bazaar reports it (e.g. base, eip155:8453, solana). Matched exactly, not as a substring — base and eip155:8453 are distinct upstream ids.","schema":{"type":"string"}},{"name":"max_price","in":"query","required":false,"description":"Ceiling on the advertised price, in USD. Entries with no advertised price are excluded rather than assumed cheap.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size. Default 50, maximum 200.","schema":{"type":"integer"}},{"name":"offset","in":"query","required":false,"description":"Pagination offset into the filtered result set.","schema":{"type":"integer"}}],"responses":{"200":{"description":"Directory page (free)"},"429":{"description":"Rate limited"},"502":{"description":"Directory cache unavailable"}}}},"/v1/wallet-snapshot":{"get":{"summary":"Wallet snapshot at latest block","description":"Verifiable native + ERC-20 balances and account flags for the requested address, plus derived metrics (wallet type, activity tier, gas runway). Formulas: GET /methodology.","parameters":[{"name":"address","in":"query","required":true,"description":"EVM wallet address to snapshot (0x...).","schema":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"}}],"responses":{"200":{"description":"Block-anchored snapshot"},"400":{"description":"Invalid or missing address"},"402":{"description":"x402 payment required (when unpaid dev mode is off)"},"429":{"description":"Rate limited"},"502":{"description":"RPC provider error"}},"x-x402":{"scheme":"exact","price":"$0.02","network":"eip155:8453","pay_to":"0x8B1CF12e7efe6AEA59cD1124eBbe7709E3Ac6085"}}},"/v1/defi-snapshot":{"get":{"summary":"DeFi position snapshot at latest block","description":"Balances, account flags, and Aave v3 collateral/debt/health factor read directly from the protocol, plus derived risk metrics (net equity, LTV utilization, leverage, health-factor band, collateral drawdown tolerance). Formulas: GET /methodology.","parameters":[{"name":"address","in":"query","required":true,"description":"EVM wallet address to snapshot (0x...).","schema":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"}}],"responses":{"200":{"description":"Block-anchored snapshot"},"400":{"description":"Invalid or missing address"},"402":{"description":"x402 payment required (when unpaid dev mode is off)"},"429":{"description":"Rate limited"},"502":{"description":"RPC provider error"}},"x-x402":{"scheme":"exact","price":"$0.05","network":"eip155:8453","pay_to":"0x8B1CF12e7efe6AEA59cD1124eBbe7709E3Ac6085"}}},"/v1/batch-snapshot":{"get":{"summary":"Batch wallet snapshots at a single block","description":"Up to 1000 addresses in one paid call, anchored to one block.","parameters":[{"name":"addresses","in":"query","required":true,"description":"Comma-separated EVM addresses (0x...), max per batch config.","schema":{"type":"string"}}],"responses":{"200":{"description":"Block-anchored snapshot"},"400":{"description":"Invalid or missing address"},"402":{"description":"x402 payment required (when unpaid dev mode is off)"},"429":{"description":"Rate limited"},"502":{"description":"RPC provider error"}},"x-x402":{"scheme":"exact","price":"$0.16","network":"eip155:8453","pay_to":"0x8B1CF12e7efe6AEA59cD1124eBbe7709E3Ac6085"}}},"/v1/endpoint-reliability":{"get":{"summary":"Reliability facts for one x402 endpoint","description":"Factual service-delivery measurements (reachability/uptime rate, valid-402 rate, latency p50/p95/p99, last status, sampled paid delivery verification) for a target x402 endpoint. Facts only — not an endorsement, rating, or advice. On a cache miss the endpoint is probed live (unpaid) so the call always returns real facts.","parameters":[{"name":"url","in":"query","required":true,"description":"Target x402 endpoint URL to read reliability facts for.","schema":{"type":"string","format":"uri"}}],"responses":{"200":{"description":"Block-anchored snapshot"},"400":{"description":"Invalid or missing address"},"402":{"description":"x402 payment required (when unpaid dev mode is off)"},"429":{"description":"Rate limited"},"502":{"description":"RPC provider error"}},"x-x402":{"scheme":"exact","price":"$0.01","network":"eip155:8453","pay_to":"0x8B1CF12e7efe6AEA59cD1124eBbe7709E3Ac6085"}}},"/v1/endpoint-reliability/batch":{"get":{"summary":"Reliability facts for many x402 endpoints","description":"Reliability facts for up to 150 x402 endpoint URLs in one paid call. Sweep an agent's whole tool list before relying on it. Endpoints with no stored history are probed live, so every billed URL returns real facts.","parameters":[{"name":"urls","in":"query","required":true,"description":"Comma-separated x402 endpoint URLs, max per batch config.","schema":{"type":"string"}}],"responses":{"200":{"description":"Block-anchored snapshot"},"400":{"description":"Invalid or missing address"},"402":{"description":"x402 payment required (when unpaid dev mode is off)"},"429":{"description":"Rate limited"},"502":{"description":"RPC provider error"}},"x-x402":{"scheme":"exact","price":"$0.08","network":"eip155:8453","pay_to":"0x8B1CF12e7efe6AEA59cD1124eBbe7709E3Ac6085"}}},"/v1/holding-period":{"post":{"summary":"Trade-lot holding-period and realized-gain math","description":"Deterministic arithmetic on caller-supplied tax lots: per-lot days held, the date gain character turns long-term (IRC §1222 cited as a published fact), and FIFO / specific-identification allocation of a proposed sell with realized gain per lot. Counts, dates, and dollars only — never a verdict or advice. The request body is computed on and never stored. Formulas: GET /methodology#trade_log.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"asOf":{"type":"string","description":"Evaluation date, YYYY-MM-DD (UTC calendar days; no server clock is used)."},"lots":{"type":"array","description":"Tax lots to evaluate. costBasis (total USD for the lot) is optional — absent means gain math is omitted for that lot.","items":{"type":"object","properties":{"symbol":{"type":"string"},"acquireDate":{"type":"string","description":"YYYY-MM-DD"},"quantity":{"type":"number"},"costBasis":{"type":"number"},"account":{"type":"string"}},"required":["symbol","acquireDate","quantity"]}},"sell":{"type":"object","description":"Optional proposed sell to allocate across the lots (FIFO or as_supplied). price (per share USD) optional.","properties":{"symbol":{"type":"string"},"tradeDate":{"type":"string","description":"YYYY-MM-DD"},"quantity":{"type":"number"},"price":{"type":"number"},"method":{"type":"string","enum":["fifo","as_supplied"]}},"required":["symbol","tradeDate","quantity"]}},"required":["asOf","lots"]}}}},"responses":{"200":{"description":"Holding-period facts and optional sell allocation"},"400":{"description":"Invalid body (coarse category; values never recorded)"},"402":{"description":"x402 payment required (when unpaid dev mode is off)"},"429":{"description":"Rate limited"}},"x-x402":{"scheme":"exact","price":"$0.02","network":"eip155:8453","pay_to":"0x8B1CF12e7efe6AEA59cD1124eBbe7709E3Ac6085"}}},"/v1/day-trade-count":{"post":{"summary":"Same-day round-trip count in the rolling 5-trading-day window","description":"Counts matched same-day buy/sell pairs per symbol over caller-supplied trades, on the versioned NYSE calendar, with FINRA Rule 4210's pattern-day-trader definition cited separately. Counts only — the comparison belongs to the caller. Bodies are never stored. Formulas: GET /methodology#trade_log.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"asOf":{"type":"string","description":"Evaluation date, YYYY-MM-DD (anchors the 5-trading-day window)."},"trades":{"type":"array","description":"Trade executions to count over.","items":{"type":"object","properties":{"symbol":{"type":"string"},"side":{"type":"string","enum":["buy","sell"]},"tradeDate":{"type":"string","description":"YYYY-MM-DD"},"quantity":{"type":"number"},"account":{"type":"string"}},"required":["symbol","side","tradeDate"]}},"tradesCoverageFrom":{"type":"string","description":"Earliest date the supplied trades cover (YYYY-MM-DD); short coverage is flagged, never hidden."}},"required":["asOf","trades"]}}}},"responses":{"200":{"description":"Day-trade count, window, ratio, and citation"},"400":{"description":"Invalid body (coarse category; values never recorded)"},"402":{"description":"x402 payment required (when unpaid dev mode is off)"},"429":{"description":"Rate limited"}},"x-x402":{"scheme":"exact","price":"$0.02","network":"eip155:8453","pay_to":"0x8B1CF12e7efe6AEA59cD1124eBbe7709E3Ac6085"}}},"/v1/settlement-dates":{"post":{"summary":"T+1 settlement dates for supplied trades","description":"Settlement date per trade (next NYSE trading day, versioned calendar) and settled/unsettled status as of the supplied date, with SEC Rule 15c6-1 cited separately. Dates and counts only — never a violation determination. Bodies are never stored. Formulas: GET /methodology#trade_log.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"asOf":{"type":"string","description":"Date to evaluate settled/unsettled against, YYYY-MM-DD."},"trades":{"type":"array","items":{"type":"object","properties":{"symbol":{"type":"string"},"side":{"type":"string","enum":["buy","sell"]},"tradeDate":{"type":"string","description":"YYYY-MM-DD"},"amount":{"type":"number","description":"Optional USD amount, echoed back untouched."},"account":{"type":"string"}},"required":["symbol","side","tradeDate"]}}},"required":["asOf","trades"]}}}},"responses":{"200":{"description":"Per-trade settlement dates and settled counts"},"400":{"description":"Invalid body (coarse category; values never recorded)"},"402":{"description":"x402 payment required (when unpaid dev mode is off)"},"429":{"description":"Rate limited"}},"x-x402":{"scheme":"exact","price":"$0.02","network":"eip155:8453","pay_to":"0x8B1CF12e7efe6AEA59cD1124eBbe7709E3Ac6085"}}},"/v1/settlement-date":{"get":{"summary":"Single-trade T+1 settlement date (GET, no body)","description":"The low-integration sibling of /v1/settlement-dates: one trade, as query params. Given trade_date and as_of, returns the settlement date (next NYSE trading day on the versioned calendar) and whether it has settled, with SEC Rule 15c6-1 cited. A dates fact — never a violation determination. Nothing is stored. Formulas: GET /methodology#trade_log.","parameters":[{"name":"trade_date","in":"query","required":true,"description":"Execution date of the trade, YYYY-MM-DD.","schema":{"type":"string"}},{"name":"as_of","in":"query","required":true,"description":"Date to evaluate settled/unsettled against, YYYY-MM-DD.","schema":{"type":"string"}},{"name":"symbol","in":"query","required":false,"description":"Optional ticker, echoed back untouched.","schema":{"type":"string"}}],"responses":{"200":{"description":"Settlement date and settled status for the trade"},"400":{"description":"Missing or invalid trade_date / as_of (coarse category)"},"402":{"description":"x402 payment required (when unpaid dev mode is off)"},"429":{"description":"Rate limited"}},"x-x402":{"scheme":"exact","price":"$0.02","network":"eip155:8453","pay_to":"0x8B1CF12e7efe6AEA59cD1124eBbe7709E3Ac6085"}}}}}