{"openapi":"3.0.0","info":{"version":"0.0.1","title":"Cardano Data API","description":"Cardano on-chain data primitives as x402 pay-per-call services. Free tier: 20 requests / IP / endpoint / day."},"servers":[{"url":"http://localhost:3001","description":"local dev"}],"components":{"schemas":{},"parameters":{}},"paths":{"/cardano/dex/price":{"get":{"tags":["DEX"],"summary":"Aggregated DEX price for a Cardano token pair","description":"Returns the best price for `pair` across Minswap V2, WingRiders, and SundaeSwap. Slippage fields give the effective price when trading 1% / 5% of the chosen pool depth. Cost: 5 credits/call after free tier (20/IP/day).","parameters":[{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]+\\/[A-Za-z0-9_-]+$","description":"Asset pair, format: BASE/QUOTE","example":"ADA/USDM"},"required":true,"name":"pair","in":"query"},{"schema":{"type":"number","minimum":0,"exclusiveMinimum":true,"description":"Optional. If set, switches to best-execution mode: per-DEX net_out is computed for this trade size (in base units, decimal-adjusted), and best_dex picks the DEX with the largest net_out (not just deepest TVL).","example":1000},"required":false,"name":"amount_in","in":"query"}],"responses":{"200":{"description":"Aggregated best price across Cardano DEXes","content":{"application/json":{"schema":{"type":"object","properties":{"pair":{"type":"string"},"best_price":{"type":"number"},"best_dex":{"type":"string","enum":["minswap_v2","wingriders","sundaeswap"]},"slippage_1pct":{"type":"number","description":"Effective price when trading 1% of best pool depth"},"slippage_5pct":{"type":"number","description":"Effective price when trading 5% of best pool depth"},"amount_in":{"type":"number","description":"Echoed when present in request"},"best_amount_out":{"type":"number","description":"Quote tokens received from best_dex for amount_in"},"best_effective_price":{"type":"number","description":"best_amount_out / amount_in"},"sources":{"type":"array","items":{"type":"object","properties":{"dex":{"type":"string"},"price":{"type":"number"},"pool_tvl_ada":{"type":"number"},"amount_out":{"type":"number"},"effective_price":{"type":"number"},"price_impact_pct":{"type":"number"}},"required":["dex","price","pool_tvl_ada"]}},"ts":{"type":"number","description":"Quote timestamp (unix ms)"}},"required":["pair","best_price","best_dex","slippage_1pct","slippage_5pct","sources","ts"]}}}},"400":{"description":"Bad pair","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"]}}}},"402":{"description":"Payment required (x402)"},"404":{"description":"No pool found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"]}}}},"429":{"description":"Free tier exhausted"}}}},"/cardano/wallet/portfolio":{"get":{"tags":["Wallet"],"summary":"Cardano wallet portfolio (ADA + native tokens + USD totals)","description":"Returns balances + staking delegation + native tokens (with USD value for tokens in our registry) + NFT count. Payment addresses with a stake key aggregate across the full wallet via the stake address. Cost: 10 credits/call after free tier (20/IP/day). USD pricing derives from /dex/price (ADA/USDM as USD anchor).","parameters":[{"schema":{"type":"string","minLength":10,"description":"Mainnet Cardano address. Payment (addr1…) or stake (stake1…). Payment with stake-key aggregates the wallet via its stake address.","example":"addr1q9um0fjz9z3stkz9k7m3zp2gp0xkwzjvr3a3rwnxck8klznzc6dxr8jvk5x8mkdc09qd7vlqd5spc7jxxx68aqaad79qtwfk7m"},"required":true,"name":"address","in":"query"}],"responses":{"200":{"description":"Wallet portfolio: ADA balance + staking + native tokens + NFT count + USD totals.","content":{"application/json":{"schema":{"type":"object","properties":{"address":{"type":"string"},"stake_address":{"type":"string","nullable":true},"ada":{"type":"object","properties":{"balance_lovelace":{"type":"string"},"balance_ada":{"type":"number"},"rewards_lovelace":{"type":"string"},"delegation":{"type":"object","nullable":true,"properties":{"pool_id":{"type":"string"},"active":{"type":"boolean"}},"required":["pool_id","active"]},"usd_value":{"type":"number","nullable":true}},"required":["balance_lovelace","balance_ada","rewards_lovelace","delegation","usd_value"]},"tokens":{"type":"array","items":{"type":"object","properties":{"unit":{"type":"string"},"policy":{"type":"string"},"name_hex":{"type":"string"},"symbol":{"type":"string","nullable":true},"decimals":{"type":"number","nullable":true},"quantity_raw":{"type":"string"},"quantity":{"type":"number","nullable":true},"price_ada":{"type":"number","nullable":true},"usd_value":{"type":"number","nullable":true}},"required":["unit","policy","name_hex","symbol","decimals","quantity_raw","quantity","price_ada","usd_value"]}},"nft_count":{"type":"number"},"totals":{"type":"object","properties":{"usd":{"type":"number","nullable":true},"priced_token_count":{"type":"number"},"unpriced_token_count":{"type":"number"}},"required":["usd","priced_token_count","unpriced_token_count"]},"ts":{"type":"number"}},"required":["address","stake_address","ada","tokens","nft_count","totals","ts"]}}}},"400":{"description":"Bad address","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"]}}}},"402":{"description":"Payment required (x402)"},"404":{"description":"Address not found on chain","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"]}}}},"429":{"description":"Free tier exhausted"},"503":{"description":"Blockfrost not configured","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"]}}}}}}},"/cardano/defi/liqwid/market/{id}/health":{"get":{"tags":["Liqwid"],"summary":"Liqwid market health (8 credits/call)","description":"Returns Liqwid market identity + live on-chain liquidity at the pool shard + qToken total supply + MarketState datum decode (gross supply, borrowed, utilization, true qTokenRate, interest rate). Supported markets: usdcx, djed, usdm.","parameters":[{"schema":{"type":"string","description":"Market id. One of: usdcx, djed, usdm.","example":"djed"},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Liqwid market health: on-chain pool liquidity + qToken supply + derived rate (lower bound).","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"asset":{"type":"object","properties":{"symbol":{"type":"string"},"unit":{"type":"string"},"decimals":{"type":"number"}},"required":["symbol","unit","decimals"]},"qtoken_policy":{"type":"string"},"market_state_token":{"type":"string"},"pool_shard_address":{"type":"string"},"risk_tier":{"anyOf":[{"type":"number","enum":[1]},{"type":"number","enum":[2]},{"type":"number","enum":[3]}]},"stablecoin_type":{"type":"string","enum":["fiat-backed","algorithmic","synthetic","volatile"]},"liquidity":{"type":"object","properties":{"underlying_at_pool_raw":{"type":"string"},"underlying_at_pool":{"type":"number"},"lovelace_at_pool":{"type":"string"},"utxo_count":{"type":"number"}},"required":["underlying_at_pool_raw","underlying_at_pool","lovelace_at_pool","utxo_count"]},"qtoken":{"type":"object","properties":{"asset_unit":{"type":"string","nullable":true},"total_supply_raw":{"type":"string","nullable":true},"total_supply":{"type":"number","nullable":true}},"required":["asset_unit","total_supply_raw","total_supply"]},"market_state":{"type":"object","nullable":true,"properties":{"available":{"type":"number"},"available_raw":{"type":"string"},"borrowed":{"type":"number"},"borrowed_raw":{"type":"string"},"gross_supply":{"type":"number"},"gross_supply_raw":{"type":"string"},"utilization_pct":{"type":"number"},"qtoken_rate":{"type":"object","properties":{"num":{"type":"string"},"den":{"type":"string"},"ratio":{"type":"number"}},"required":["num","den","ratio"]},"interest_rate":{"type":"object","properties":{"num":{"type":"string"},"den":{"type":"string"},"ratio":{"type":"number"}},"required":["num","den","ratio"]}},"required":["available","available_raw","borrowed","borrowed_raw","gross_supply","gross_supply_raw","utilization_pct","qtoken_rate","interest_rate"]},"ts":{"type":"number"}},"required":["id","name","asset","qtoken_policy","market_state_token","pool_shard_address","risk_tier","stablecoin_type","liquidity","qtoken","market_state","ts"]}}}},"400":{"description":"Unknown market id","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"]}}}},"402":{"description":"Payment required (x402)"},"429":{"description":"Free tier exhausted"},"503":{"description":"Blockfrost not configured","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"]}}}}}}},"/cardano/defi/liqwid/market/{id}/apy":{"get":{"tags":["Liqwid"],"summary":"Liqwid market APY (8 credits/call)","description":"Realized APY computed from qTokenRate history (snapshots taken whenever /market/{id}/health is called, 10-min bucket dedup). Returns `insufficient_data: true` until ≥1h of history accumulates. For USDCx, `apy_estimate_kink` provides an immediate borrow/supply APY using known governance kink parameters. Supported markets: usdcx, djed, usdm.","parameters":[{"schema":{"type":"string","description":"Market id. One of: usdcx, djed, usdm.","example":"usdcx"},"required":true,"name":"id","in":"path"},{"schema":{"type":"number","minimum":0,"exclusiveMinimum":true,"maximum":720,"description":"Lookback window in hours (max 720h = 30d). Default 24. APY = compound-annualized return of qTokenRate over the window.","example":24},"required":false,"name":"window","in":"query"}],"responses":{"200":{"description":"Liqwid market APY: realized return of qTokenRate over the window + USDCx kink-model estimate.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"window_hours":{"type":"number"},"samples":{"type":"number"},"first_ts":{"type":"number","nullable":true},"last_ts":{"type":"number","nullable":true},"rate_start":{"type":"number","nullable":true},"rate_end":{"type":"number","nullable":true},"apy_realized_pct":{"type":"number","nullable":true},"insufficient_data":{"type":"boolean"},"apy_estimate_kink":{"type":"object","nullable":true,"properties":{"borrow_apy_pct":{"type":"number"},"supply_apy_pct":{"type":"number"},"utilization_pct":{"type":"number"},"note":{"type":"string"}},"required":["borrow_apy_pct","supply_apy_pct","utilization_pct","note"]},"ts":{"type":"number"}},"required":["id","window_hours","samples","first_ts","last_ts","rate_start","rate_end","apy_realized_pct","insufficient_data","apy_estimate_kink","ts"]}}}},"400":{"description":"Unknown market id","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"]}}}},"402":{"description":"Payment required (x402)"},"429":{"description":"Free tier exhausted"}}}},"/cardano/cross/arb":{"get":{"tags":["Cross"],"summary":"Cardano DEX × OKX spot arbitrage signal (8 credits/call)","description":"Sizes a trade across Cardano (best DEX via aggregator) and OKX (live spot bid/ask), reports direction + gross spread. Assumes 1 USDM ≈ 1 USDT. Excludes bridging/CEX-withdraw cost. Useful as input for trading-bot / funding-arb agents.","parameters":[{"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]+\\/[A-Za-z0-9_-]+$","description":"BASE/QUOTE. Quote semantics are strict — no silent USDT↔USDM substitution. ?pair=ADA/USDT returns OKX-only (no real USDT DEX pool on Cardano). ?pair=ADA/USDM returns Cardano-only (OKX has no ADA-USDM). ?pair=NIGHT/USDT returns OKX-only, ?pair=NIGHT/USDM returns both legs (SundaeSwap + OKX cross).","example":"ADA/USDT"},"required":true,"name":"pair","in":"query"},{"schema":{"type":"number","minimum":0,"exclusiveMinimum":true,"description":"Amount of base token (decimal) to size the spread analysis around.","example":1000},"required":true,"name":"amount_in","in":"query"},{"schema":{"type":"boolean","nullable":true,"description":"When true (default false), USD stablecoin quotes (USDT/USDC/USDM/DJED/USDA) are normalized: Cardano leg uses USDM, OKX leg uses USDT. Lets a single call do a pseudo cross-venue spread at the cost of ~0.1% intraday USDM/USDT drift. Strict mode (false) returns null on either side if the exact pair has no real market.","example":true},"required":false,"name":"compare_usd","in":"query"}],"responses":{"200":{"description":"Cardano DEX vs OKX spot spread analysis","content":{"application/json":{"schema":{"type":"object","properties":{"pair":{"type":"string"},"amount_in":{"type":"number"},"cardano":{"type":"object","nullable":true,"properties":{"route":{"type":"string","enum":["direct","via_ada"]},"best_dex":{"type":"string"},"quote_token":{"type":"string"},"net_out":{"type":"number"},"effective_price":{"type":"number"},"price_impact_pct":{"type":"number"},"pool_tvl_ada":{"type":"number"},"hops":{"type":"array","items":{"type":"object","properties":{"dex":{"type":"string"},"base_symbol":{"type":"string"},"quote_symbol":{"type":"string"},"amount_in":{"type":"number"},"amount_out":{"type":"number"}},"required":["dex","base_symbol","quote_symbol","amount_in","amount_out"]}}},"required":["route","best_dex","quote_token","net_out","effective_price","price_impact_pct","pool_tvl_ada","hops"]},"cex_okx":{"type":"object","nullable":true,"properties":{"inst_id":{"type":"string"},"bid":{"type":"number","nullable":true},"ask":{"type":"number","nullable":true},"last":{"type":"number"},"sell_base_price":{"type":"number","nullable":true},"buy_base_price":{"type":"number","nullable":true},"sell_base_proceeds":{"type":"number","nullable":true},"vol_24h_usdt":{"type":"number","nullable":true},"depth_simulated":{"type":"object","nullable":true,"properties":{"sell_avg_price":{"type":"number"},"sell_proceeds":{"type":"number"},"sell_levels_consumed":{"type":"number"},"sell_fully_filled":{"type":"boolean"},"buy_avg_price":{"type":"number"},"buy_cost":{"type":"number"},"buy_levels_consumed":{"type":"number"},"buy_fully_filled":{"type":"boolean"},"slippage_vs_top_bid_pct":{"type":"number"}},"required":["sell_avg_price","sell_proceeds","sell_levels_consumed","sell_fully_filled","buy_avg_price","buy_cost","buy_levels_consumed","buy_fully_filled","slippage_vs_top_bid_pct"]}},"required":["inst_id","bid","ask","last","sell_base_price","buy_base_price","sell_base_proceeds","vol_24h_usdt","depth_simulated"]},"spread":{"type":"object","properties":{"direction":{"type":"string","enum":["buy_cardano_sell_okx","buy_okx_sell_cardano","no_arb","cex_unlisted","cardano_no_pool"]},"gross_profit_pct":{"type":"number","nullable":true},"cardano_vs_okx_bid_pct":{"type":"number","nullable":true},"cardano_vs_okx_ask_pct":{"type":"number","nullable":true},"note":{"type":"string"}},"required":["direction","gross_profit_pct","cardano_vs_okx_bid_pct","cardano_vs_okx_ask_pct","note"]},"ts":{"type":"number"}},"required":["pair","amount_in","cardano","cex_okx","spread","ts"]}}}},"400":{"description":"Bad pair / unsupported quote","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"]}}}},"402":{"description":"Payment required (x402)"},"404":{"description":"No DEX pool / OKX ticker","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"]}}}},"429":{"description":"Free tier exhausted"}}}},"/cardano/cross/basis-trade":{"get":{"tags":["Cross"],"summary":"Long-Cardano-spot × short-OKX-perp basis trade signal (8 credits/call)","description":"Combines OKX funding rate APR (currently negative = shorts collect), Cardano spot price (USDM via best DEX), and Cardano staking yield (~3% configurable). When funding is sufficiently negative (≤ −1% APR), recommends long-spot + short-perp for combined yield. Otherwise recommends plain Cardano staking. Returns daily yield, breakeven days vs entry cost, and risk list. ADA only for now (other bases lack deep OKX SWAP markets).","parameters":[{"schema":{"type":"string","description":"Base asset. Currently supports ADA only.","example":"ADA"},"required":true,"name":"base","in":"query"},{"schema":{"type":"number","minimum":0,"exclusiveMinimum":true,"description":"Position size in BASE units.","example":10000},"required":true,"name":"amount_in","in":"query"}],"responses":{"200":{"description":"Basis-trade signal","content":{"application/json":{"schema":{"type":"object","properties":{"base":{"type":"string"},"amount_in":{"type":"number"},"current":{"type":"object","properties":{"cardano_spot_usdm":{"type":"number","nullable":true},"okx_swap_last_usdt":{"type":"number","nullable":true},"okx_spot_last_usdt":{"type":"number","nullable":true},"funding_rate":{"type":"number","nullable":true},"funding_apr_pct":{"type":"number","nullable":true},"funding_interval_hours":{"type":"number","nullable":true},"cardano_staking_apr_pct":{"type":"number"}},"required":["cardano_spot_usdm","okx_swap_last_usdt","okx_spot_last_usdt","funding_rate","funding_apr_pct","funding_interval_hours","cardano_staking_apr_pct"]},"recommended_strategy":{"type":"string","enum":["long_cardano_spot_short_okx_swap","hold_cardano_spot_only","no_data"]},"rationale":{"type":"string"},"annual_yield_pct":{"type":"number","nullable":true},"position_notional_usd":{"type":"number","nullable":true},"daily_yield_usd":{"type":"number","nullable":true},"entry_cost_estimate_usd":{"type":"number"},"breakeven_days":{"type":"number","nullable":true},"risks":{"type":"array","items":{"type":"string"}},"ts":{"type":"number"}},"required":["base","amount_in","current","recommended_strategy","rationale","annual_yield_pct","position_notional_usd","daily_yield_usd","entry_cost_estimate_usd","breakeven_days","risks","ts"]}}}},"400":{"description":"Unsupported base","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"]}}}},"402":{"description":"Payment required (x402)"},"404":{"description":"Required market data unavailable","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"]}}}}}}},"/cex/okx/funding/{instId}":{"get":{"tags":["OKX"],"summary":"OKX perp funding rate + history (5 credits/call)","description":"Current funding rate, next settlement, interval, annualized %, plus history. Use any OKX SWAP id (e.g. ADA-USDT-SWAP, BTC-USDT-SWAP).","parameters":[{"schema":{"type":"string","pattern":"^[A-Z0-9]+-[A-Z0-9]+(-[A-Z0-9]+)*$","description":"OKX instrument id (uppercase, hyphenated).","example":"ADA-USDT-SWAP"},"required":true,"name":"instId","in":"path"},{"schema":{"type":"integer","nullable":true,"minimum":0,"maximum":100,"description":"History rows (0–100). Default 30. 0 = skip history fetch.","example":30},"required":false,"name":"history","in":"query"}],"responses":{"200":{"description":"OKX funding snapshot + history","content":{"application/json":{"schema":{"type":"object","properties":{"inst_id":{"type":"string"},"funding_rate":{"type":"number"},"funding_time_ms":{"type":"number"},"next_funding_rate":{"type":"number","nullable":true},"next_funding_time_ms":{"type":"number","nullable":true},"interval_ms":{"type":"number"},"annualized_pct":{"type":"number","nullable":true},"history":{"type":"array","items":{"type":"object","properties":{"funding_rate":{"type":"number"},"funding_time_ms":{"type":"number"},"realized_rate":{"type":"number","nullable":true}},"required":["funding_rate","funding_time_ms","realized_rate"]}},"ts":{"type":"number"}},"required":["inst_id","funding_rate","funding_time_ms","next_funding_rate","next_funding_time_ms","interval_ms","annualized_pct","history","ts"]}}}},"400":{"description":"Bad instrument id","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"]}}}},"402":{"description":"Payment required (x402)"},"404":{"description":"OKX returned no data","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"]}}}},"429":{"description":"Free tier exhausted"}}}},"/cex/okx/ticker/{instId}":{"get":{"tags":["OKX"],"summary":"OKX spot ticker (3 credits/call)","description":"Live last / bid / ask / 24h OHLV. Any OKX SPOT id (e.g. ADA-USDT, BTC-USDT, SNEK-USDT).","parameters":[{"schema":{"type":"string","pattern":"^[A-Z0-9]+-[A-Z0-9]+(-[A-Z0-9]+)*$","example":"ADA-USDT"},"required":true,"name":"instId","in":"path"}],"responses":{"200":{"description":"OKX 24h ticker","content":{"application/json":{"schema":{"type":"object","properties":{"inst_id":{"type":"string"},"last":{"type":"number"},"ask":{"type":"number","nullable":true},"bid":{"type":"number","nullable":true},"open_24h":{"type":"number","nullable":true},"high_24h":{"type":"number","nullable":true},"low_24h":{"type":"number","nullable":true},"vol_ccy_24h":{"type":"number","nullable":true},"vol_24h":{"type":"number","nullable":true},"ts":{"type":"number"}},"required":["inst_id","last","ask","bid","open_24h","high_24h","low_24h","vol_ccy_24h","vol_24h","ts"]}}}},"400":{"description":"Bad instrument id","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"]}}}},"402":{"description":"Payment required (x402)"},"404":{"description":"OKX returned no data","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error","message"]}}}},"429":{"description":"Free tier exhausted"}}}}}}