{"uid":"cap_T_ohXvo5RwHFVadozwTyO","slug":"acoda-observed-liquidation-map-3676ca1c","name":"ACODA Observed Liquidation Map","description":"Measured liquidation intelligence combining observed CEX liquidation events with position-level data from Hyperliquid, the largest transparent perp venue. A pay-per-call JSON API for AI trading agents.","url":"https://acoda.xyz/v1/observed-map","method":"GET","headers":{},"bodySchema":{"type":"object","$schema":"https://json-schema.org/draft/2020-12/schema","required":["input"],"properties":{"input":{"type":"object","required":["type","method"],"properties":{"type":{"type":"string","const":"http"},"method":{"enum":["GET"],"type":"string"},"queryParams":{"type":"object","required":[],"properties":{"market":{"enum":["BTC-USDT-PERP","ETH-USDT-PERP","SOL-USDT-PERP"],"type":"string","description":"Perp market (canonical BASE-QUOTE-PERP)"},"range_pct":{"type":"string","description":"Half-range around mark in percent (default 15)"},"price_buckets":{"type":"string","description":"Price buckets (default 40)"}}}},"additionalProperties":false},"output":{"type":"object","required":["type"],"properties":{"type":{"type":"string"},"example":{"type":"object"}}}}},"responseSchema":{"type":"json","example":{"paid":true,"basis":"exchange-reported liquidationPx of open positions","cells":[{"intensity":1,"price_low":62243.79,"price_high":62878.93,"position_count":27,"long_notional_usd":4712345.1,"short_notional_usd":0}],"market":"BTC-USDT-PERP","source":"observed","coverage":{"note":"Sampled lower bound; coverage disclosed.","complete":false},"mark_price":63490.11,"price_axis":{"max":73013.62,"min":53966.59,"buckets":40,"bucket_width":476.18}}},"example":null,"exampleRequest":null,"tags":["x402"],"displayCostAmount":"0.1","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"priced","priceSource":"probe","requiresHandshake":false,"reviewCount":0,"rating":{"score":"0.00","successRate":"0.00","reviews":0,"stars":null,"state":"unrated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"static","summary":"$0.1/call","primary":{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.1","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.1","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_8TDc8vfgVWRBpjPTL5qFE","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.1","costPer":"request","priority":0,"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","unit":"request","depositMicros":null,"planRef":null}],"brandName":null,"brandSlug":null,"brandBaseUrl":null,"brandDocsUrl":null,"whatItDoes":"Returns a price-bucketed heatmap of observed liquidation exposure across long and short positions for a given perpetual futures market on Hyperliquid","exampleAgentPrompt":"Pull me the liquidation heatmap for BTC-USDT-PERP on Hyperliquid with a 10% price range and 40 buckets so I can see where the long and short exposure clusters are sitting right now.","exampleUseCases":[{"title":"Pre-trade liquidation cascade check","prompt":"Before I enter this BTC long, show me the ACODA liquidation map for BTC-USDT-PERP within 15% of mark price — I want to see if there's a cluster of longs just below that could cascade into a flush if price drops."},{"title":"Short squeeze zone detection for ETH","prompt":"Show me the liquidation heatmap for ETH-USDT-PERP with a 20% range and 40 buckets — I'm looking for price levels where short notional is stacked up and a squeeze could accelerate a move upward."},{"title":"SOL perp risk dashboard for trading agent","prompt":"My agent needs a live snapshot of liquidation exposure for SOL-USDT-PERP — pull the observed map with default range and bucket settings so it can flag any dangerous leverage concentrations near current price."}],"resultDescription":"A JSON object containing an array of price bucket cells, each with a price range (low/high), long and short notional USD at risk, position count, and a normalized liquidation intensity score. Also includes the current mark price, full price axis metadata (min, max, bucket count, bucket width), the market queried, a coverage note indicating this is a sampled lower bound from observed data, and a source field confirming 'observed' methodology.","failureModes":["Unsupported market symbol returns validation error — only BTC-USDT-PERP, ETH-USDT-PERP, SOL-USDT-PERP are valid","Missing or malformed query parameters may return default behavior or a 400 error","Coverage is explicitly a sampled lower bound — incomplete data is expected by design and flagged in the response","Payment not processed (402) if x402 payment header is missing or USDC balance is insufficient","Data may lag real-time conditions slightly due to on-chain data indexing latency","Hyperliquid data unavailability could result in empty or stale position data"],"whenToPreferThis":"Choose this endpoint when an AI trading agent needs structured, price-bucketed liquidation exposure data for major crypto perpetual markets — specifically BTC, ETH, or SOL on Hyperliquid. It is uniquely valuable when you need to identify where forced liquidations are likely to cluster at specific price levels, combining both CEX-observed liquidation events and on-chain position data. Prefer this over generic order book or funding rate APIs when the specific goal is cascade risk analysis, liquidation-driven momentum anticipation, or pre-trade leverage concentration screening.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-09-14T18:39:12.373Z","isFirstParty":false}