Documentation

◆ Quick Start

Add AlgoVault to Claude Desktop in under 30 seconds. Paste this into your claude_desktop_config.json:

{
  "mcpServers": {
    "crypto-quant-signal": {
      "command": "npx",
      "args": ["-y", "crypto-quant-signal-mcp"]
    }
  }
}

Then ask Claude:

Free tier: all supported assets, all 11 timeframes (1m–1d), 200 calls/month (up to 100/day). No signup needed. Upgrade to Starter ($9.99/mo) or Pro for higher monthly limits and unlimited funding-arb results.

Your agent can also ask AlgoVault to teach itself how to use the tools — see Knowledge Tools below.

◆ Platform

◆ Tools

Six MCP tools: a directional trade call, market-regime classification, cross-venue funding arbitrage, a multi-asset trade-call scanner, and two knowledge tools your agent can query to learn the API before calling it. Each is callable over MCP and (where flagged) the REST/x402 HTTP API, webhooks, and the Telegram bot — see Channels.

◆ Trade Call get_trade_call

Returns a composite BUY/SELL/HOLD trade call with confidence percentage, regime context, and reasoning. The exchange parameter below lists every venue this tool accepts.

Parameters

Omit both timeframe and exchange and the router treats the call as bare: it infers the asset class from the symbol, then applies 15m on BINANCE for a perpetual. Naming either one routes to the perpetual engine explicitly.

Example Response

{
  "call": "BUY",
  "confidence": 78,
  "price": 84250.50,
  "indicators": {
    "funding_rate": 0.0001,
    "funding_24h_avg": 0.00008,
    "funding_state": "NORMAL",
    "oi_change_pct": 2.4,
    "volume_24h": 2381602633,
    "trend_persistence": "HIGH",
    "breakout_pending": "INACTIVE"
  },
  "regime": "TRENDING_UP",
  "reasoning": "Trending regime, upward bias. Funding pressure mild. Volatility neither expanding nor compressed. Trend persistence elevated; momentum structure. Strong conviction from aligned signals.",
  "timestamp": 1712764800,
  "coin": "BTC",
  "timeframe": "1h",
  "_algovault": {
    "version": "1.10.0",
    "tool": "get_trade_call",
    "compatible_with": ["crypto-quant-risk-mcp", "crypto-quant-backtest-mcp"]
  }
}

Response Fields

The example above is abridged. Every response carries these top-level fields.

_receipts — the audit trail

Ships on every get_trade_call response. It is what makes a verdict checkable rather than merely asserted: the ledger names each factor the engine weighed, which way it pointed, and whether it moved the result.

_algovault.auth — what happened to your key

Read this before anything else when a paid key seems not to apply. A key that was presented but not accepted still returns a verdict — on the free tier — so the response looks fine and the quota is wrong. This block says so explicitly, and replaces inferring it from the quota numbers.

The three served outcomes appear in _algovault.auth.outcome; the two refusing ones never do, because the call is refused before a verdict exists — look for them in error.data.auth_outcome instead. See Errors & troubleshooting.

◆ Market Regime get_market_regime

Classifies the current market regime for any asset, on any venue this tool accepts. Returns one of four states: TRENDING_UP, TRENDING_DOWN, RANGING, or VOLATILE.

Parameters

Example Response

{
  "regime": "TRENDING_UP",
  "confidence": 85,
  "metrics": {
    "adx_interpretation": "Strong trend",
    "volatility_interpretation": "Normal",
    "price_structure": "HIGHER_HIGHS",
    "trend_strength": "STRONG",
    "cross_venue_funding_sentiment": "BULLISH_BIAS",
    "funding_divergence_note": "HL funding 3.2x above CEX avg — longs concentrated on HL"
  },
  "suggestion": "Strong uptrend detected. Favor long positions with trend-following strategies.",
  "timestamp": 1712764800,
  "coin": "BTC",
  "timeframe": "4h",
  "_algovault": {
    "version": "1.10.0",
    "tool": "get_market_regime",
    "compatible_with": ["crypto-quant-risk-mcp", "crypto-quant-backtest-mcp"]
  }
}

Response Fields

Transcribed from a live response. The example above is abridged; every response carries these top-level fields.

◆ Funding Arbitrage scan_funding_arb

Scans cross-venue funding rate differences across 7 venues: Hyperliquid, Binance, Bybit, Gate, KuCoin, Aster, and OKX. Returns top arbitrage opportunities ranked by annualized spread, with a per-leg liquidity filter so only tradeable spreads surface.

Parameters

Example Response

{
  "opportunities": [
    {
      "coin": "ETH",
      "rates": {
        "HlPerp": 0.000125,
        "BinPerp": -0.000042,
        "BybitPerp": -0.000038
      },
      "bestArb": {
        "longVenue": "Binance",
        "shortVenue": "Hyperliquid",
        "spreadBps": 13.4,
        "annualizedPct": 117.3,
        "direction": "Long Binance / Short Hyperliquid"
      }
    }
  ],
  "scannedPairs": 245,
  "timestamp": 1712764800,
  "_algovault": {
    "version": "1.10.0",
    "tool": "scan_funding_arb",
    "compatible_with": ["crypto-quant-risk-mcp", "crypto-quant-execution-mcp"]
  }
}

Response Fields

Transcribed from a live response. The example above is abridged; every response carries these top-level fields.

◆ Trade Call Scanner scan_trade_calls

Scans a whole promoted-venue universe in one call and returns the top-ranked get_trade_call verdicts, ordered by a selectable lens (open interest, OI change, volume, momentum, …). One request instead of N per-asset calls — ideal for an agent building a watchlist or a scheduled digest.

Parameters

Ranking lenses

Every value rankBy accepts. Pass the lens or its alias — both resolve to the same universe.

Example

scan_trade_calls({
  topN: 20,
  timeframe: "1h",
  exchange: "BINANCE",
  rankBy: "oi",
  limit: 10
})
// → the 10 highest-ranked assets, each a get_trade_call verdict
//    (call, confidence, regime, price, indicators, _algovault)

Response Fields

The scan returns counters alongside the results, so you can tell “nothing qualified” from “nothing was scanned” without a second call.

{
  "scanned": 30,
  "eligible_non_hold": 1,
  "holds": 29,
  "errors": 0,
  "partial": false,
  "calls": [
    { "coin": "BTC", "timeframe": "1h", "exchange": "BINANCE",
      "call": "BUY", "confidence": 57, "regime": "TRENDING_UP" }
  ]
}

Each result carries the same shape as get_trade_call. A scan charges one unit per returned result, minimum 1. Quota is counted per call, regardless of verdict. x402 is a flat $0.02/scan.

◆ Knowledge Chat chat_knowledge

Ask AlgoVault a natural-language question — get a synthesized answer with citations, grounded in the canonical knowledge bundle (every MCP tool description, response shape, integration tutorial, and code example). Use this when you need an explanation, code pattern, or "how do I" answer. For raw ranked snippets without LLM synthesis, use search_knowledge (faster, no quota cost).

Parameters

Response Fields

Transcribed from a live response.

◆ Knowledge Search search_knowledge

Ask AlgoVault any question about its MCP tools, response shapes, integration patterns (LangChain / LlamaIndex / MAF / CrewAI), or code examples. Returns ranked snippets from the canonical knowledge bundle. Use this BEFORE attempting any tool call to confirm correct parameter usage and avoid hallucinating tool shapes. Fast (BM25 lexical search, no LLM call, no quota cost). For natural-language synthesized answers, use chat_knowledge instead.

Parameters

Response Fields

Transcribed from a live response.

◆ When to use which

◆ Worked examples

1. Discovery query — agent asks for trade-call docs before calling get_trade_call:

search_knowledge({
  query: "how do I get a trade call with stop loss for BTC"
})
// → ranked snippets including get_trade_call describe-text + integration excerpts

2. Comparison query — ask for synthesis across two tool descriptions:

chat_knowledge({
  question: "what's the difference between get_trade_call and get_market_regime"
})
// → synthesized answer with [source: ...] citations

3. Integration discovery — agent finds the LangChain tutorial:

search_knowledge({
  query: "how do I integrate with LangChain"
})
// → LangChain integration tutorial ranks first, with full code snippet

4. Direct HTTP — search:

curl -X POST https://api.algovault.com/api/search \
  -H "Content-Type: application/json" \
  -d '{"query":"BTC stop loss","limit":3}'

# → { "query": "BTC stop loss", "total_results": 3, "results": [...], "_algovault": {...} }

5. Direct HTTP — chat:

curl -X POST https://api.algovault.com/api/chat \
  -H "Content-Type: application/json" \
  -d '{"question":"how do I get a BTC trade call","model":"claude-haiku-4-5-20251001"}'

# → { "question": "...", "answer": "...", "citations": [...], "model": "...", "_algovault": {...} }

◆ Rate limits & cost

Cost transparency: chat_knowledge costs about $0.002 per call with prompt caching. Quota resets at the first of each UTC month.

◆ Errors & troubleshooting

Every failure this API can return, what it means, and what to change. Verified against the live server.

A venue outside the exchange list is a -32602, not an outage. The published list is the set with a live track record; venues without one are not accepted.

◆ Channels

Four ways to reach the same engine: the MCP server, the REST / x402 HTTP API, outbound webhooks, and the Telegram bot. Pick the surface that fits your stack — each links to a dedicated guide.

◆ MCP Server

Connect over the Model Context Protocol at https://api.algovault.com/mcp. Any MCP-compatible client (Claude Desktop, Cursor, Cline, Claude Code) handles the protocol for you. See Connect Your MCP Client for per-client setup. Wiring a non-MCP system? POST tools/call directly. The transport is stateless, so there is no initialize step and no session id to thread:

AV_KEY="av_live_..."   # paste your API key

curl -sS -X POST https://api.algovault.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer $AV_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_trade_call","arguments":{"coin":"BTC","timeframe":"15m","exchange":"BINANCE"}}}'

No key? Drop the Authorization header and the same call runs on the free tier.

Send both Accept types. The header must list application/json and text/event-stream. Sending only the first returns:

{"jsonrpc":"2.0","error":{"code":-32000,"message":"Not Acceptable: Client must accept both application/json and text/event-stream"},"id":null}

Parse twice. The reply is an SSE frame. The verdict is a JSON string nested at result.content[0].text. Strip the data: prefix, then decode the inner payload:

curl -sS -X POST https://api.algovault.com/mcp \
  -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_trade_call","arguments":{"coin":"BTC"}}}' \
  | sed -n 's/^data: //p' | head -1 | jq -r '.result.content[0].text' | jq

The same call in Python. Both parses in one place — the SSE frame, then the verdict string inside it. No MCP client library, no handshake, no session id.

import json, requests

r = requests.post(
    "https://api.algovault.com/mcp",
    headers={
        "Content-Type": "application/json",
        # both values, or the server answers 406
        "Accept": "application/json, text/event-stream",
        # optional — omit entirely to use the free tier
        # "Authorization": "Bearer av_live_...",
    },
    json={"jsonrpc": "2.0", "id": 1, "method": "tools/call",
          "params": {"name": "get_trade_call",
                     "arguments": {"coin": "BTC", "timeframe": "1h"}}},
    timeout=30,
)

# 1st parse — the reply is an SSE frame; the payload is the line after "data: "
envelope = json.loads(next(l[6:] for l in r.text.splitlines() if l.startswith("data: ")))

# failures arrive in TWO shapes — check both before reading a verdict
if "error" in envelope:
    raise SystemExit(envelope["error"])                      # -32003 / -32004
if envelope["result"].get("isError"):
    raise SystemExit(envelope["result"]["content"][0]["text"])  # -32602, as text

# 2nd parse — the verdict is a JSON *string* inside the tool result
verdict = json.loads(envelope["result"]["content"][0]["text"])

print(verdict["call"], verdict["confidence"], verdict["regime"])
print(verdict["_algovault"]["auth"])   # ABSENT / RESOLVED / MALFORMED

Optional: the full MCP session handshake. You do not need this to call a tool. It is kept for clients that speak full MCP session semantics. It also reproduces what an MCP client does internally:

AV_KEY="av_live_..."   # paste your API key

# 1. initialize — reads a session id from the response headers, if the server issues one
SESSION_ID=$(curl -sS -i -X POST https://api.algovault.com/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AV_KEY" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}},"id":1}' \
  | awk 'BEGIN{IGNORECASE=1} /^mcp-session-id:/ {gsub(/\r/,""); print $2; exit}')

# 2. notify "initialized"
curl -sS -X POST https://api.algovault.com/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AV_KEY" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: $SESSION_ID" \
  -d '{"jsonrpc":"2.0","method":"notifications/initialized"}' >/dev/null

# 3. call the tool
curl -sS -X POST https://api.algovault.com/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AV_KEY" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: $SESSION_ID" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"get_trade_call","arguments":{"coin":"SOL","timeframe":"5m","exchange":"BINANCE"}},"id":2}'

The stateless server issues no session id, so SESSION_ID stays empty and the header is ignored. Every call above still succeeds.

Full MCP Server guide →

◆ REST API

Two keyless / keyed HTTP rails for non-MCP consumers: x402 pay-per-call (USDC on Base, no signup) for autonomous agents, and plain API-key POST endpoints for the knowledge tools. Base URL https://api.algovault.com.

x402 Pay-Per-Call (USDC on Base)

No signup. No API key. No billing. Your agent pays per HTTP call with USDC on Base — the payment receipt is the credential. Works with any x402-compatible client or wallet.

How it works

Quick start (TypeScript)

The official x402-fetch client wraps fetch and runs the 402 → sign → retry handshake for you. Your wallet just needs USDC on Base.

// npm i x402-fetch viem
import { wrapFetchWithPayment } from "x402-fetch";
import { createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { base } from "viem/chains";

const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
const wallet  = createWalletClient({ account, chain: base, transport: http() });
const fetchWithPay = wrapFetchWithPayment(fetch, wallet);

// Pays automatically on the 402, then returns the verdict.
// content-type: set it EXACTLY once. x402-fetch wraps raw fetch, which would send a string
// body as text/plain — so here you must set it. Circle's GatewayClient.pay() is the opposite:
// it sets Content-Type itself, so passing your own merges into "application/json,
// application/json" and the server replies 400 invalid_content_type (you are not charged).
const res = await fetchWithPay("https://api.algovault.com/x402/get_trade_call", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ coin: "BTC", timeframe: "1h" }),
});

const verdict = await res.json();
console.log(verdict.call, verdict.confidence); // e.g. "BUY" 72

Endpoints & pricing

Base URL https://api.algovault.com.

New to x402? The open protocol spec and client libraries (x402-fetch, x402-axios) live at x402.org.

HTTP API (search & chat)

Both tools also expose plain HTTP endpoints for non-MCP consumers. Send a JSON body, read a JSON response — no JSON-RPC envelope, no dual Accept header, no SSE to unwrap.

Trade calls are served over POST /mcp and the /x402/* routes. There is no separate /api/trade-call endpoint.

Error contract: INVALID_QUERY / QUERY_TOO_SHORT / QUERY_TOO_LONG / INVALID_QUESTION / QUESTION_TOO_SHORT / QUESTION_TOO_LONG / INVALID_MODEL / CHAT_QUOTA_EXHAUSTED / INTERNAL_ERROR. All return JSON {"code": "...", "message": "..."}.

Full REST API guide →

◆ Webhooks

Stop polling. Register an HTTPS endpoint and AlgoVault POSTs you a signed event the instant a new trade call fires, the regime shifts, or a scheduled scan completes — every delivery is HMAC-signed, idempotent, and retried. Needs a free or paid av_live_ key (get one in your account).

Events

Subscribe

curl -X POST https://api.algovault.com/api/webhooks \
  -H "Authorization: Bearer av_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/hook",
    "events": ["trade_call", "regime_shift"],
    "timeframes": ["15m", "1h"],
    "assets": ["BTC", "ETH", "top:25"],
    "min_confidence": 60
  }'

Filters are optional — omit them to receive every call. assets accepts coin symbols or a top:N token (N 1–100); min_confidence is 0–100. For scan_digest add timeframe, exchange, top_n (1–100) and cadence (1h/4h/1d). The response includes a per-subscription secret — store it to verify signatures.

Manage

Delivery & signature

Each delivery is a POST to your URL with these headers:

{
  "event": "trade_call",
  "delivery_id": "d_8f3c...",
  "data": {
    "type": "trade_call",
    "coin": "BTC",
    "timeframe": "15m",
    "exchange": "BINANCE",
    "call": "BUY",
    "confidence": 72,
    "regime": "TRENDING_UP",
    "verify_url": "https://algovault.com/verify?id=..."
  }
}

Endpoint URLs must be HTTPS (SSRF-guarded; internal addresses are rejected). Full reference — payload schemas, retry/backoff, and self-healing — in docs/WEBHOOKS.md →

Full Webhooks guide →

◆ Telegram Bot

Trade calls delivered straight to Telegram — no client, no key. Start the bot, ask for a composite verdict in chat, or subscribe to push alerts for regime shifts and new calls. Free tier works out of the box.

Start @algovaultofficialbot on Telegram →

◆ Ecosystem

Drop AlgoVault into what you already run — MCP clients, agent frameworks, exchange execution kits, and hosted trading platforms — plus ready-made skills and 20 worked examples.

◆ Integration

Connect AlgoVault to your existing tools. Pick your surface below; each links to a step-by-step guide at /integrations.

◆ Connect Your Trading Platform

Feed AlgoVault calls into hosted crypto-bot and copy-trade platforms — e.g. Cryptohopper's signaler marketplace, 3Commas, and other signal-bot platforms — via the Webhooks channel or the platform's signal import. Your bot trades on AlgoVault's directional calls without you writing glue code.

See trading-platform integrations →

◆ Skills & Usage Examples

20 real-world workflows for AI agents and human developers. From simple one-liners to multi-agent orchestration.

◆ Track Record

◆ Live Dashboard

Every recorded BUY/SELL call is scored by PFE (Peak Favorable Excursion) win rate and broken down by asset, timeframe, and regime — updated live from the same on-chain-anchored record. No cherry-picking: the full call set is public.

Open the live track record →

◆ Verify

Every call is hashed and anchored on Base L2 via daily Merkle batches. This makes the track record tamper-proof.

How It Works

Verification Endpoints

GET /api/verify-signal?signalId=<ID>

GET /api/merkle-batches

Visual Verification

Visit algovault.com/verify to look up any call and see its on-chain proof in a human-readable format.

Contract Details

What This Proves

• ✓ Calls were recorded BEFORE outcomes were known
• ✓ No call can be retroactively edited or deleted
• ✓ The complete set of calls in each batch is locked — cherry-picking is detectable via sequential call IDs

◆ Pricing

Two payment rails: Stripe subscriptions for human developers, x402 micropayments (USDC on Base) for autonomous agents.

Subscription Tiers

Pro 6-month is currently $129 — limited-time pricing; subscribe now and renewals keep your price.

Quota is counted per call, regardless of verdict. The two meters are independent — a call is refused when either the monthly or the daily allowance is exhausted, and the daily one resets at 00:00 UTC.

What happens after you subscribe

◆ FAQ