{"openapi":"3.1.0","info":{"title":"PerpFinder Public Data API","version":"1.0.0","description":"Free, keyless, CORS-open crypto-derivatives data: perp volume, open interest, funding rates, options/IV, volume quality, fees. Missing values are null, never 0. Attribution requested: \"Data: PerpFinder\" linking to perpfinder.com. Rate limits: 30–60 req/min per IP depending on endpoint.","termsOfService":"https://perpfinder.com/terms","contact":{"url":"https://perpfinder.com/docs/api"},"license":{"name":"PerpFinder data-use terms","url":"https://perpfinder.com/terms"}},"servers":[{"url":"https://perpfinder.com"}],"externalDocs":{"description":"PerpFinder API documentation","url":"https://perpfinder.com/docs/api"},"x-ai-discovery":{"llms":"https://perpfinder.com/llms.txt","fullCatalogue":"https://perpfinder.com/llms-full.txt","manifest":"https://perpfinder.com/api-manifest","definitions":"https://perpfinder.com/data-definitions"},"paths":{"/api/data/perps":{"get":{"operationId":"getApiDataPerps","summary":"Perp DEX volume overview (24h/7d/30d, change %, per protocol).","description":"Stable public dataset. Key response fields: protocols[], dataStatus, generatedAt, upstreamTimestamp, schemaVersion, sources, ETag","responses":{"200":{"description":"JSON. Key fields: protocols[], dataStatus, generatedAt, upstreamTimestamp, schemaVersion, sources, ETag. Missing values are null, never 0.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or unsupported query parameter."},"429":{"description":"Rate limited — respect Retry-After."},"503":{"description":"No trustworthy fresh or stale upstream data was available."}}}},"/api/data/slippage":{"get":{"operationId":"getApiDataSlippage","summary":"Live perp execution-cost ladder from order books and supported oracle/pool models. Total cost is fee + half-spread + size-dependent impact beyond the best quote.","description":"Stable public dataset. Key response fields: asset, sizeUsd, side, results[].{exchange,feeBps,feeBpsMin,feeBpsMax,feeModel,slippageBps,halfSpreadBps,spreadBps,totalBps,midPrice,vwap,sufficient,quoteStatus,maxExecutableSizeUsd}, coverage, dataStatus, generatedAt, schemaVersion, sources, ETag","parameters":[{"name":"asset","in":"query","required":false,"schema":{"type":"string","example":"BTC"},"description":"Example: BTC"},{"name":"size","in":"query","required":false,"schema":{"type":"integer","minimum":1,"example":100000},"description":"Example: 100000"},{"name":"feeType","in":"query","required":false,"schema":{"type":"string","enum":["taker","maker"],"example":"taker"},"description":"Example: taker|maker"},{"name":"side","in":"query","required":false,"schema":{"type":"string","enum":["buy","sell"],"example":"buy"},"description":"Example: buy|sell"}],"responses":{"200":{"description":"JSON. Key fields: asset, sizeUsd, side, results[].{exchange,feeBps,feeBpsMin,feeBpsMax,feeModel,slippageBps,halfSpreadBps,spreadBps,totalBps,midPrice,vwap,sufficient,quoteStatus,maxExecutableSizeUsd}, coverage, dataStatus, generatedAt, schemaVersion, sources, ETag. Missing values are null, never 0.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or unsupported query parameter."},"429":{"description":"Rate limited — respect Retry-After."},"503":{"description":"No trustworthy fresh or stale upstream data was available."}}}},"/api/data/slippage-spot":{"get":{"operationId":"getApiDataSlippageSpot","summary":"Live spot execution-cost ladder using venue order books, pair-specific fees, spread, VWAP impact and explicit depth coverage.","description":"Stable public dataset. Key response fields: asset, sizeUsd, side, results[].{exchange,baseAsset,quoteAsset,feeBps,slippageBps,halfSpreadBps,spreadBps,totalBps,midPrice,vwap,sufficient}, coverage, dataStatus, generatedAt, schemaVersion, sources, ETag","parameters":[{"name":"asset","in":"query","required":false,"schema":{"type":"string","example":"BTC"},"description":"Example: BTC"},{"name":"size","in":"query","required":false,"schema":{"type":"integer","minimum":1,"example":10000},"description":"Example: 10000"},{"name":"feeType","in":"query","required":false,"schema":{"type":"string","enum":["taker","maker"],"example":"taker"},"description":"Example: taker|maker"},{"name":"side","in":"query","required":false,"schema":{"type":"string","enum":["buy","sell"],"example":"buy"},"description":"Example: buy|sell"}],"responses":{"200":{"description":"JSON. Key fields: asset, sizeUsd, side, results[].{exchange,baseAsset,quoteAsset,feeBps,slippageBps,halfSpreadBps,spreadBps,totalBps,midPrice,vwap,sufficient}, coverage, dataStatus, generatedAt, schemaVersion, sources, ETag. Missing values are null, never 0.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or unsupported query parameter."},"429":{"description":"Rate limited — respect Retry-After."},"503":{"description":"No trustworthy fresh or stale upstream data was available."}}}},"/api/data/dex-enrichment":{"get":{"operationId":"getApiDataDexEnrichment","summary":"Direct DEX market enrichment: OI, volume, funding, prices, protocol stats and venue coverage.","description":"Stable public dataset. Key response fields: protocols[], crossVenueFunding, coverage, dataStatus, generatedAt, upstreamTimestamp, schemaVersion, sources, ETag","responses":{"200":{"description":"JSON. Key fields: protocols[], crossVenueFunding, coverage, dataStatus, generatedAt, upstreamTimestamp, schemaVersion, sources, ETag. Missing values are null, never 0.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or unsupported query parameter."},"429":{"description":"Rate limited — respect Retry-After."},"503":{"description":"No trustworthy fresh or stale upstream data was available."}}}},"/api/data/perps-chart":{"get":{"operationId":"getApiDataPerpsChart","summary":"Aggregate daily perp-volume time series + total open interest per day (own snapshots).","description":"Stable public dataset. Key response fields: chart[{date,volume,oi}]","parameters":[{"name":"days","in":"query","required":false,"schema":{"type":"integer","minimum":1,"example":90},"description":"Example: 90"}],"responses":{"200":{"description":"JSON. Key fields: chart[{date,volume,oi}]. Missing values are null, never 0.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or unsupported query parameter."},"429":{"description":"Rate limited — respect Retry-After."},"503":{"description":"No trustworthy fresh or stale upstream data was available."}}}},"/api/data/volume":{"get":{"operationId":"getApiDataVolume","summary":"CEX 24h volume per venue from direct venue-reported futures tickers + top symbols.","description":"Stable public dataset. Key response fields: exchanges[], venueSlugs, updatedAt, dataStatus, generatedAt, upstreamTimestamp, schemaVersion, sources, ETag","responses":{"200":{"description":"JSON. Key fields: exchanges[], venueSlugs, updatedAt, dataStatus, generatedAt, upstreamTimestamp, schemaVersion, sources, ETag. Missing values are null, never 0.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or unsupported query parameter."},"429":{"description":"Rate limited — respect Retry-After."},"503":{"description":"No trustworthy fresh or stale upstream data was available."}}}},"/api/data/open-interest":{"get":{"operationId":"getApiDataOpenInterest","summary":"Open interest per exchange (CEX+DEX) + aggregate total.","description":"Stable public dataset. Key response fields: byExchange[], venueSlugs, updatedAt","responses":{"200":{"description":"JSON. Key fields: byExchange[], venueSlugs, updatedAt. Missing values are null, never 0.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or unsupported query parameter."},"429":{"description":"Rate limited — respect Retry-After."},"503":{"description":"No trustworthy fresh or stale upstream data was available."}}}},"/api/data/oi-long-short":{"get":{"operationId":"getApiDataOiLongShort","summary":"DEX long vs short open-interest split per protocol.","description":"Stable public dataset. Key response fields: rows[], updatedAt","responses":{"200":{"description":"JSON. Key fields: rows[], updatedAt. Missing values are null, never 0.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or unsupported query parameter."},"429":{"description":"Rate limited — respect Retry-After."},"503":{"description":"No trustworthy fresh or stale upstream data was available."}}}},"/api/data/funding-rates":{"get":{"operationId":"getApiDataFundingRates","summary":"Live funding-rate matrix: asset × exchange (normalized 1h). Missing OI/price are null with per-venue field support and explicit feed coverage.","description":"Stable public dataset. Key response fields: rows[], exchanges[], coverage, updatedAt, meta.fieldSupport, meta.venueSlugs, dataStatus, generatedAt, upstreamTimestamp, schemaVersion, sources, ETag","responses":{"200":{"description":"JSON. Key fields: rows[], exchanges[], coverage, updatedAt, meta.fieldSupport, meta.venueSlugs, dataStatus, generatedAt, upstreamTimestamp, schemaVersion, sources, ETag. Missing values are null, never 0.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or unsupported query parameter."},"429":{"description":"Rate limited — respect Retry-After."},"503":{"description":"No trustworthy fresh or stale upstream data was available."}}}},"/api/data/fees":{"get":{"operationId":"getApiDataFees","summary":"Protocol fees (DEX, 24h/7d/30d per protocol).","description":"Stable public dataset. Key response fields: protocols[], dataStatus, generatedAt, upstreamTimestamp, schemaVersion, sources, ETag","responses":{"200":{"description":"JSON. Key fields: protocols[], dataStatus, generatedAt, upstreamTimestamp, schemaVersion, sources, ETag. Missing values are null, never 0.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or unsupported query parameter."},"429":{"description":"Rate limited — respect Retry-After."},"503":{"description":"No trustworthy fresh or stale upstream data was available."}}}},"/api/data/liquidations":{"get":{"operationId":"getApiDataLiquidations","summary":"Liquidations 24h/4h/1h, long vs short split.","description":"Stable public dataset. Key response fields: rows[], updatedAt","responses":{"200":{"description":"JSON. Key fields: rows[], updatedAt. Missing values are null, never 0.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or unsupported query parameter."},"429":{"description":"Rate limited — respect Retry-After."},"503":{"description":"No trustworthy fresh or stale upstream data was available."}}}},"/api/data/options":{"get":{"operationId":"getApiDataOptions","summary":"BTC/ETH options market state: mark IV per strike/expiry, ATM term structure, put/call, Deribit DVOL (attributed), expiries.","description":"Stable public dataset. Key response fields: assets.{BTC,ETH}, dvol, termStructure[], expiries[], status, updatedAt","responses":{"200":{"description":"JSON. Key fields: assets.{BTC,ETH}, dvol, termStructure[], expiries[], status, updatedAt. Missing values are null, never 0.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or unsupported query parameter."},"429":{"description":"Rate limited — respect Retry-After."},"503":{"description":"No trustworthy fresh or stale upstream data was available."}}}},"/api/data/options-history":{"get":{"operationId":"getApiDataOptionsHistory","summary":"Self-collected options time series (no synthetic backfill); allowlisted metrics; maturity + methodologyVersion in every response.","description":"Stable public dataset. Key response fields: series[], maturity, methodologyVersion, firstObservedAt, dataStatus, ETag","parameters":[{"name":"asset","in":"query","required":false,"schema":{"type":"string","example":"BTC"},"description":"Example: BTC"},{"name":"metric","in":"query","required":false,"schema":{"type":"string","example":"dvol"},"description":"Example: dvol"},{"name":"interval","in":"query","required":false,"schema":{"type":"string","enum":["15m","1d"],"example":"15m"},"description":"Example: 15m|1d"},{"name":"days","in":"query","required":false,"schema":{"type":"string","example":"N"},"description":"Example: N"}],"responses":{"200":{"description":"JSON. Key fields: series[], maturity, methodologyVersion, firstObservedAt, dataStatus, ETag. Missing values are null, never 0.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or unsupported query parameter."},"429":{"description":"Rate limited — respect Retry-After."},"503":{"description":"No trustworthy fresh or stale upstream data was available."}}}},"/api/data/volume-quality":{"get":{"operationId":"getApiDataVolumeQuality","summary":"Reported vs observable CEX volume signals with separate data-confidence scoring.","description":"Stable public dataset. Key response fields: sweep.venues[], maturity, methodologyVersion, datasetStart, dataStatus","responses":{"200":{"description":"JSON. Key fields: sweep.venues[], maturity, methodologyVersion, datasetStart, dataStatus. Missing values are null, never 0.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or unsupported query parameter."},"429":{"description":"Rate limited — respect Retry-After."},"503":{"description":"No trustworthy fresh or stale upstream data was available."}}}},"/api/data/rwa-markets":{"get":{"operationId":"getApiDataRwaMarkets","summary":"RWA perp markets: stocks / forex / commodities across venues.","description":"Stable public dataset. Key response fields: markets[], updatedAt","responses":{"200":{"description":"JSON. Key fields: markets[], updatedAt. Missing values are null, never 0.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or unsupported query parameter."},"429":{"description":"Rate limited — respect Retry-After."},"503":{"description":"No trustworthy fresh or stale upstream data was available."}}}},"/api/data/mica":{"get":{"operationId":"getApiDataMica","summary":"Committed ESMA MiCA register snapshot joined to PerpFinder venue status, service permissions, EU-derivatives scope and fee context.","description":"Stable public dataset. Key response fields: register, scope, coverage, authorized[], tracked[], dataStatus, generatedAt, upstreamTimestamp, schemaVersion, sources, ETag","responses":{"200":{"description":"JSON. Key fields: register, scope, coverage, authorized[], tracked[], dataStatus, generatedAt, upstreamTimestamp, schemaVersion, sources, ETag. Missing values are null, never 0.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or unsupported query parameter."},"429":{"description":"Rate limited — respect Retry-After."},"503":{"description":"No trustworthy fresh or stale upstream data was available."}}}},"/api/data/premium":{"get":{"operationId":"getApiDataPremium","summary":"Perp premium / basis vs spot per venue.","description":"Stable public dataset. Key response fields: rows[], updatedAt","responses":{"200":{"description":"JSON. Key fields: rows[], updatedAt. Missing values are null, never 0.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or unsupported query parameter."},"429":{"description":"Rate limited — respect Retry-After."},"503":{"description":"No trustworthy fresh or stale upstream data was available."}}}},"/api/data/fear-greed":{"get":{"operationId":"getApiDataFearGreed","summary":"Fear & Greed index (alternative.me, attributed).","description":"Stable public dataset. Key response fields: value, updatedAt","responses":{"200":{"description":"JSON. Key fields: value, updatedAt. Missing values are null, never 0.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or unsupported query parameter."},"429":{"description":"Rate limited — respect Retry-After."},"503":{"description":"No trustworthy fresh or stale upstream data was available."}}}},"/api/data/funding-history":{"get":{"operationId":"getApiDataFundingHistory","summary":"Self-collected funding history: aggregates, per-venue sweeps, or the append-only realized-settlement ledger. Rate types never mixed; no synthetic backfill.","description":"Stable public dataset. Key response fields: series[]/entries[], coverage, maturity, methodologyVersion, datasetStart, dataStatus, generatedAt, schemaVersion, sources, ETag","parameters":[{"name":"asset","in":"query","required":false,"schema":{"type":"string","example":"BTC"},"description":"Example: BTC"},{"name":"type","in":"query","required":false,"schema":{"type":"string","enum":["aggregates","venue","realized"],"example":"aggregates"},"description":"Example: aggregates|venue|realized"},{"name":"days","in":"query","required":false,"schema":{"type":"integer","minimum":1,"example":7},"description":"Example: 7"},{"name":"venue","in":"query","required":false,"schema":{"type":"string","example":"Binance"},"description":"Example: Binance"},{"name":"rateType","in":"query","required":false,"schema":{"type":"string","enum":["current","predicted"],"example":"current"},"description":"Example: current|predicted"},{"name":"format","in":"query","required":false,"schema":{"type":"string","example":"csv"},"description":"Example: csv"}],"responses":{"200":{"description":"JSON. Key fields: series[]/entries[], coverage, maturity, methodologyVersion, datasetStart, dataStatus, generatedAt, schemaVersion, sources, ETag. Missing values are null, never 0.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or unsupported query parameter."},"429":{"description":"Rate limited — respect Retry-After."},"503":{"description":"No trustworthy fresh or stale upstream data was available."}}}},"/api/data/volume-quality-history":{"get":{"operationId":"getApiDataVolumeQualityHistory","summary":"Volume-quality sweep history per venue (reported vs observable signals over time). Measurements, never accusations.","description":"Stable public dataset. Key response fields: series[], maturity, methodologyVersion, datasetStart, updatedAt","parameters":[{"name":"days","in":"query","required":false,"schema":{"type":"integer","minimum":1,"example":7},"description":"Example: 7"},{"name":"venue","in":"query","required":false,"schema":{"type":"string"}},{"name":"format","in":"query","required":false,"schema":{"type":"string","example":"csv"},"description":"Example: csv"}],"responses":{"200":{"description":"JSON. Key fields: series[], maturity, methodologyVersion, datasetStart, updatedAt. Missing values are null, never 0.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or unsupported query parameter."},"429":{"description":"Rate limited — respect Retry-After."},"503":{"description":"No trustworthy fresh or stale upstream data was available."}}}},"/api/data/venue-history":{"get":{"operationId":"getApiDataVenueHistory","summary":"Per-venue daily volume/OI history from the committed snapshot series (since 2026-06-05) — venue-reported figures, normalized; null never zero-filled.","description":"Stable public dataset. Key response fields: series[], venueSlug, datasetStart, updatedAt","parameters":[{"name":"venue","in":"query","required":false,"schema":{"type":"string","example":"Binance"},"description":"Example: Binance"},{"name":"days","in":"query","required":false,"schema":{"type":"integer","minimum":1,"example":30},"description":"Example: 30"},{"name":"format","in":"query","required":false,"schema":{"type":"string","example":"csv"},"description":"Example: csv"}],"responses":{"200":{"description":"JSON. Key fields: series[], venueSlug, datasetStart, updatedAt. Missing values are null, never 0.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or unsupported query parameter."},"429":{"description":"Rate limited — respect Retry-After."},"503":{"description":"No trustworthy fresh or stale upstream data was available."}}}},"/api/data/cost-history":{"get":{"operationId":"getApiDataCostHistory","summary":"Execution-cost ladder history (fee + spread + VWAP slippage per venue, 4×/day). Young series — maturity labeled honestly.","description":"Stable public dataset. Key response fields: series[], maturity, methodologyVersion, datasetStart, updatedAt","parameters":[{"name":"market","in":"query","required":false,"schema":{"type":"string","example":"perp"},"description":"Example: perp"},{"name":"asset","in":"query","required":false,"schema":{"type":"string","example":"BTC"},"description":"Example: BTC"},{"name":"size","in":"query","required":false,"schema":{"type":"integer","minimum":1,"example":100000},"description":"Example: 100000"},{"name":"days","in":"query","required":false,"schema":{"type":"integer","minimum":1,"example":7},"description":"Example: 7"},{"name":"format","in":"query","required":false,"schema":{"type":"string","example":"csv"},"description":"Example: csv"}],"responses":{"200":{"description":"JSON. Key fields: series[], maturity, methodologyVersion, datasetStart, updatedAt. Missing values are null, never 0.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid or unsupported query parameter."},"429":{"description":"Rate limited — respect Retry-After."},"503":{"description":"No trustworthy fresh or stale upstream data was available."}}}}}}