{"schema_version":"1.1.0","service":"Orcpin","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.","base_url":"https://orcpin.dev","payment":{"protocol":"x402","version":2,"currency":"USDC","network":"eip155:8453","testnet":false,"unpaid_dev_mode":false},"disclaimer":"Responses are informational snapshots of public Base on-chain data, served directly from chain. Not financial advice. Lawful use only; no reselling, redistribution, or implied endorsement. See /terms.","methodology":{"url":"https://orcpin.dev/methodology","description":"Exact formulas for every metric in data.derived. Free to fetch — audit the math before paying."},"endpoints":[{"name":"health","method":"GET","path":"/health","payment_required":false},{"name":"service_catalog","method":"GET","path":"/catalog","payment_required":false},{"name":"x402_directory","method":"GET","path":"/v1/x402/discovery/resources","payment_required":false,"description":"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"}}],"example":"https://orcpin.dev/v1/x402/discovery/resources?q=search&network=base&max_price=0.01"},{"name":"landing","method":"GET","path":"/","payment_required":false,"description":"Human-readable marketing page at orcpin.com (orcpin.dev redirects / to /catalog)."},{"name":"terms","method":"GET","path":"/terms","payment_required":false},{"name":"wallet_snapshot","method":"GET","path":"/v1/wallet-snapshot","payment_required":true,"description":"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.","x402":{"scheme":"exact","price":"$0.02","network":"eip155:8453","pay_to":"0x8B1CF12e7efe6AEA59cD1124eBbe7709E3Ac6085"},"parameters":[{"name":"address","in":"query","required":true,"description":"EVM wallet address to snapshot (0x...).","schema":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"}}],"response":{"schema_version":"1.1.0","as_of":"block","fields":["address","block_number","data.account.is_contract","data.account.transaction_count","data.native_balance","data.token_balances","data.derived.wallet_type","data.derived.activity_tier","data.derived.gas_runway","sources","disclaimer"],"derived_methodology":"https://orcpin.dev/methodology"},"example":"https://orcpin.dev/v1/wallet-snapshot?address=0x0000000000000000000000000000000000000001"},{"name":"defi_snapshot","method":"GET","path":"/v1/defi-snapshot","payment_required":true,"description":"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.","x402":{"scheme":"exact","price":"$0.05","network":"eip155:8453","pay_to":"0x8B1CF12e7efe6AEA59cD1124eBbe7709E3Ac6085"},"parameters":[{"name":"address","in":"query","required":true,"description":"EVM wallet address to snapshot (0x...).","schema":{"type":"string","pattern":"^0x[a-fA-F0-9]{40}$"}}],"response":{"schema_version":"1.1.0","as_of":"block","fields":["address","block_number","data.account","data.native_balance","data.token_balances","data.derived.wallet_type","data.derived.activity_tier","data.derived.gas_runway","data.aave_v3.total_collateral","data.aave_v3.total_debt","data.aave_v3.available_borrows","data.aave_v3.loan_to_value_bps","data.aave_v3.current_liquidation_threshold_bps","data.aave_v3.health_factor","data.aave_v3.no_outstanding_debt","data.derived.aave.net_equity","data.derived.aave.unused_borrow_power","data.derived.aave.ltv_utilization_pct","data.derived.aave.leverage_multiplier","data.derived.aave.health_factor_band","data.derived.aave.collateral_drawdown_tolerance_pct","sources","disclaimer"],"derived_methodology":"https://orcpin.dev/methodology"},"example":"https://orcpin.dev/v1/defi-snapshot?address=0x0000000000000000000000000000000000000001"},{"name":"batch_snapshot","method":"GET","path":"/v1/batch-snapshot","payment_required":true,"description":"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. Up to 1000 addresses per call; one bad address returns a per-item error without failing the batch. Per-address rate $0.02, discounted 20% at 10+, 30% at 50+, 40% at 100+; the 402 advertises the exact total for the count sent ($0.16 is the 10-address starting price).","x402":{"scheme":"exact","price":"$0.16","network":"eip155:8453","pay_to":"0x8B1CF12e7efe6AEA59cD1124eBbe7709E3Ac6085"},"limits":{"max_addresses":1000},"parameters":[{"name":"addresses","in":"query","required":true,"description":"Comma-separated EVM addresses (0x...), max per batch config.","schema":{"type":"string"}}],"response":{"schema_version":"1.1.0","as_of":"block","fields":["block_number","count","results[].address","results[].data","results[].error","sources","disclaimer"]},"example":"https://orcpin.dev/v1/batch-snapshot?addresses=0x0000000000000000000000000000000000000001,0x0000000000000000000000000000000000000002"},{"name":"endpoint_reliability","method":"GET","path":"/v1/endpoint-reliability","payment_required":true,"description":"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.","x402":{"scheme":"exact","price":"$0.01","network":"eip155:8453","pay_to":"0x8B1CF12e7efe6AEA59cD1124eBbe7709E3Ac6085"},"parameters":[{"name":"url","in":"query","required":true,"description":"Target x402 endpoint URL to read reliability facts for.","schema":{"type":"string","format":"uri"}}],"response":{"schema_version":"0.1.0","as_of":"rolling_probes","fields":["url","status","sample_size","first_seen","last_verified","facts.reachable_rate","facts.http_success_rate","facts.valid_402_rate","facts.latency_ms","facts.last_status","facts.consecutive_failures","facts.delivery_verified","flags","methodology","disclaimer"],"derived_methodology":"https://orcpin.dev/methodology#endpoint_reliability"},"example":"https://orcpin.dev/v1/endpoint-reliability?url=https://example.com/v1/some-resource"},{"name":"endpoint_reliability_batch","method":"GET","path":"/v1/endpoint-reliability/batch","payment_required":true,"description":"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. Up to 150 URLs per call; any endpoint we hold no measurement for is probed live so every billed URL returns real facts. Per-endpoint rate $0.01, discounted 20% at 10+, 30% at 50+, 40% at 100+; the 402 advertises the exact total for the count sent ($0.08 is the 10-endpoint starting price).","x402":{"scheme":"exact","price":"$0.08","network":"eip155:8453","pay_to":"0x8B1CF12e7efe6AEA59cD1124eBbe7709E3Ac6085"},"limits":{"max_urls":150},"parameters":[{"name":"urls","in":"query","required":true,"description":"Comma-separated x402 endpoint URLs, max per batch config.","schema":{"type":"string"}}],"response":{"schema_version":"0.1.0","as_of":"rolling_probes","fields":["count","results[].url","results[].status","results[].sample_size","results[].facts","results[].flags","methodology","disclaimer"]},"example":"https://orcpin.dev/v1/endpoint-reliability/batch?urls=https://example.com/v1/a,https://example.org/v1/b"},{"name":"holding_period","method":"POST","path":"/v1/holding-period","payment_required":true,"description":"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. Up to 500 lots per call. Request body is computed on and never stored.","x402":{"scheme":"exact","price":"$0.02","network":"eip155:8453","pay_to":"0x8B1CF12e7efe6AEA59cD1124eBbe7709E3Ac6085"},"limits":{"max_lots":500},"request_body":{"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"]},"response":{"schema_version":"lotmath-v1","as_of":"caller-supplied asOf date","fields":["as_of","lots[].daysHeld","lots[].longTermFrom","lots[].character","lots[].daysUntilLongTerm","sell.method","sell.allocations[].quantity","sell.allocations[].daysHeld","sell.allocations[].character","sell.allocations[].costBasis","sell.allocations[].proceeds","sell.allocations[].realizedGain","sell.totals","explanation","methodology","disclaimer"],"derived_methodology":"https://orcpin.dev/methodology#trade_log"},"example":"POST https://orcpin.dev/v1/holding-period with JSON body {\"asOf\":\"2026-07-02\",\"lots\":[{\"symbol\":\"XYZ\",\"acquireDate\":\"2025-01-10\",\"quantity\":100,\"costBasis\":500}],\"sell\":{\"symbol\":\"XYZ\",\"tradeDate\":\"2026-07-02\",\"quantity\":100,\"price\":12}}"},{"name":"day_trade_count","method":"POST","path":"/v1/day-trade-count","payment_required":true,"description":"Day-trade counter for trading agents: matched same-day buy/sell pairs per symbol in the rolling five-trading-day window (versioned NYSE holiday calendar), total in-window trades, and the ratio — with FINRA's pattern-day-trader definition (Rule 4210) cited separately as a published fact. Counts only, never a status determination; the comparison belongs to the caller. Nothing is stored. Up to 1000 trades per call. Request body is counted and never stored.","x402":{"scheme":"exact","price":"$0.02","network":"eip155:8453","pay_to":"0x8B1CF12e7efe6AEA59cD1124eBbe7709E3Ac6085"},"limits":{"max_trades":1000},"request_body":{"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"]},"response":{"schema_version":"daytrade-v1","as_of":"caller-supplied asOf date","fields":["window.tradingDays","window.calendarVersion","day_trade_count","total_trades_in_window","day_trade_ratio","day_trades[].symbol","day_trades[].pairs","coverage","threshold_citation","explanation","methodology","disclaimer"],"derived_methodology":"https://orcpin.dev/methodology#trade_log"},"example":"POST https://orcpin.dev/v1/day-trade-count with JSON body {\"asOf\":\"2026-07-06\",\"trades\":[{\"symbol\":\"XYZ\",\"side\":\"buy\",\"tradeDate\":\"2026-07-01\"},{\"symbol\":\"XYZ\",\"side\":\"sell\",\"tradeDate\":\"2026-07-01\"}]}"},{"name":"settlement_dates","method":"POST","path":"/v1/settlement-dates","payment_required":true,"description":"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. Up to 1000 trades per call. Request body is computed on and never stored.","x402":{"scheme":"exact","price":"$0.02","network":"eip155:8453","pay_to":"0x8B1CF12e7efe6AEA59cD1124eBbe7709E3Ac6085"},"limits":{"max_trades":1000},"request_body":{"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"]},"response":{"schema_version":"settlement-v1","as_of":"caller-supplied asOf date","fields":["calendar_version","trades[].settlementDate","trades[].settledAsOf","trades[].tradingDaysUntilSettlement","settled_count","unsettled_count","rule_citation","explanation","methodology","disclaimer"],"derived_methodology":"https://orcpin.dev/methodology#trade_log"},"example":"POST https://orcpin.dev/v1/settlement-dates with JSON body {\"asOf\":\"2026-07-02\",\"trades\":[{\"symbol\":\"XYZ\",\"side\":\"sell\",\"tradeDate\":\"2026-07-02\"}]}"},{"name":"settlement_date","method":"GET","path":"/v1/settlement-date","payment_required":true,"description":"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.","x402":{"scheme":"exact","price":"$0.02","network":"eip155:8453","pay_to":"0x8B1CF12e7efe6AEA59cD1124eBbe7709E3Ac6085"},"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"}}],"response":{"schema_version":"settlement-v1","as_of":"caller-supplied as_of date","fields":["trade_date","settlement_date","settled","trading_days_until_settlement","calendar_version","rule_citation","explanation","methodology","disclaimer"],"derived_methodology":"https://orcpin.dev/methodology#trade_log"},"example":"https://orcpin.dev/v1/settlement-date?trade_date=2026-07-02&as_of=2026-07-02"}],"agent_integration":{"caller_library":"@x402/fetch","flow":["GET endpoint without payment header","Receive HTTP 402 with x402 payment requirements","Sign and send USDC payment on configured network","Retry GET with x402 payment header","Receive JSON snapshot"],"test_script":"npm run test:agent","samples":{"mcp":{"description":"Drop-in MCP server — native tools for Claude Desktop, Cursor, and agent runtimes. Handles x402 payment for you. orcpin_x402_directory is free and works with no wallet configured, so the server is useful before it is funded.","package":"orcpin-mcp","config":{"mcpServers":{"orcpin":{"command":"npx","args":["-y","orcpin-mcp"],"env":{"ORCPIN_PRIVATE_KEY":"0xYOUR_FUNDED_BASE_WALLET_KEY","X402_NETWORK":"eip155:8453"}}}},"tools":["orcpin_x402_directory","orcpin_wallet_snapshot","orcpin_defi_snapshot","orcpin_batch_snapshot","orcpin_endpoint_reliability","orcpin_endpoint_reliability_batch","orcpin_holding_period","orcpin_day_trade_count","orcpin_settlement_dates"],"toolsets":"Optional ORCPIN_TOOLSETS env (\"defi\", \"trading\", comma-separated) exposes a subset of the PAID tools; default is all. orcpin_x402_directory is free and always exposed."},"raw_x402_fetch":{"description":"Raw client: wrap fetch so 402s are paid and retried automatically (gasless USDC, no ETH needed).","install":"npm i @x402/fetch @x402/evm viem","code":"import { wrapFetchWithPaymentFromConfig } from \"@x402/fetch\";\nimport { ExactEvmScheme } from \"@x402/evm\";\nimport { privateKeyToAccount } from \"viem/accounts\";\n\nconst account = privateKeyToAccount(process.env.EVM_PRIVATE_KEY);\nconst fetchWithPay = wrapFetchWithPaymentFromConfig(fetch, {\n  schemes: [{ network: \"eip155:8453\", client: new ExactEvmScheme(account) }],\n});\n\nconst res = await fetchWithPay(\"https://orcpin.dev/v1/wallet-snapshot?address=0xYourTarget\");\nconst snapshot = await res.json();"},"vercel_ai_sdk_tool":{"description":"Expose Orcpin as a Vercel AI SDK tool. Reuses fetchWithPay from the raw sample above.","install":"npm i ai zod @x402/fetch @x402/evm viem","code":"import { tool } from \"ai\";\nimport { z } from \"zod\";\n// fetchWithPay: see raw_x402_fetch sample\n\nexport const orcpinWalletSnapshot = tool({\n  description: \"Block-anchored wallet snapshot on Base: balances + derived metrics.\",\n  parameters: z.object({\n    address: z.string().describe(\"0x EVM address to snapshot\"),\n  }),\n  execute: async ({ address }) => {\n    const res = await fetchWithPay(`https://orcpin.dev/v1/wallet-snapshot?address=${address}`);\n    return await res.json();\n  },\n});"},"reliability_preflight":{"description":"Pre-flight an x402 endpoint before paying it: fetch reliability facts (uptime, valid-402 rate, latency) and let your own policy decide. Facts only — apply your own thresholds. Reuses fetchWithPay from the raw sample above.","code":"// fetchWithPay: see raw_x402_fetch sample\nconst target = \"https://some-endpoint.example/v1/resource\";\nconst res = await fetchWithPay(`https://orcpin.dev/v1/endpoint-reliability?url=${encodeURIComponent(target)}`);\nconst { facts, sample_size, flags } = await res.json();\n// Your policy, your call — e.g. require evidence before trusting it:\nconst trustworthy =\n  sample_size >= 20 &&\n  (facts.http_success_rate ?? 0) >= 0.95 &&\n  !flags.includes(\"consecutive_failures\");"}}},"discovery":{"bazaar":true,"service":{"serviceName":"Orcpin","tags":["wallet","defi","base","snapshot","aave","portfolio","risk","health-factor","balances","erc20","onchain","usdc","x402","reliability","uptime","endpoint-monitoring"],"iconUrl":"https://orcpin.com/orcpin-logo.png"},"facilitator":"https://api.cdp.coinbase.com/platform/v2/x402","cdp_bazaar":{"resources":"https://api.cdp.coinbase.com/platform/v2/x402/discovery/resources","search":"https://api.cdp.coinbase.com/platform/v2/x402/discovery/search","merchant":"https://api.cdp.coinbase.com/platform/v2/x402/discovery/merchant","lookup_by":"payTo","note":"Indexed after the first successful CDP settlement per route. For reliable lookup, GET search or merchant with ?payTo=<pay_to from any paid endpoint x402 block>. Semantic text search (?q=...) may lag for new listings."}}}