Research API and MCP quickstart

Connect your AI assistant to inspect a market or test conditions from a chart.

Start with a chart

1. Connect your assistant. Add EdgeDepth from MCP setup and sign in through the browser authorization screen.
2. Show it the move. In an image-capable assistant, paste a chart and ask: “What happened before this move, and how did similar setups turn out?” You can also name a coin and time.
3. Review, then investigate. Confirm any unclear symbol, venue or timestamp. Check the proposed conditions, markets, dates and allowance estimate before approving a new study.

Your assistant reads the image. EdgeDepth tests confirmed conditions against recorded data. A screenshot cannot supply missing readings.

See the chart walkthrough → · Connection guide →

REST API quickstart

This is the programmatic interface to the same search engine available at Research Workbench. Search recorded crypto and TradFi perpetuals from your own code and inspect historical matches. Tick replay depends on recorded coverage and plan access; searchable history can extend beyond order-book recordings.

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. research:read covers everything on this page. Add research:interpret only if your code will turn prose into proposed queries.

2. Read 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. Review the scope and 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? These fixed dates are an example, not a claim about the latest coverage. Check available history and the credit estimate and limits before running a study.

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 (keep it with the query and dataset revision), 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.

Choose a next step

Read completed and missing outcome windows separately. Missing outcomes are not zero returns. When an unconditional same-scope reference is available, it includes matches and is not a matched control group. Adjacent observations may overlap. These summaries describe historical behaviour; they do not establish causality or net strategy profitability.

Inspect counterexamples, test a separate period or stop pursuing an unsupported idea. To save a study or confirm monitoring of a supported definition, use the web Workbench. MCP research tools do not change alerts or execute trades. Monitoring applies supported conditions to future closed market minutes; it does not turn the historical study into an automated verdict.

5. Revalidate a cached result

Repeat the exact call with the ETag you received. An unchanged result answers 304 and spends nothing. Save the original request body as same-document.json for the example below. Cache hits are also free. New data or a changed definition can produce a new result identity and a charge for fresh computation. The response header X-Research-Cache: hit identifies cached bytes.

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

Reading an existing public report consumes no research allowance. Keep the query document and original response when you need a durable research record; a fresh scan against a later dataset can differ.

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