EVIO API Documentation.

Introduction #

EVIO API is a regulated, MCP-native financial-data platform built for two audiences at once:

1. Autonomous AI agents that discover, choose, call, and recover from EVIO endpoints without a human ever rendering a webpage.
2. The humans who configure, govern, debug, and pay for those agents.

Where existing financial-data APIs ship raw bytes to a single human developer building a single application, EVIO ships ranked, decision-shaped outputs with reasoning traces, citations, and confidence scores — and treats agents as first-class entities with their own keys, budgets, and audit trails.

Quick start #

1. Get an API key at app.evioinc.com/sign-up?invite=alpha. Test keys are prefixed evk_test_* and bypass billing while still logging usage.
2. Make a request:

curl -H "Authorization: Bearer evk_test_..." \
  "https://api.evioinc.com/v1/options/unusual?ticker=XNAS:AAPL&lookback=30d&limit=5"

You'll get back JSON with results, _reasoning, _citations, _confidence, _links, and _meta. See response envelope below for the full shape.

Authentication #

API surface uses Bearer API keys, exclusively. OAuth is available for the human-facing dashboard at app.evioinc.com only — never on the API surface itself.

Header

Authorization: Bearer evk_test_xxxxxxxxxxxxxxxxxxxxxxxx

Per-agent keys

Per-agent keys are strongly recommended over org-wide keys. Each agent gets:

• Its own monthly call cap
• Its own budget cap (in cents)
• Its own audit trail
• Its own pause / revoke kill switch (1-second propagation guarantee)

Manage agents at app.evioinc.com/agents.

Rotation, hashing, and revocation

• API keys are SHA-256 hashed at rest. Plaintext is shown once at creation. Copy it immediately.
• The Rotate button generates a new key and marks the old one as revoking with a 24-hour grace period before deletion.
• Pausing an agent revokes all its keys with 1-second propagation across all api.evioinc.com edges.

Response envelope #

Every successful (2xx) response carries the same five fields, plus the actual results:

{
  "results": [ /* endpoint-specific payload */ ],
  "_reasoning":   ["sentence 1.", "sentence 2."],
  "_citations":   [{ "step": 0, "source": "...", "locator": "..." }],
  "_confidence":  { "score": 0.87, "label": "high", "factors": ["..."] },
  "_links":       [{ "id": "XNAS:AAPL", "endpoints": ["..."] }],
  "_meta": {
    "request_id": "req_01HXY...",
    "latency_ms": 142,
    "data_freshness": "mock",
    "tokens_estimated": 318,
    "version": "v1"
  }
}

Opt-in fields

Pass ?include=alternatives,counterfactual,suggestions to add:

These are off by default — they cost tokens, and you should only pay for them when you can route on them.

data_freshness

The transition mock → shadow → live is a single env-var flip on the server. Field names, types, and the envelope are stable. Customer code never changes.

The _meta.tokens_estimated field reports cost computed against tiktoken o200k_base so agents can budget — no competitor publishes this.

Error envelope #

400 Bad Request tells an agent nothing and a human almost nothing. EVIO makes every error machine-actionable AND human-readable.

{
  "error": {
    "code": "invalid_ticker_format",
    "message": "Field 'ticker' must be in MIC:SYMBOL format. Received 'apple'. Try 'XNAS:AAPL'.",
    "recoverable": true,
    "retry_after_ms": null,
    "docs_url": "https://evioinc.com/api/docs/#errors",
    "request_id": "req_01HXY...",
    "hints": [
      { "field": "ticker", "action": "transform", "suggestion": "XNAS:AAPL" }
    ]
  }
}

Catalog

Stability promise

• Error codes never change meaning.
• New codes are added; old codes are not repurposed.
• Codes are namespaced: invalid_*, rate_limit_*, agent_budget_*, data_*.

Conventions #

Pagination & rate limits #

Pagination

List endpoints support cursor-based pagination:

?cursor=opaque_string&limit=50

• limit default 50, max 200.
• cursor is opaque — do not parse it. Pass it back exactly as received.
• Next-page cursor returned in _meta.next_cursor (null when exhausted).

Rate limits

Per-agent overrides configurable from /agents/[id]. Headers on every response:

X-RateLimit-Limit:     60
X-RateLimit-Remaining: 58
X-RateLimit-Reset:     45    # seconds until the bucket fully refills
X-Request-Id:          req_01HXY...

When exhausted, the server returns 429 with the standard error envelope and retry_after_ms populated. Respect that value rather than guessing.

Field selection #

Every endpoint accepts a fields query parameter and a verbose flag.

The ?include= query parameter is separate — it adds the opt-in envelope fields _alternatives, _counterfactual, _suggestions.

Options — unusual flow #

curl -H "Authorization: Bearer $EVIO_KEY" \
  "https://api.evioinc.com/v1/options/unusual?ticker=XNAS:AAPL&lookback=30d&limit=5"

Factor — multi-factor score #

{
  "tickers": ["XNAS:AAPL", "XNAS:MSFT"],
  "factors": ["value", "momentum", "quality", "low_vol", "size"],
  "as_of":   "2026-05-01"
}

Backtest — strategy run #

{
  "name":     "60-40 monthly rebalance",
  "universe": ["XNAS:AAPL", "..."],
  "rules":    { },
  "start":    "2020-01-01",
  "end":      "2025-12-31",
  "mode":     "sync"
}

Equity — research package #

curl -H "Authorization: Bearer $EVIO_KEY" \
  "https://api.evioinc.com/v1/equity/research?ticker=XNAS:AAPL&horizon=12m"

Regime — macro classification #

curl -H "Authorization: Bearer $EVIO_KEY" \
  "https://api.evioinc.com/v1/regime/classify?region=us&history=30"

News — sentiment vs. baseline #

curl -H "Authorization: Bearer $EVIO_KEY" \
  "https://api.evioinc.com/v1/news/sentiment?ticker=XNAS:AAPL&window=7d"

SEC — filing structured summary #

curl -H "Authorization: Bearer $EVIO_KEY" \
  "https://api.evioinc.com/v1/sec/filing?accession_number=0000320193-25-000001&diff=true"

Portfolio — VaR, ES, factor exposure #

curl -X POST -H "Authorization: Bearer $EVIO_KEY" \
     -H "Content-Type: application/json" \
     -d '{"positions":[{"ticker":"XNAS:AAPL","weight":0.3,"qty":100}],"horizon_days":10,"confidence":0.95}' \
     https://api.evioinc.com/v1/portfolio/risk

MCP server #

The same eight endpoints are also exposed as a first-class MCP server at https://api.evioinc.com/mcp across all three current MCP transports:

• stdio — Claude Desktop, Cursor, local agents
• http+sse — legacy cloud agents
• streamable-http — modern hosted-agent default (per November 2024 spec)

Discovery via https://api.evioinc.com/.well-known/mcp returns the server URL, transport list, auth method, and capability summary in JSON.

Tool description discipline

EVIO's MCP tool descriptions are prompts, not docs. Each follows the same template (imperative · when to use · when NOT to use with the alternative tool name · distinguishing features · concrete example, all under ~600 tokens). The "when NOT to use" pattern is the agent-visibility lever — frontier LLMs see all enabled tool descriptions on every call, so giving them disambiguation hints raises tool-pick accuracy.

Claude Desktop #

Drop into ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "evio": {
      "url": "https://api.evioinc.com/mcp",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Bearer evk_test_REPLACE_ME"
      }
    }
  }
}

Restart Claude Desktop. EVIO's nine tools (eight endpoints + the async backtest variant) appear in the tool picker.

Cursor #

Drop into ~/.cursor/mcp.json:

{
  "mcpServers": {
    "evio": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-fetch", "https://api.evioinc.com/mcp"],
      "env": { "AUTHORIZATION": "Bearer evk_test_REPLACE_ME" }
    }
  }
}

LangChain (Python) #

import os
os.environ["EVIO_API_KEY"] = "evk_test_..."

# Pull the wrapper from github.com/JpDeSilva17/evio-schemas
from langchain_tools import EVIO_TOOLS

from langchain.agents import create_react_agent
from langchain_anthropic import ChatAnthropic

agent = create_react_agent(
    ChatAnthropic(model="claude-sonnet-4-6"),
    tools=EVIO_TOOLS,
)
result = agent.invoke({"input": "What's the unusual options activity in AAPL today?"})

CrewAI (Python) #

import os
os.environ["EVIO_API_KEY"] = "evk_test_..."

from crewai_tools import EVIO_TOOLS
from crewai import Agent, Crew, Task

analyst = Agent(role="Quant analyst", goal="...", tools=EVIO_TOOLS)
crew = Crew(agents=[analyst], tasks=[Task(description="...")])
crew.kickoff()

Anthropic SDK (tool use) #

import anthropic, json
client = anthropic.Anthropic()

with open("anthropic-tools.json") as f:
    tools = json.load(f)

resp = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    tools=tools,
    messages=[{"role": "user", "content": "What's the macro regime?"}],
)

Anthropic returns tool_use blocks; you make the HTTPS call to api.evioinc.com with the user's evk_test_* key in the Authorization header, then send the result back as a tool_result.

OpenAI Agents SDK / function calling #

from openai import OpenAI
import json
client = OpenAI()

with open("openai-functions.json") as f:
    tools = json.load(f)

resp = client.chat.completions.create(
    model="gpt-5",
    messages=[{"role": "user", "content": "Find unusual options on AAPL."}],
    tools=tools,
)

Vercel AI SDK / Mastra / Voltagent (TypeScript) #

import { tool } from "ai";
import { z } from "zod";

export const evioOptionsUnusual = tool({
  description: "Top N tickers with unusual options activity over a lookback window.",
  parameters: z.object({
    ticker:   z.string(),
    lookback: z.enum(["7d", "14d", "30d", "60d", "90d"]).default("30d"),
    limit:    z.number().int().min(1).max(50).default(5),
  }),
  execute: async ({ ticker, lookback, limit }) => {
    const r = await fetch(
      `https://api.evioinc.com/v1/options/unusual?ticker=${ticker}&lookback=${lookback}&limit=${limit}`,
      { headers: { Authorization: `Bearer ${process.env.EVIO_API_KEY}` } },
    );
    return r.json();
  },
});

Definitions for the other seven endpoints follow the same pattern. A generated TypeScript module is on the v1.1 roadmap.

Webhook events #

Webhook delivery #

• Auth: HMAC-SHA256 signature in X-Evio-Signature header. Verify before processing.
• Retries: exponential backoff up to 24 hours, then dead-lettered.
• Idempotency: every event has a UUID; customers should dedupe.
• Replay: from app.evioinc.com/settings/webhooks, last 100 events kept.

Verifying the signature

# Python
import hmac, hashlib
def verify(secret: str, body: bytes, signature: str) -> bool:
    expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

// TypeScript
import crypto from "node:crypto";
export function verify(secret: string, body: string, sig: string): boolean {
  const expected = crypto.createHmac("sha256", secret).update(body).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig));
}

Discovery surfaces #

Both human and machine. Both must work.

Machine surfaces (agent first contact)

Public schemas repo #

The OpenAPI 3.1 spec and per-framework tool wrappers are mirrored to a separate, public, MIT-licensed repo:

github.com/JpDeSilva17/evio-schemas

It contains:

• v1.yaml — OpenAPI 3.1 spec
• frameworks/anthropic-tools.json
• frameworks/openai-functions.json
• frameworks/langchain_tools.py
• frameworks/crewai_tools.py
• frameworks/mcp-manifest.json
• examples/claude-desktop.json, examples/cursor.json
• CHANGELOG.md — SemVer + min 90-day deprecation timelines

Every breaking change ships with at least 90 days of deprecation notice via the Deprecation and Sunset HTTP headers on the live API and a ## Deprecated section in the schemas CHANGELOG.md.

Status & support #