Cardano Data API

Cross-venue trading signals and on-chain Cardano data for AI agents — listed on the Sokosumi marketplace via the Masumi protocol. One agent, one synthesized briefing, nine underlying building blocks.


Live (preprod)	https://cardano-api-preprod.optivaults.app
Network	Cardano Preprod (Mainnet planned)
Pricing	0.5 tUSDM per call
Protocol	MIP-003 / x402 over Masumi
Author	OptiVaults

`cardano/alpha` — the headline endpoint

One call returns the full Cardano cross-venue briefing for any pair, sized to your amount_in:

Prices across Cardano DEX best-execution + OKX + Binance spot
Spread with direction, gross + net profit %, best CEX, and live anomaly flag
Basis-trade signal (funding rate × Cardano staking, with strategy auto-pick)
Recent anomalies — last 24h spread-anomaly events for the pair
Liqwid yield — realized APY on USDM + USDCx supply
Recommended action — rule-based decision (execute_arb / basis_trade / lend_usdm / wait) with confidence scoring and human-readable reasoning
Stats block — rank_30d (percentile vs 30d distribution) and momentum (widening / tightening / flat) populate once spread_history accumulates ≥ 720 hourly samples per pair. Until then, the samples_collected / ready_in_hours countdown is honest about the state.

GET /cardano/alpha?pair=ADA/USDM&amount_in=10000

Designed for AI trading agents that want a single structured response instead of stitching together six upstream APIs. The nine endpoints below are the same data exposed individually — use them when you only need one slice.

Cross-venue trading signals

The differentiated endpoints — synthesizing data nobody else combines in one call.

Endpoint	Why it’s unique
`cross/basis-trade`	OKX funding APR + Cardano spot + Cardano staking APR with strategy auto-pick (long-spot+short-perp when funding deeply negative, else hold-spot). Returns annualized yield, daily yield USD, breakeven days vs bridge cost. The only API on Cardano synthesizing all three.
`cross/arb`	Cardano DEX best-execution (Minswap V2 / WingRiders / SundaeSwap aggregated by net_out) × OKX orderbook depth (walked bid/ask levels) with bridge cost deducted (`net_profit_pct` reflects OKX withdraw fee + Cardano network fee per direction) and statistical anomaly assessment (`anomaly.is_anomaly` flags samples that are >2σ from the prior-hour baseline OR >2% absolute). Apples-to-apples large-order comparison at any `amount_in` — no DEX aggregator delivers executable net spread with built-in surprise detection.
`cross/anomalies`	Historical spread-anomaly events recorded by every `/cross/arb` call. Use it to back-test trading-bot triggers, alert on transient pool imbalances, or measure your alpha capture rate.

On-chain Cardano data

Endpoint	What it returns
`liqwid/health`	Live Liqwid market health: pool liquidity, qToken supply, true qTokenRate, utilization, interest rate. Only public API decoding the MarketState datum directly.
`liqwid/apy`	Realized APY from our qTokenRate snapshot history + kink-model estimate (USDCx). Liqwid’s own dashboard shows projected, not realized.
`dex/price`	Best-execution price across Minswap V2 + WingRiders + SundaeSwap. Optional `amount_in` for true net_out routing with per-source slippage.
`wallet/portfolio`	Full wallet snapshot: ADA + staking + native tokens (USD-priced via `/dex/price`) + NFT count. addr1 / stake1 both accepted. Mainnet-only (Preprod returns 404 — arbitrary wallets can’t be snapshotted in advance).

OKX passthrough (bundled for convenience)

Endpoint	What it returns
`okx/funding`	OKX perpetual funding rate + history + annualized %.
`okx/ticker`	OKX 24h spot ticker.

Environments

Environment	Data	Free-tier (direct REST)	Sokosumi pricing	Purpose
Preprod (current)	Hourly snapshots of real mainnet data, refreshed every hour at :05. Responses tagged `_environment: "preprod-t1"` + `_snapshot_date`. Restricted to a canonical params set per endpoint.	1000 calls / IP / endpoint / day	0.5 tUSDM flat	Evaluate real aggregation quality + data shape before paying for real-time mainnet
Mainnet (planned)	Real-time live data from on-chain + OKX, no params restriction	5 calls / IP / endpoint / day	TBD — designed against preprod traffic	Production trading-signal alpha

Build your integration against the Preprod URL. Preprod returns yesterday’s real Minswap V2 / WingRiders / SundaeSwap / OKX / Blockfrost data — not mock fixtures — so you can verify shape and aggregation quality before paying. Params outside the canonical set return 404 with the canonical set listed; the same parser will work against mainnet for arbitrary params once you switch the base URL. wallet/portfolio is mainnet-only by design (arbitrary wallets can’t be snapshotted daily).

Example responses

Every preprod response is tagged _environment: "preprod-t1" + _snapshot_date (the source date of the snapshot). Mainnet returns the same body shape with real-time values and no _environment tag. URLs below are live; click through to fetch them yourself.

cardano/alpha — GET /cardano/alpha?pair=ADA/USDM&amount_in=10000

{
  "pair": "ADA/USDM",
  "amount_in": 10000,
  "prices": { "cardano": 0.2390, "okx": 0.2397, "binance": 0.2396 },
  "spread": {
    "direction": "buy_cardano_sell_okx",
    "gross_profit_pct": 0.267,
    "net_profit_pct": 0.257,
    "best_cex": "okx",
    "is_anomaly": false
  },
  "basis_trade": {
    "recommended_strategy": "hold_cardano_spot_only",
    "annual_yield_pct": 3,
    "breakeven_days": 25.5
  },
  "recent_anomalies": [],
  "liqwid_yield": { "usdm_apy_pct": 5.85, "usdcx_apy_pct": 0.66 },
  "stats": {
    "rank_30d": null,
    "momentum": null,
    "samples_collected": 8,
    "samples_needed": 720,
    "ready_in_hours": 712
  },
  "recommended": {
    "action": "lend_usdm",
    "size_ada": null,
    "confidence": "medium",
    "reasoning": "Liqwid USDM realized APY 5.85% beats Cardano staking baseline ~3%."
  },
  "ts": 1779882897628,
  "_environment": "preprod-t1",
  "_snapshot_date": "2026-05-27",
  "_note": "Preprod returns hourly snapshots of real mainnet data, refreshed every hour at :05. For real-time data, use the Mainnet endpoint."
}

dex/price — GET /cardano/dex/price?pair=ADA/USDM&amount_in=1000

{
  "pair": "ADA/USDM",
  "best_price": 0.25,
  "best_dex": "minswap_v2",
  "slippage_1pct": 0.2495,
  "slippage_5pct": 0.24625,
  "sources": [
    { "dex": "minswap_v2",  "price": 0.25,    "pool_tvl_ada": 4000000, "amount_out": 249,        "effective_price": 0.249,        "price_impact_pct": 0.42 },
    { "dex": "wingriders",  "price": 0.25025, "pool_tvl_ada": 2500000, "amount_out": 249.249,    "effective_price": 0.249249,     "price_impact_pct": 0.42 },
    { "dex": "sundaeswap",  "price": 0.24975, "pool_tvl_ada": 1200000, "amount_out": 248.751,    "effective_price": 0.248751,     "price_impact_pct": 0.42 }
  ],
  "amount_in": 1000,
  "best_amount_out": 249.25,
  "best_effective_price": 0.24925,
  "ts": 1779688594507,
  "_environment": "preprod-t1",
  "_snapshot_date": "2026-05-25",
  "_note": "Preprod returns hourly snapshots of real mainnet data, refreshed every hour at :05. For real-time data, use the Mainnet endpoint."
}

wallet/portfolio — Preprod returns 404 (mainnet-only endpoint)

Wallet portfolio queries are mainnet-only by design — arbitrary wallets can’t be snapshotted in advance, and the value of this endpoint is asking about your wallet, not someone else’s. Preprod returns:

{
  "error": "preprod_params_not_in_snapshot",
  "message": "Preprod serves hourly snapshots for a fixed canonical params set. Your params are not in that set. Use the Mainnet endpoint for arbitrary params.",
  "requested_params": { "address": "addr1..." },
  "canonical_params": [],
  "mainnet_url": "https://cardano-api.optivaults.app"
}

On mainnet this endpoint accepts any addr1... (payment) or stake1... (stake) Cardano address — the stake form aggregates all delegated payment addresses. Returns ADA balance + staking delegation + native tokens (USD-priced via /dex/price) + NFT count. Mainnet response shape mirrors the other endpoints (no _environment tag, real-time values).

liqwid/health — GET /cardano/defi/liqwid/market/usdcx/health

{
  "id": "usdcx",
  "name": "Liqwid USDCX market",
  "asset": { "symbol": "USDCX", "decimals": 6 },
  "risk_tier": 2,
  "stablecoin_type": "fiat-backed",
  "liquidity": { "underlying_at_pool": 1500, "lovelace_at_pool": "5000000000", "utxo_count": 4 },
  "qtoken":    { "total_supply": 2000 },
  "market_state": {
    "available": 1500,
    "borrowed": 800,
    "gross_supply": 2300,
    "utilization_pct": 34.78,
    "qtoken_rate":   { "num": "10123", "den": "10000", "ratio": 1.0123 },
    "interest_rate": { "num": "85",    "den": "1000",  "ratio": 0.085  }
  },
  "ts": 1779688595315,
  "_environment": "preprod-t1",
  "_snapshot_date": "2026-05-25",
  "_note": "Preprod returns hourly snapshots of real mainnet data, refreshed every hour at :05. For real-time data, use the Mainnet endpoint."
}

qtoken_rate.ratio is decoded directly from the on-chain MarketState datum, not derived from pool liquidity.

liqwid/apy — GET /cardano/defi/liqwid/market/usdcx/apy?window=24

{
  "id": "usdcx",
  "window_hours": 24,
  "samples": 12,
  "rate_start": 1.0120,
  "rate_end":   1.0123,
  "apy_realized_pct": 8.7,
  "insufficient_data": false,
  "apy_estimate_kink": {
    "borrow_apy_pct":   11.2,
    "supply_apy_pct":   3.9,
    "utilization_pct":  34.78,
    "note": "Kink-model estimate using Liqwid governance parameters."
  },
  "ts": 1779688595637,
  "_environment": "preprod-t1",
  "_snapshot_date": "2026-05-25",
  "_note": "Preprod returns hourly snapshots of real mainnet data, refreshed every hour at :05. For real-time data, use the Mainnet endpoint."
}

apy_realized_pct is compounded from our qTokenRate snapshot history ((end/start)^(8760/hours) − 1). apy_estimate_kink only populates for USDCx, derived from on-chain governance parameters.

cross/arb — GET /cardano/cross/arb?pair=ADA/USDT&amount_in=1000

{
  "pair": "ADA/USDT",
  "amount_in": 1000,
  "cardano": {
    "route": "direct",
    "best_dex": "minswap_v2",
    "quote_token": "USDM",
    "net_out": 250,
    "effective_price": 0.25,
    "price_impact_pct": 0.5,
    "pool_tvl_ada": 4000000,
    "hops": [{ "dex": "minswap_v2", "base_symbol": "ADA", "quote_symbol": "USDM", "amount_in": 1000, "amount_out": 250 }]
  },
  "cex_okx": {
    "inst_id": "ADA-USDT",
    "bid": 0.251748,
    "ask": 0.252252,
    "last": 0.252,
    "depth_simulated": {
      "sell_avg_price": 0.251496,
      "sell_fully_filled": true,
      "buy_avg_price":  0.252504,
      "buy_fully_filled": true,
      "slippage_vs_top_bid_pct": 0.12
    }
  },
  "spread": {
    "direction": "buy_cardano_sell_okx",
    "gross_profit_pct":         0.80,
    "cardano_vs_okx_bid_pct":   0.80,
    "cardano_vs_okx_ask_pct":   0.60,
    "net_profit_pct":           0.70,
    "bridge": {
      "okx_withdraw_ada":       0,
      "cardano_network_ada":    1.0,
      "total_ada":              1.0,
      "total_usd":              0.25,
      "ada_usd_price":          0.25,
      "fee_table_last_verified": "2026-05-25",
      "path": "buy_cardano_sell_okx"
    },
    "anomaly": {
      "z_score":          null,
      "is_anomaly":       false,
      "baseline_samples": 0,
      "baseline_mean":    null,
      "baseline_stddev":  null,
      "threshold_z":      2.0,
      "threshold_abs_pct": 2.0,
      "reason":           null
    },
    "note": "Bridge cost 2 × Cardano network 0.5 ADA (DEX swap + deposit-to-OKX tx) ≈ $0.25 at ADA 0.2500. OKX fee table verified 2026-05-25."
  },
  "ts": 1779688596096,
  "_environment": "preprod-t1",
  "_snapshot_date": "2026-05-25",
  "_note": "Preprod returns hourly snapshots of real mainnet data, refreshed every hour at :05. For real-time data, use the Mainnet endpoint."
}

depth_simulated walks the actual OKX orderbook levels (not the top-of-book quote) so large-order spreads stay honest. net_profit_pct is gross_profit_pct minus the bridge cost as a fraction of notional — only populated when the trade is executable (ADA arb with a USD-stable leg). For buy_cardano_sell_okx you pay 2 × Cardano network fee (DEX swap + deposit-to-OKX tx); for buy_okx_sell_cardano you pay OKX’s ADA withdraw fee (~1.2 ADA, live from OKX) + 1 × Cardano network fee. bridge.fee_table_last_verified is live:<isoTimestamp> when the value came from OKX’s /api/v5/asset/currencies (refreshed hourly), or static:<date> when the call fell back to a quarterly-verified static table because OKX was unreachable. anomaly is the statistical assessment vs the prior-hour baseline for this pair: z_score is null until ≥10 samples accumulate (insufficient data); is_anomaly=true when |z| > 2 OR |gross_profit_pct| > 2%. The historical event stream is queryable at cross/anomalies.

cross/basis-trade — GET /cardano/cross/basis-trade?base=ADA&amount_in=1000

{
  "base": "ADA",
  "amount_in": 1000,
  "current": {
    "cardano_spot_usdm":     0.25,
    "okx_swap_last_usdt":    0.252,
    "okx_spot_last_usdt":    0.251,
    "funding_rate":         -0.0005,
    "funding_apr_pct":     -54.75,
    "funding_interval_hours": 8,
    "cardano_staking_apr_pct": 3.0
  },
  "recommended_strategy": "long_cardano_spot_short_okx_swap",
  "rationale": "Funding ≤ −1% APR → long-spot collects funding + staking.",
  "annual_yield_pct":         57.75,
  "position_notional_usd":   250,
  "daily_yield_usd":          0.395,
  "entry_cost_estimate_usd":  5,
  "breakeven_days":           25,
  "risks": ["funding rate flip risk", "mainnet bridging cost"],
  "ts": 1779688596385,
  "_environment": "preprod-t1",
  "_snapshot_date": "2026-05-25",
  "_note": "Preprod returns hourly snapshots of real mainnet data, refreshed every hour at :05. For real-time data, use the Mainnet endpoint."
}

Strategy auto-switches: deeply-negative funding → long-spot + short-perp; otherwise → hold-spot.

cross/anomalies — GET /cardano/cross/anomalies?pair=ADA/USDT&limit=10

{
  "threshold_z":       2.0,
  "threshold_abs_pct": 2.0,
  "count": 2,
  "events": [
    {
      "pair":             "ADA/USDT",
      "direction":        "buy_cardano_sell_okx",
      "gross_profit_pct":  2.45,
      "net_profit_pct":    2.35,
      "z_score":           2.80,
      "amount_in":        1000,
      "ts":               1779706702208
    },
    {
      "pair":             "ADA/USDT",
      "direction":        "buy_okx_sell_cardano",
      "gross_profit_pct": -2.18,
      "net_profit_pct":   -2.42,
      "z_score":          -2.15,
      "amount_in":         500,
      "ts":               1779704182208
    }
  ],
  "ts": 1779707002208,
  "_environment": "preprod-t1",
  "_snapshot_date": "2026-05-25",
  "_note": "Preprod returns hourly snapshots of real mainnet data, refreshed every hour at :05. For real-time data, use the Mainnet endpoint."
}

Returns every spread sample that was flagged anomalous (is_anomaly=true in the originating /cross/arb response). Default window is the last 7 days; filter with pair=, since_ms=, and limit= (max 500). Useful for back-testing strategy triggers, alerting on transient pool imbalances, or auditing how often a pair has crossed the threshold this week.

okx/funding — GET /cex/okx/funding/ADA-USDT-SWAP?history=5

{
  "inst_id": "ADA-USDT-SWAP",
  "funding_rate":          -0.0005,
  "funding_time_ms":       1779688536854,
  "next_funding_rate":     -0.00045,
  "next_funding_time_ms":  1779717336854,
  "interval_ms":           28800000,
  "annualized_pct":       -54.75,
  "history": [
    { "funding_rate": -0.00065, "funding_time_ms": 1779688596854, "realized_rate": -0.00065 },
    { "funding_rate": -0.00064, "funding_time_ms": 1779659796854, "realized_rate": -0.00064 },
    { "funding_rate": -0.00063, "funding_time_ms": 1779630996854, "realized_rate": -0.00063 }
  ],
  "ts": 1779688596854,
  "_environment": "preprod-t1",
  "_snapshot_date": "2026-05-25",
  "_note": "Preprod returns hourly snapshots of real mainnet data, refreshed every hour at :05. For real-time data, use the Mainnet endpoint."
}

okx/ticker — GET /cex/okx/ticker/ADA-USDT

{
  "inst_id":    "ADA-USDT",
  "last":       0.2515,
  "ask":        0.2517,
  "bid":        0.2513,
  "open_24h":   0.2480,
  "high_24h":   0.2550,
  "low_24h":    0.2460,
  "vol_ccy_24h": 12345678,
  "vol_24h":    49018350,
  "ts": 1779688597278,
  "_environment": "preprod-t1",
  "_snapshot_date": "2026-05-25",
  "_note": "Preprod returns hourly snapshots of real mainnet data, refreshed every hour at :05. For real-time data, use the Mainnet endpoint."
}

How it works

Agent
  │ POST /start_job  { identifier_from_purchaser, input_data: { endpoint, params } }
  ↓
Masumi mints a blockchainIdentifier for the job
  │ purchaser pays tUSDM to the smart contract
  ↓
Background worker watches Masumi state every 10s
  │ on FundsLocked → run handler → store result → submit_result
  ↓
Agent polls GET /status?job_id=<uuid> until status = completed

All nine endpoints share a single Sokosumi agent — pick which one at start_job time.

Quickstart

BASE=https://cardano-api-preprod.optivaults.app

# 1. Inspect what the agent accepts
curl $BASE/availability
curl $BASE/input_schema
curl "$BASE/input_schema?endpoint=dex/price"

# 2. Start a job — receive a Masumi blockchain identifier
curl -X POST $BASE/start_job \
  -H 'content-type: application/json' \
  -d '{
    "identifier_from_purchaser": "<14-26 hex chars>",
    "input_data": {
      "endpoint": "dex/price",
      "params": { "pair": "ADA/USDM", "amount_in": 1000 }
    }
  }'

# 3. Pay 0.5 tUSDM to the returned smart contract (via Masumi / Sokosumi UI)

# 4. Poll status
curl "$BASE/status?job_id=<uuid>"

For free direct REST (off-Sokosumi, 20 calls / IP / endpoint / day), hit endpoints directly — e.g. GET $BASE/cardano/dex/price?pair=ADA/USDM&amount_in=1000.

The full OpenAPI spec is at https://cardano-api-preprod.optivaults.app/openapi.json with interactive Swagger UI at /docs.

Data sources

Minswap V2 — public REST (api-mainnet-prod.minswap.org)
WingRiders V2 — public GraphQL
SundaeSwap — public REST
Blockfrost — wallet portfolio + Liqwid UTxOs + MarketState datum decode
OKX V5 — public market endpoints only (no order or withdraw paths)

Contact

OptiVaults — optivaults@gmail.com