UmbraUmbrafeed
Open Dashboard

API reference

Funding

Cross-exchange funding-rate dislocations (ΔF) and perp↔spot hedge opportunities, as `umbra.funding.v1` events.

Planned /v1 event API

The /v1 endpoints documented here are the published event-API contract, but that serving layer is not deployed and these URLs return 404 today. The production machine rail is live separately at /api/v1/data, /mcp, and the authenticated family WebSocket routes. See Live APIs for endpoints that can be called now.

`kind` is `cross` (two venues' funding diverge) or `spot_hedge` (perp vs spot on one venue). Each side is a self-contained leg under `legs.long` / `legs.short` (venue, market, `funding_rate_pct`, `funding_interval_hours`, `funding_rate_8h_pct`, `price`, `volume_24h_usd`).

`rate_delta_pct` is the raw per-interval edge (what you see on the exchanges); `rate_delta_8h_pct` normalizes both legs to a common 8h base so rates on different intervals (8h vs 4h vs 1h) are comparable — use this one to rank.

Net-of-fees figures are published as plain arithmetic under neutral names: `rate_delta_net_pct` (= `rate_delta_pct` − `fees_pct`) and `entry_spread_net_pct` (= entry spread − the entry-side half of `fees_pct`). Advice-BRANDED fields (estimated PnL, safety ratio) are never published — the numbers are here, the recommendation is not.

GET recent

Last ≤500 funding events in memory, filtered.

GET/v1/funding/recent

Tier: Builder+

Query parameters

ParameterTypeDescription
min_rate_delta_pctfloatMinimum raw ΔF percent.
kindstringcross | spot_hedge.
max_time_to_funding_minfloatOnly opportunities settling within N minutes.
basestringExact base asset, e.g. BTC.
exclude_basestringBlacklist a base.
exchangestringMatch either leg.
min_volume_usdfloatMinimum leg volume in USD.
delayint (s)Hide events fresher than N seconds. Your tier clamps the minimum (see Access tiers).
limitintMax events to return. Capped server-side (recent ≤ 500, history per-tier).

Response

json
{
  "meta": { "trace": "c_4f2a…", "as_of": "2026-07-08T12:00:00.000Z", "count": 1, "delay_seconds": 0 },
  "data": [
    {
      "schema": "umbra.funding.v1",
      "event_type": "funding.dislocation",
      "funding_key": "funding:ORBS:kucoin:spot",
      "detected_at": "2026-07-08T12:00:00.000Z",
      "kind": "spot_hedge",
      "instrument": { "symbol": "ORBS_USDT", "base": "ORBS", "quote": "USDT" },
      "legs": {
        "long":  { "venue": "kucoin", "market": "spot",    "funding_rate_pct": null, "funding_interval_hours": 8, "funding_rate_8h_pct": null, "next_settlement_at": "2026-07-08T12:27:00.000Z", "price": 0.0201, "volume_24h_usd": 120000.0 },
        "short": { "venue": "kucoin", "market": "futures", "funding_rate_pct": 2.25, "funding_interval_hours": 8, "funding_rate_8h_pct": 2.25, "next_settlement_at": "2026-07-08T12:27:00.000Z", "price": 0.0203, "volume_24h_usd": 120000.0 }
      },
      "rate_delta_pct": 2.25,
      "rate_delta_8h_pct": 2.25,
      "fees_pct": 0.1,
      "entry_spread_pct": 0.99,
      "next_settlement_at": "2026-07-08T12:27:00.000Z",
      "seconds_to_settlement": 1620
    }
  ]
}

GET history

Durable funding event log, keyset-paginated.

GET/v1/funding/history

Tier: Builder+

Query parameters

ParameterTypeDescription
kindstringcross | spot_hedge.
min_rate_delta_pctfloatMinimum raw ΔF.
sinceint (ts)Return events at or after this unix timestamp.
beforeint (ts)Keyset pagination cursor — return events strictly older than this unix timestamp.
limitintMax events to return. Capped server-side (recent ≤ 500, history per-tier).

Response

json
{ "meta": { "trace": "c_4f2a…", "count": 100, "next_before": 1780990000 }, "data": [ /* umbra.funding.v1 events */ ] }

WS live

Filtered live funding stream.

WS/v1/funding/live

Tier: builder+

Query parameters

ParameterTypeDescription
min_rate_delta_pctfloatMinimum raw ΔF.
kindstringcross | spot_hedge.
basestringExact base.
delayint (s)Hide events fresher than N seconds. Your tier clamps the minimum (see Access tiers).

Response

json
// Typed event frame (umbra.funding.v1 event under "data"):
{ "type": "event", "family": "funding", "received_at": "2026-07-08T12:00:00.000Z",
  "data": { "schema": "umbra.funding.v1", "kind": "spot_hedge", "funding_key": "funding:ORBS:kucoin:spot",
            "rate_delta_pct": 2.25, "rate_delta_8h_pct": 2.25, "legs": { "long": { "venue": "kucoin", "market": "spot" }, "short": { "venue": "kucoin", "market": "futures" } }, "seconds_to_settlement": 1620 } }

Event fields

Payloads are curated — only the fields below are exposed. New upstream fields never leak by default (allowlist policy). Every response carries a per-consumer trace watermark.

ParameterTypeDescription
kindstringcross | spot_hedge.
instrumentobjectsymbol / base / quote.
legs.long / legs.shortobjectSelf-contained leg: venue, market, funding_rate_pct, funding_interval_hours, funding_rate_8h_pct, next_settlement_at, price, volume_24h_usd.
rate_delta_pctfloatRaw funding edge, percent per settlement interval.
rate_delta_8h_pctfloatEdge normalized to a common 8h base — comparable across intervals.
fees_pctfloatEstimated round-trip taker fees, percent.
next_settlement_atstringNext settlement (earlier leg), ISO-8601 UTC.
seconds_to_settlementintSeconds to next settlement.