Skip to content

Data Ocean

Sharpe Data Ocean exposes governed analytics datasets that agents and applications can discover, query, and inspect without sending arbitrary SQL.

GET/v1/meta/datasets

Dataset catalog

Returns the public catalog of queryable datasets, fields, allowed filter operators, default selections, source labels, and freshness service levels.

Authentication: none required.

cURL

curl https://www.sharpe.ai/api/v1/meta/datasets

Response shape

{
  "data": {
    "dataset_count": 3,
    "datasets": {
      "funding_rates_current": {
        "id": "funding_rates_current",
        "name": "Current Funding Rates",
        "backing_kind": "supabase_table",
        "source_labels": ["Supabase", "Binance", "Bybit", "OKX"],
        "freshness_sla_seconds": 300,
        "default_limit": 100,
        "max_limit": 500,
        "fields": [
          {
            "id": "base_coin",
            "type": "string",
            "role": "dimension",
            "filter_ops": ["eq", "in"],
            "sortable": true
          }
        ]
      }
    }
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-06-04T12:00:00Z",
    "elapsed_ms": 2
  }
}
POST/v1/analytics/query

Analytics query

Runs a bounded analytics query against a cataloged dataset. The endpoint accepts only registered dataset IDs, whitelisted fields, whitelisted filter operators, whitelisted sort fields, and opaque cursors.

Authentication: API key required. During the initial rollout the route is gated by SHARPE_DATA_OCEAN_V1_ENABLED.

Request body

  • Name
    dataset
    Type
    string
    Description

    Dataset ID from /v1/meta/datasets.

  • Name
    select
    Type
    string[]
    Description

    Optional list of fields to return. Defaults to the dataset's default_select.

  • Name
    filters
    Type
    object[]
    Description

    Optional filters. Supported operators are eq, in, gte, and lte, depending on the field contract.

  • Name
    sort
    Type
    object[]
    Description

    Optional sort fields. Each item has field and direction, where direction is asc or desc.

  • Name
    limit
    Type
    integer
    Description

    Maximum rows to return. Defaults to 100; the global cap is 500, and datasets may define lower caps.

  • Name
    cursor
    Type
    string
    Description

    Opaque cursor returned by the previous response.

cURL

curl https://www.sharpe.ai/api/v1/analytics/query \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "dataset": "funding_rates_current",
    "select": ["exchange", "symbol", "base_coin", "rate", "updated_at"],
    "filters": [{ "field": "base_coin", "op": "eq", "value": "BTC" }],
    "sort": [{ "field": "updated_at", "direction": "desc" }],
    "limit": 100
  }'

Response shape

{
  "data": {
    "dataset_id": "funding_rates_current",
    "rows": [
      {
        "exchange": "binance",
        "symbol": "BTCUSDT",
        "base_coin": "BTC",
        "rate": 0.0001,
        "updated_at": "2026-06-04T12:00:00Z"
      }
    ],
    "data_meta": {
      "dataset_id": "funding_rates_current",
      "source": ["Supabase", "Binance", "Bybit", "OKX"],
      "as_of": "2026-06-04T12:00:00Z",
      "freshness_status": "fresh",
      "cache_status": "live",
      "runtime_status": "ok",
      "warnings": [],
      "truncated": false
    },
    "pagination": {
      "cursor": null,
      "has_more": false
    }
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-06-04T12:00:00Z",
    "elapsed_ms": 9
  }
}

Initial datasets

DatasetBackingNotes
funding_rates_currentSupabase tableRow dataset for current funding rates.
funding_accumulatedSupabase materialized viewRow dataset for accumulated funding sums and settlement counts.
stablecoins_metricstracker_cache snapshotSnapshot dataset for stablecoin aggregates, items, histories, and chain rows.

Safety model

  • The query route does not accept SQL, table names, or arbitrary column names.
  • The Supabase service-role client is used only on the server.
  • Each dataset defines its own fields, filters, sorts, default limit, max limit, sources, and freshness SLA.
  • The query route returns Cache-Control: no-store; the catalog route is cacheable because it contains metadata only.
  • Snapshot datasets return a snapshot payload instead of pretending to be row-queryable tables.

Was this page helpful?