Search by API

One key, one query, one reproducibility key. Under 5 minutes.

This is the programmatic interface to the same search engine available at /research. Search recorded crypto and TradFi perpetuals from your own code, then open any returned occurrence in tick replay.

1. Create a key

Open the Developer page and generate a key. The full key (edk_live_...) is shown once: only its hash is stored. The generated MCP key includes both research scopes, and research:read covers everything on this page.

2. Ground yourself: the registry

The registry is the live, closed list of everything a query may say: feature ids, operators, window aggregates, sequence rules, limits and error codes. It is generated from the same contract that validates every document, so clients discover new fields here instead of hard-coding them.

curl -s https://app.edgedepth.com/api/v1/research/registry \
  -H "Authorization: Bearer edk_live_YOUR_KEY"

3. Run one scan

The request body is a research_query.v2 document: stated conditions only, fail-closed validation, named error codes. This one asks: on 3 majors over 7 days, where was VPIN at or above 0.7?

curl -s https://app.edgedepth.com/api/v1/research/query \
  -H "Authorization: Bearer edk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "schema_version": "research_query.v2",
    "normalization_version": "archive_normalization.v1",
    "feature_version": "feature_defs.v1",
    "target": "record_occurrences",
    "where": { "all": [
      ["identity.symbol", "in", ["btcusdt", "ethusdt", "solusdt"]],
      ["times.anchor_time", "between", ["2026-07-09T00:00:00Z", "2026-07-16T00:00:00Z"]],
      ["feature.vpin", "gte", 0.7]
    ]},
    "sort": ["times.anchor_time", "desc"],
    "page": { "limit": 50, "cursor": null }
  }'

4. Read the result

The response body is the engine's canonical bytes, verbatim. Start with three things: reproducibility_key (cite it; same key means byte-identical result, forever), counts (occurrences WITH their denominators: eligible buckets, warmup exclusions), and outcomes_summary (what followed, computed forward over ALL occurrences; page rows are examples, never the denominator).

The headers carry the same identity: X-Canonical-Query-Hash, X-Dataset-Revision, X-Research-Feature-Ver, and an ETag derived from the full tuple.

5. Re-run it free

Replay the exact call with the ETag you received; identical data answers 304 and spends nothing. Re-running a result never spends: cached bytes are served, and X-Research-Cache: hit says so.

curl -s -i https://app.edgedepth.com/api/v1/research/query \
  -H "Authorization: Bearer edk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H 'If-None-Match: "ETAG_FROM_STEP_3"' \
  -d @same-document.json

Next: the grammar for every field the contract speaks, credits + limits for what scans cost, and worked examples including sequences and paging.