{"service":"Orcpin","resource":"methodology","schema_version":"1.1.0","last_updated":"2026-09-16","summary":"Method for every number Orcpin publishes: the exact formula, inputs and edge cases for each metric group — derived snapshot metrics, endpoint-reliability probe aggregates, and trade-log arithmetic. Each group is addressable by anchor.","sections":[{"group":"wallet","title":"Wallet-level metrics","anchor":"https://orcpin.dev/methodology#wallet","applies_to":["/v1/wallet-snapshot","/v1/defi-snapshot","/v1/batch-snapshot"]},{"group":"aave","title":"Aave v3 metrics","anchor":"https://orcpin.dev/methodology#aave","applies_to":["/v1/defi-snapshot"]},{"group":"endpoint_reliability","title":"x402 endpoint reliability","anchor":"https://orcpin.dev/methodology#endpoint_reliability","applies_to":["/v1/endpoint-reliability","/v1/endpoint-reliability/batch"]},{"group":"trade_log","title":"Trade-log calculators","anchor":"https://orcpin.dev/methodology#trade_log","applies_to":["/v1/holding-period","/v1/settlement-dates","/v1/settlement-date","/v1/wash-sale-status"]},{"group":"statement","title":"Signed statement of account","anchor":"https://orcpin.dev/methodology#statement","applies_to":["/v1/statement"]},{"group":"door_report","title":"Door report","anchor":"https://orcpin.dev/methodology#door_report","applies_to":["/v1/door-report"]}],"principles":["No outside inputs. Every derived value is computed only from fields already in the same block-anchored response (balances, nonce, gas price, and Aave's own reported figures). Nothing is fetched from a price oracle, model, or third party.","Facts, not opinions. Bands and tiers are deterministic thresholds on the raw numbers — not ratings, predictions, or advice.","Reproducible. Each formula below uses only published response fields, so any caller can recompute every number themselves."],"metrics":[{"group":"wallet","title":"Wallet-level metrics","applies_to":["/v1/wallet-snapshot","/v1/defi-snapshot","/v1/batch-snapshot"],"intro":"Present in every snapshot under data.derived. Computed from account flags, the native balance, and the current gas price at the anchored block.","fields":[{"field":"wallet_type","label":"Wallet type","formula":"is_contract ? \"contract\" : \"eoa\"","inputs":["data.account.is_contract"],"unit":"enum: \"eoa\" | \"contract\"","notes":"Based on whether the address has bytecode at the anchored block."},{"field":"activity_tier","label":"Activity tier","formula":"0 → \"new\"; 1–9 → \"low\"; 10–99 → \"active\"; ≥100 → \"power\"","inputs":["data.account.transaction_count"],"unit":"enum: \"new\" | \"low\" | \"active\" | \"power\"","notes":"Buckets on the outbound nonce only. A coarse activity heuristic — not an age, identity, or reputation score."},{"field":"gas_runway.gas_price_wei","label":"Gas price (wei)","formula":"eth_gasPrice at request time","inputs":["RPC gas price"],"unit":"wei (string)","notes":"The whole gas_runway object is null if the gas-price read fails."},{"field":"gas_runway.assumed_gas_units","label":"Assumed gas units","formula":"constant 21000","inputs":[],"unit":"gas units","notes":"Gas for a simple native ETH transfer. Contract calls cost more, so this is a best-case upper bound."},{"field":"gas_runway.est_tx_cost_wei","label":"Estimated tx cost (wei)","formula":"gas_price_wei × 21000","inputs":["gas_runway.gas_price_wei","gas_runway.assumed_gas_units"],"unit":"wei (string)","notes":"Cost of one simple transfer at the current gas price."},{"field":"gas_runway.simple_transfers_affordable","label":"Simple transfers affordable","formula":"floor(native_balance.wei ÷ est_tx_cost_wei)","inputs":["data.native_balance.wei","gas_runway.est_tx_cost_wei"],"unit":"integer count","notes":"How many simple transfers the ETH balance could pay for at the current gas price. Gas price varies block to block, so treat as an estimate."}]},{"group":"aave","title":"Aave v3 metrics","applies_to":["/v1/defi-snapshot"],"intro":"Present under data.derived.aave only when the address has an Aave v3 position (aave_v3.available && aave_v3.has_position); otherwise data.derived.aave is null. USD figures use Aave's base currency (8 decimals). Below, C = total_collateral, D = total_debt, HF = health_factor.","fields":[{"field":"net_equity","label":"Net equity","formula":"C − D","inputs":["aave_v3.total_collateral","aave_v3.total_debt"],"unit":"USD (8 decimals)","notes":"Position value net of debt."},{"field":"unused_borrow_power","label":"Unused borrow power","formula":"available_borrows (pass-through)","inputs":["aave_v3.available_borrows"],"unit":"USD (8 decimals)","notes":"The value Aave reports as still borrowable."},{"field":"ltv_utilization_pct","label":"LTV utilization","formula":"D == 0 → 0; else (D ÷ C) ÷ (loan_to_value_bps ÷ 10000) × 100","inputs":["aave_v3.total_debt","aave_v3.total_collateral","aave_v3.loan_to_value_bps"],"unit":"percent (1 dp)","null_when":"C = 0 or loan_to_value_bps = 0","notes":"Percent of the maximum borrow allowed by LTV that is currently used."},{"field":"leverage_multiplier","label":"Leverage multiplier","formula":"C ÷ (C − D)","inputs":["aave_v3.total_collateral","aave_v3.total_debt"],"unit":"ratio (2 dp)","null_when":"equity (C − D) ≤ 0","notes":"Equity multiplier of the position."},{"field":"health_factor_band","label":"Health factor band","formula":"no debt → \"no_debt\"; HF ≥ 2 → \"safe\"; 1.5 ≤ HF < 2 → \"moderate\"; 1.1 ≤ HF < 1.5 → \"elevated\"; HF < 1.1 → \"critical\"","inputs":["aave_v3.health_factor","aave_v3.no_outstanding_debt"],"unit":"enum: \"no_debt\" | \"safe\" | \"moderate\" | \"elevated\" | \"critical\"","notes":"Fixed thresholds on Aave's reported health factor. A label, not a recommendation."},{"field":"collateral_drawdown_tolerance_pct","label":"Collateral drawdown tolerance","formula":"(1 − 1 ÷ HF) × 100","inputs":["aave_v3.health_factor"],"unit":"percent (1 dp)","null_when":"no outstanding debt","notes":"Percent the collateral value can fall before HF reaches 1 (Aave's liquidation point). Derived from Aave's own definition HF = (collateral × liquidation_threshold) ÷ debt: holding debt and the threshold constant, HF scales linearly with collateral value, so collateral can drop by (1 − 1/HF) before HF = 1. Assumes a uniform collateral price move with debt and threshold constant; it is a point-in-time estimate, not a prediction or advice."}]},{"group":"endpoint_reliability","title":"x402 endpoint reliability","applies_to":["/v1/endpoint-reliability","/v1/endpoint-reliability/batch"],"intro":"Unlike the snapshot metrics above, these facts are NOT computed from a single response — they aggregate Orcpin's own independent probe history for a target x402 endpoint over a rolling ~60-day window. Each probe is an unpaid request with no body (which returns the endpoint's 402 challenge at zero cost, before the endpoint does any work). We probe with GET first; if the endpoint answers with a status that indicates the wrong verb rather than a fault (404, 405, 501) we retry once with POST and record only that result — a large share of x402 endpoints are POST-only, and counting our own wrong verb against them would understate their reliability. A small, opt-in sample of probes additionally make a real PAID call to verify delivery. The subject is software delivery (did it respond, was the 402 well-formed, how fast) — NOT the financial quality or accuracy of any data the endpoint returns. Every value is a raw measured rate or count: there is no composite 'trust score' and no 'scam'/'safe' label. The caller applies its own thresholds. Below, P = total probes recorded.\n\nCoverage. Two things populate the measurement history. A scheduled sweep continuously re-probes a worklist drawn from the public CDP Bazaar catalog and ordered by real demand (unique payers over the last 30 days), so the endpoints agents actually pay for hold the deepest samples. Anything else is probed on demand: ask about an endpoint we hold no measurement for — through either the single or the batch route — and it is probed live before the response is built, then kept for subsequent callers. A first-ever lookup therefore returns a one-sample measurement carrying the 'low_sample' flag, never a blank. We make no claim to have pre-measured the whole catalog, and 'unmeasured' means exactly what it says: no probe history and no live probe reached it.","fields":[{"field":"reachable_rate","label":"Reachable rate","formula":"probes that returned any HTTP response ÷ P","inputs":["probe history"],"unit":"ratio 0–1 (3 dp), null when P = 0","notes":"A probe is 'reachable' if it got an HTTP response at all (no timeout or transport error). Says nothing about the status code."},{"field":"http_success_rate","label":"HTTP success rate","formula":"probes whose status was 2xx OR a well-formed 402 ÷ P","inputs":["probe history"],"unit":"ratio 0–1 (3 dp), null when P = 0","notes":"For an x402 endpoint a 402 is correct behaviour (it is demanding payment), so it counts as success. Measures whether the endpoint responded as expected — not whether returned data is correct."},{"field":"valid_402_rate","label":"Valid 402 rate","formula":"probes whose 402 body was a well-formed x402 challenge ÷ P","inputs":["probe history"],"unit":"ratio 0–1 (3 dp), null when P = 0","notes":"A 402 is 'valid' when its body parses as an x402 challenge (has an `accepts` array or an `x402Version`). Distinguishes a real paywalled endpoint from a generic 402."},{"field":"latency_ms.p50 / p95 / p99","label":"Latency percentiles","formula":"percentiles over a fixed 7-bucket histogram with edges 100/250/500/1000/2500/5000 ms; the reported value is the upper edge of the bucket the percentile falls into","inputs":["probe history"],"unit":"milliseconds (bucketed estimate), null when no timed probes","notes":"Bucketed, so these are estimates, not exact percentiles — the response marks basis:'histogram'. Round-trip wall-clock time of the probe request."},{"field":"last_status","label":"Last status","formula":"HTTP status code of the most recent probe","inputs":["probe history"],"unit":"HTTP status integer, null when unknown","notes":"402 is normal and healthy for a paid endpoint."},{"field":"consecutive_failures","label":"Consecutive failures","formula":"count of probes since the last success; reset to 0 on any success","inputs":["probe history"],"unit":"integer count"},{"field":"delivery_verified","label":"Delivery verification","formula":"verified = (paid probes that returned a parseable response > 0); samples = paid probes attempted","inputs":["sampled paid probe history"],"unit":"object { verified, at, samples }, null when no paid probe has run","notes":"Present only when sampled PAID verification has been run for the endpoint (off by default). It is the only fact whose measurement involved spending. Confirms the endpoint actually returns a response after payment; it does not judge the returned data."},{"field":"flags","label":"Factual flags","formula":"\"unmeasured\" when P = 0; \"unprobeable_url\" when the URL can't be safely probed; \"low_sample\" when 0 < P < 5; \"unreachable\" when 0 of ≥5 probes got any response; \"consecutive_failures\" when consecutive_failures ≥ 3; \"last_probe_error\" when last_status ≥ 500; \"stale_measurement\" when the last probe is older than 7 days; \"delivery_failed\" when every paid delivery attempt failed","inputs":["probe history"],"unit":"array of enumerated string markers (may be empty)","notes":"Enumerated factual markers, each with a fixed mechanical trigger above. Condition flags (unreachable / consecutive_failures / last_probe_error) are suppressed below 5 probes — a single transient bad sweep never flags an endpoint; \"low_sample\" is emitted instead and the raw rates still report what was seen. Never adjectives like 'scam' or 'unsafe', and never a recommendation — the caller decides what they mean for its use."}]},{"group":"trade_log","title":"Trade-log calculators","applies_to":["/v1/holding-period","/v1/settlement-dates","/v1/settlement-date","/v1/wash-sale-status"],"intro":"Unlike the chain metrics above, these are computed ONLY from the trade data the caller supplies in the request (a JSON body, or query params for the single-trade /v1/settlement-date GET) — nothing is fetched, and nothing is stored. Pure calendar arithmetic (UTC days) with the statutory threshold cited as a published fact; the response never states a verdict about the caller. All conventions below are deterministic: same inputs, same output, no server clock. Trading-day math (T+1 settlement) uses a versioned, published NYSE holiday table echoed as calendarVersion in each response; dates outside its range are a 400, never a guess.","fields":[{"field":"lots[].daysHeld","label":"Days held","formula":"asOf − acquireDate, in whole UTC calendar days","inputs":["body.asOf","body.lots[].acquireDate"],"unit":"integer days","notes":"The holding period begins the day AFTER acquisition (IRS Pub 550), so the acquisition day itself counts 0."},{"field":"lots[].longTermFrom","label":"Long-term from","formula":"acquireDate + 1 year + 1 day (UTC calendar)","inputs":["body.lots[].acquireDate"],"unit":"date (YYYY-MM-DD)","notes":"First date on which a sale is long-term under IRC §1222 (held MORE than one year): a sale exactly on the one-year anniversary is short-term. Feb 29 acquisitions roll the anniversary to Mar 1 (the later, conservative boundary)."},{"field":"lots[].character / sell.allocations[].character","label":"Gain character","formula":"(evaluation date ≥ longTermFrom) ? \"long_term\" : \"short_term\"","inputs":["lots[].longTermFrom","body.asOf or body.sell.tradeDate"],"unit":"enum: \"short_term\" | \"long_term\"","notes":"A definitional label from the cited threshold — not a recommendation about whether or when to sell."},{"field":"sell.allocations[]","label":"Sell allocation","formula":"method \"fifo\": consume matching-symbol lots oldest acquireDate first; method \"as_supplied\": consume in the caller's array order (specific identification). The last lot consumed may be split.","inputs":["body.sell","body.lots[]"],"unit":"array of per-lot allocations","notes":"Selling more shares than the supplied lots hold is a 400 error, never a partial answer."},{"field":"sell.allocations[].realizedGain","label":"Realized gain per allocation","formula":"proceeds − allocated basis, where proceeds = quantity × sell.price and allocated basis = lot.costBasis × (quantity ÷ lot.quantity); both rounded to cents","inputs":["body.sell.price","body.lots[].costBasis"],"unit":"USD (2 dp)","null_when":"the lot has no costBasis, or the sell has no price","notes":"Cost basis is used exactly as supplied — wash-sale basis adjustments, corporate actions, and splits are not applied."},{"field":"sell.totals","label":"Per-character totals","formula":"sum of allocation quantities and realizedGain per character (short_term / long_term)","inputs":["sell.allocations[]"],"unit":"object per character","null_when":"realizedGain is null when ANY allocation in that character bucket lacks basis or price — a partial sum would misstate the total"},{"field":"trades[].settlementDate (settlement-dates)","label":"Settlement date","formula":"the next NYSE trading day strictly after tradeDate (T+1), per the versioned holiday table","inputs":["body.trades[].tradeDate","published NYSE holiday table (calendarVersion)"],"unit":"date (YYYY-MM-DD)","notes":"SEC Rule 15c6-1 (as amended, effective 2024-05-28) is cited separately in rule_citation. Assumes standard US equity settlement; other instruments can differ."},{"field":"trades[].settledAsOf","label":"Settled as of","formula":"asOf ≥ settlementDate","inputs":["body.asOf","trades[].settlementDate"],"unit":"boolean","notes":"Settlement completes on the settlement date itself. A dates fact — never a violation determination."},{"field":"matches[].daysFromOrder (wash-sale-status)","label":"Days from order","formula":"saleDate − order.tradeDate, signed UTC calendar days; a sale matches when |daysFromOrder| ≤ 30 and the ticker is identical","inputs":["body.order.tradeDate","body.recentSales[].tradeDate","body.recentSales[].symbol"],"unit":"signed integer days","notes":"IRC §1091's 61-day window (±30 days, boundary-inclusive) is cited separately in rule_citation. v1 matches exact tickers only; substantially identical securities are out of scope and the disclaimer says so. Sales with zero/absent realizedLoss are ignored by construction."},{"field":"status (wash-sale-status)","label":"Wash-sale status","formula":"matches.length > 0 ? \"would_trigger\" : coverage.complete === true ? \"clear\" : \"insufficient_data\"; sell orders return \"not_applicable\"","inputs":["matches","coverage.complete","body.order.side"],"unit":"enum","notes":"coverage.complete = salesCoverageFrom ≤ order.tradeDate − 30 days; undeclared coverage is null and an empty sales list then reads insufficient_data, never a false clear. A tax STATUS with the rule cited — never advisability; a disallowed loss defers into replacement basis rather than being forfeited."}]},{"group":"statement","title":"Signed statement of account","applies_to":["/v1/statement"],"intro":"The statement is structured like an auditor's letter. `verified` holds facts Orcpin read itself: every outgoing USDC transfer from the wallet in the window, from the public Base explorer, at the block shown. `representations` holds figures the requester's own meter reported, attested AS REPORTED by digest and never verified — Orcpin cannot see the requester's HTTP responses and does not pretend to. `reconciliation` is the arithmetic between the two. The whole document is canonicalised (keys sorted at every level, no whitespace), ed25519-signed, and its hash appended to a public transparency log; verification needs nothing from Orcpin but the published key.","fields":[{"field":"verified.settlements","label":"Settlements","formula":"count of outgoing USDC transfers from the wallet in the window with value > 0","inputs":["explorer token-transfers, filter=from"],"unit":"count"},{"field":"verified.usd","label":"Spent","formula":"sum of those transfers' values ÷ 10^6","inputs":["same"],"unit":"USD (6 dp)"},{"field":"verified.zero_value_transfers","label":"Zero-value transfers","formula":"count of outgoing transfers with value = 0","inputs":["same"],"unit":"count","notes":"Moved no money and are not settlements. Kept apart because a run of them to an address that looks like one you pay is the address-poisoning pattern."},{"field":"verified.by_counterparty[].flags","label":"Address flags","formula":"lookalike_of:<addr> when the first and last four hex characters match a payee this wallet actually paid; zero_value_only when every transfer to it was zero-value","inputs":["the statement's own rows"],"unit":"list","notes":"A pattern is named; no verdict is given about any party."},{"field":"verified.by_counterparty[].resources[].matches_settlement_amounts","label":"Price match","formula":"true when this wallet paid the payee an amount equal to the resource's catalog price","inputs":["CDP Bazaar merchant lookup by payee"],"unit":"boolean","notes":"A likely attribution, not a proof of which call was made."},{"field":"reconciliation.unaccounted_usd","label":"Unaccounted","formula":"max(0, verified.usd − representations.delivered_usd)","inputs":["chain total","requester's reported delivered total"],"unit":"USD","null_when":"no representations were supplied"},{"field":"signature.payload_sha256","label":"Payload hash","formula":"sha256 of the canonical JSON of everything except signature, signed and transparency","inputs":["the document"],"unit":"hex","notes":"The value logged in the transparency log; a hash that is not there under the signing key's kid is a forgery."}]},{"group":"door_report","title":"Door report","applies_to":["/v1/door-report"],"intro":"Four parts, in the order a buyer meets them. Quote: one unpaid request to the door records its status, latency and 402 challenge, and the same door is looked up on every surface that advertises it — the seller's own /.well-known/x402 manifest, the CDP Bazaar merchant listing for the payee, and Orcpin's weekly crawl — to see whether each names the same price and payee. Purchase: N real purchases with Orcpin's separately funded audit wallet, each recorded as quoted (the 402 the wallet saw), signed (the EIP-3009 authorization it sent), settled (the facilitator's payment-response), chain (that transaction's USDC Transfer read from the node), and delivered (a 2xx with valid JSON); then the first purchase's exact payment header is sent again, and a well-formed header that is not a payment is sent, and the door's answers are recorded. Books: every incoming USDC transfer to the payee over the last 30 days, from the public explorer, aggregated to counts and amounts — payer addresses are held in memory for the call and never returned. Cost: what a delivered response cost in this audit, and the share of USDC-priced doors in the public catalog priced below and above this one. Every figure is a raw count, amount, share or status; `attention` names patterns and the reader draws the conclusion. Nothing is charged for a URL that does not present a valid 402 on the audit's network.","fields":[{"field":"quote.price_consistent","label":"Price consistency","formula":"every surface that lists the door agrees with the 402's amount to the atomic unit","inputs":["402 challenge","seller manifest","CDP Bazaar","Orcpin index"],"unit":"boolean","notes":"A surface that does not list the door neither agrees nor disagrees."},{"field":"purchase.records[].outcome","label":"Purchase outcome","formula":"delivered = settled and 2xx with valid JSON; paid_not_delivered = settled without that; settlement_failed = the facilitator reported failure; delivered_without_payment = content came back with no retry; no_response = nothing usable came back","inputs":["the paid call's two requests"],"unit":"enum"},{"field":"purchase.records[].chain.matches_signed","label":"Receipt confirmed","formula":"the settlement transaction's USDC Transfer is from the audit wallet, to the quoted payee, for the signed amount","inputs":["transaction receipt from the node"],"unit":"boolean","null_when":"no receipt could be read"},{"field":"purchase.replay.delivered","label":"Replay delivered","formula":"the first purchase's exact payment header, sent again, produced a 2xx with valid JSON","inputs":["one extra unpaid request"],"unit":"boolean","notes":"An EIP-3009 nonce is single-use on chain; a second delivery is one the seller was not paid for."},{"field":"books.repeat_payers","label":"Repeat payers","formula":"distinct payers with settlements on two or more distinct UTC days in the window","inputs":["explorer token-transfers, filter=to"],"unit":"count"},{"field":"books.single_settlement_payers_at_this_price","label":"One-shot buyers at list price","formula":"distinct payers with exactly one settlement in the window, equal to the door's quoted price","inputs":["same","the 402 amount"],"unit":"count","notes":"Consistent with verifiers and probes; stated as a count, not a classification of anyone."},{"field":"books.top_payer_share","label":"Top payer share","formula":"settlements by the single most frequent payer ÷ settlements","inputs":["same"],"unit":"ratio 0–1","null_when":"no settlements"},{"field":"cost.this_audit.usd_per_delivered_response","label":"Cost per delivered response","formula":"USD settled in this audit ÷ purchases that were delivered","inputs":["purchase records"],"unit":"USD","null_when":"nothing was delivered"},{"field":"cost.catalog.share_priced_below","label":"Catalog share below","formula":"USDC-priced doors on this network in Orcpin's catalog crawl priced strictly below this door ÷ all such doors","inputs":["weekly catalog crawl"],"unit":"ratio 0–1","null_when":"the crawl is empty"}]}],"disclaimer":"Derived metrics are transparent arithmetic on the same on-chain values already in each response — not financial, legal, or investment advice, and not predictions. Read-only and factual. See /terms for acceptable use.","links":{"human_page":"https://orcpin.com/methodology","catalog":"https://orcpin.dev/catalog","terms":"https://orcpin.dev/terms"}}