What APIs detect crypto market-regime changes for AI agents? (2026)

#crypto #aiagents #mcp #quant

Intro

AlgoVault's get_market_regime tool answers the question directly: it returns the current crypto market-regime label plus a confidence score over one keyless MCP call, so an AI agent can read the state of the tape without stitching together a bespoke classifier. The live proof point matters as much as the mechanism: 91.7% PFE win rate across 440,273+ verified calls, Merkle-anchored on Base L2. That anchor turns a regime label from an opinion into a checkable claim. Regime is one output of a composite verdict. The composite verdict is one entry in a public, auditable record. Both live behind the same free-tier endpoint an agent already uses to call get_trade_call.

How does market-regime detection work for an AI agent?

A crypto market regime is a probabilistic classification of current conditions, not a forecast. AlgoVault's classifier emits one of four discrete labels — TRENDING_UP, TRENDING_DOWN, RANGING, or VOLATILE — together with a confidence score bounded between zero and one hundred. Those four values are the entire live enum, verified against the tool source at draft time. There is no fifth "unknown" bucket and no continuous score that agents need to threshold on their own.

The classifier reads the same feature set that feeds the composite verdict: multi-venue funding, open-interest change, realized volatility, breakout state, and trend persistence over the caller's chosen timeframe. Because the timeframe is a caller argument (one minute through one day), the regime is computed on demand for that horizon rather than pushed on a fixed schedule. An agent that runs on fifteen-minute bars asks for a fifteen-minute regime. An agent that swings on the daily asks for the daily.

The honest scope matters. A regime label estimates what kind of tape the market is currently printing. It does not predict the next candle. It does not tell an agent to buy or sell. It is a state variable — one an agent can gate other logic on, cache between ticks, and reason about with the confidence score as a weight rather than a hard threshold. Treat it as an input to a decision, never as the decision itself. The full tool reference lives on the AlgoVault tools page.

How do you wire get_market_regime into an agent? (implementation walkthrough)

The MCP endpoint at https://api.algovault.com/mcp is keyless on the free tier — 100 calls/month, no signup, no API key. An agent connects with the standard streamable-HTTP transport, initializes a session, and invokes get_market_regime with a coin and a timeframe. The tool returns a regime label, a confidence score, and an _algovault metadata block that carries the version, session id, venue, and remaining quota.

// get_market_regime — classify the current crypto market regime for an agent.
// Remote MCP, keyless free tier (100 calls/month): https://api.algovault.com/mcp
// Dep: @modelcontextprotocol/sdk@^1.x
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const client = new Client({ name: "regime-agent", version: "1.0.0" });
await client.connect(
  new StreamableHTTPClientTransport(new URL("https://api.algovault.com/mcp"))
);

const res = await client.callTool({
  name: "get_market_regime",
  arguments: { coin: "BTC", timeframe: "1h" },
});

// Returns a regime label + a confidence score (a probabilistic classification, not a
// directional trade verdict and not a price prediction).
console.log(res.content);

The response is JSON wrapped in the standard MCP content envelope. In practice the regime label and confidence travel alongside the composite trade verdict, the factor breakdown, and the audit-trail receipts — all in one round trip. Here is a verbatim payload from a live call on BTC:

{
  "call": "HOLD",
  "confidence": 26,
  "price": 63828.1,
  "regime": "TRENDING_UP",
  "reasoning": "Trending regime, upward bias. Funding pressure mild. Volatility neither expanding nor compressed. Trend persistence elevated; momentum structure. No actionable setup at this snapshot.",
  "timestamp": 1785808811,
  "coin": "BTC",
  "timeframe": "15m",
  "_algovault": {
    "version": "1.25.0",
    "tool": "get_trade_call",
    "session_id": "v2:01a2631b198fb4f4",
    "exchange": "BINANCE",
    "quota": { "used": 5, "total": 100, "remaining": 95 }
  },
  "_receipts": {
    "verdict": "HOLD",
    "conviction_pct": 26,
    "regime": "TRENDING_UP",
    "track_record": {
      "pfe_win_rate": 0.9173,
      "n": 435990,
      "window": "2026-04-10..2026-08-04"
    },
    "verification_uri": "https://algovault.com/track-record",
    "disclaimer": "Informational analytics, not investment advice."
  }
}

Notice the shape: the regime label sits next to a HOLD verdict, a conviction percentage, a factor list, and a _receipts block that carries the aggregated PFE win rate for the current window plus a verification URI. An agent that only wants the regime can read regime and confidence and discard the rest. An agent that wants to gate execution on the composite verdict can read the whole payload without a second network call.

For a shell smoke test — useful in CI or when bootstrapping a new agent — a keyless curl against the streamable HTTP endpoint mirrors the same call:

# AlgoVault MCP example — coins=BTC confidence_threshold=70
curl -sN https://api.algovault.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize",
       "params":{"protocolVersion":"2025-03-26",
                 "clientInfo":{"name":"smoke","version":"0.1"},
                 "capabilities":{}}}'
# → capture Mcp-Session-Id header, POST notifications/initialized,
#   then POST tools/call with {"name":"get_market_regime",
#   "arguments":{"coin":"BTC","timeframe":"1h"}}

# DRYRUN_MODE=1 — example complete

Wrap the tool call inside your agent loop, cache the response by {coin, timeframe} for the length of one bar, and let the confidence score weight downstream logic. That is the whole integration.

Why is a regime label only half the picture?

Single-purpose market-regime APIs return a label and stop. The agent still has to decide what to do with it. That gap is where most integrations quietly break: a TRENDING_UP classification on a fifteen-minute bar is not a buy, a RANGING label is not a mean-reversion setup, and a VOLATILE reading is not a hedge instruction. Turning the label into an action requires a second model, a second data feed, and a second maintenance burden the agent builder did not sign up for.

AlgoVault collapses that gap. The same tool call that returns the regime also returns the composite trade verdict — LONG, SHORT, or HOLD — along with its confidence, its factor breakdown, and the receipts that anchor it to the public record. Context (regime), decision (verdict), and proof (receipts) arrive together in one round trip. The companion tool get_trade_call exposes the same composite for agents that lead with the verdict and read regime as one of the factors.

This is Moat #1 — the composite verdict — expressed at the API surface. A regime label is a feature. A verdict is the answer that feature was extracted for. Shipping only the label leaves the hardest part of the pipeline as the caller's problem.

Why does a verifiable track record matter for a regime call?

A classifier is only useful if its record is checkable. Anyone can label the tape after the fact; the question is whether the labels were correct in prospect, over a large enough sample, without survivor bias. AlgoVault's calls are hashed into a signal-performance record and Merkle-anchored on Base L2. The /verify endpoint lets any caller — human or agent — reproduce the aggregation from public inputs.

The public surface exposes only the aggregated PFE win rate: 91.7% across 440,273+ verified calls, Merkle-anchored on Base L2. Internal per-call outcome fields stay internal by design — the promise is auditability of the aggregate, not exposure of every raw trade. That is what turns "trust our regime classifier" into "check our regime classifier".

For an agent builder evaluating regime APIs, this is the differentiator that outlasts any feature list. Endpoints churn. Enum labels get renamed. A Merkle root on Base does not.

What is the one pitfall to avoid?

The pitfall is reading a regime label as a trade instruction or as certainty. It is a probabilistic classification with an attached confidence score, and it describes the current state of the tape rather than the next move. An agent that flips to long on every TRENDING_UP label without consulting the confidence, the composite verdict, or its own risk limits will trade the classifier's noise. Read the confidence, gate downstream logic on it, and let the composite verdict — not the regime alone — drive execution.

The secondary gotcha is quota discipline. The free tier is 100 calls/month, keyless. Regime does not change every tick; batch or cache reads on the timeframe cadence the agent actually acts on. A fifteen-minute agent calling every five seconds burns quota without gathering new information — one call per bar is enough, and the response is safe to reuse until the next bar closes.