# VecViz for agents

VecViz publishes a quantitative equity model as tools an agent can call: forecast targets and the events that build them, price-probability bands, correlation by three methods, model portfolios, risk history and a published track record. Every number comes back computed, carrying the model date it describes, so you can render it rather than estimate it.

Outputs are quantitative research, not forecasts or investment advice.

## 1. Get a key

No email, no signup, no card:

```
curl -sX POST https://agents-vecviz.fly.dev/connect
```

The response carries the key and everything needed to use it: `api_key`, `expires_at`, `monthly_units`, the `tickers` it covers, an `mcp` block with the URL and auth header, a `rest` block, and `upgrade` for when the scope runs out. **The key is shown once** -- only its hash is stored, so save it on receipt.

## 2. Connect over MCP

```json
{
  "mcpServers": {
    "vecviz": {
      "url": "https://agents-vecviz.fly.dev/mcp",
      "headers": { "Authorization": "Bearer vv_..." }
    }
  }
}
```

If your gateway forwards header values verbatim and cannot prepend `Bearer `, send the bare key in `X-VecViz-Key` instead. Both reach the same check.

## 3. Or call REST

Base URL `https://agents-vecviz.fly.dev`, same bearer key. Start at `GET /v1/usage` -- it reports your tier, what you have spent, and the rate card it bills from. Full schema at https://agents-vecviz.fly.dev/openapi.json, browsable at https://agents-vecviz.fly.dev/docs.

Every response is one envelope: `data`, plus `meta` carrying `as_of` (the model date the answer describes), `units` and `units_basis` (what the call cost, and the arithmetic behind it).

## What a free key covers

* **10 tickers**: AAPL, GLD, JPM, MRK, MSFT, SPY, TLT, TSLA, WMT, XOM.
* **200 units a month**, and the key expires after 14 days.
* **Every tool.** Nothing is withheld by feature -- the limit is which tickers you may ask about, so what you evaluate is the real product.

## What subscribing adds

* **788 tickers** instead of 10.
* **50,000 units a month**.
* **The OpenBB Workspace app** on the same key: the same model as interactive widgets rather than tool calls.

$39/month, cancel anytime: https://vecviz.com/signup

## Tools (22)

Cost is the rule an ordinary single-ticker call fires. A sector, the whole universe or a portfolio price on the ladder below.

| Tool | Cost | What it answers |
| --- | --- | --- |
| `correlate` | 1 per ticker | Pairwise correlations among 2-40 tickers. 'pearson' is ordinary trailing 252-day return correlation and is what most callers mean; 'vecevent'... |
| `diversifiers` | 10 per call | Top-ranked tickers that would most DIVERSIFY an exposure to a given one -- the call for 'what should I own alongside NVDA'. Two stages: it correlates... |
| `methodology` | free | What a VecViz number means and how it is derived. FREE. Read this before presenting a figure to a user; 'citation' is a one-line attribution safe to... |
| `metric_context` | 1 per ticker | WHY a ticker's number is what it is -- the call for 'how could NVDA's 99D be -45%' or 'why is SPY's EUB so narrow'. Resolves the metric, horizon and... |
| `metric_history` | 1 per ticker | How one VV-Data-Table metric has MOVED OVER TIME -- the call for 'chart SPY's V-Score', 'has NVDA's upside bound been widening', 'show me semis vs... |
| `model_review` | 1 per ticker | How VecViz actually performed -- the published track record, one section at a time. Realized 99% bound breaks by ticker, breakage rates, average... |
| `option_fair_value` | 1 per ticker | What VecViz thinks an option is worth, from the PPF band structure. There is no market implied-volatility source here, so it CANNOT say whether an... |
| `portfolio` | 1 per holding, min 25 | Analyse a portfolio you supply, or look up VecViz model portfolios by strategy, max weight and target volatility. 'optimize' is a LOOKUP over... |
| `ppf` | 1 per ticker | Price-probability forecast bands by horizon, and optionally the date each band reaches a target price. Ten bands at six horizons. Pass target_price... |
| `price_likelihood` | 1 per ticker | What VecViz says about the likelihood of a PRICE for a ticker -- the one call for 'could NVDA reach 250' or 'what would take SPY to 600'. Five... |
| `report_feedback` | free | Report a wrong number, a confusing response, or a missing capability. FREE. Use this when a VecViz answer looks incorrect rather than silently... |
| `risk_history` | 1 per ticker | How a ticker's downside and upside bounds have moved over time, plus where the current value sits in its own history -- so you can say 'this is the... |
| `usage` | free | The caller's tier, quota consumed, quota remaining, period reset, and the published rate card. FREE. |
| `vecevent_matrix` | 1 per ticker | WHY a ticker's VNA target price is what it is: the contribution of each VecEvent across each Vector Set. Read-only and recomputes nothing. Costs 1... |
| `vecevent_matrix_reviewed` | 1 per ticker | COMPOSE several VecEvent changes at once and get the whole reviewed picture back. vna_scenario prices ONE change against the untouched baseline and... |
| `vector_set_anchors` | 1 per ticker | The historical tops and bottoms each Vector Set is drawn over: date, price, and whether each was a top or a bottom, in chronological order. This is... |
| `vecviz_catalog` | 1 per ticker | What you can ask about: tickers, sectors, industries, per-dataset coverage, and the precomputed portfolio variants. FREE. Call this before naming... |
| `vecviz_filter` | 10 per call | Which names clear SEVERAL thresholds AT ONCE -- the call for 'run the bullish screen'. Not the same question as vecviz_universe, which ranks the... |
| `vecviz_read` | 1 per ticker | Everything known about ONE ticker: VNA target price, channels, VecEvents, V-Score, and a digest of which price-probability bands exist. START HERE... |
| `vecviz_report` | 1 per call | Is a value unusual -- for THIS name, or for the market? Eight VV Data Table metrics (V-Score, VNA Ret, EUB/95U/99U, EDB/95D/99D), each with its... |
| `vecviz_universe` | 1 per ticker | Screen or batch-read the whole universe at the latest model date. TWO uses. (1) DISCOVERY: rank every ticker on one metric to find candidates. (2)... |
| `vna_scenario` | 1 per ticker | What a ticker's VNA target price becomes under a different VecEvent picture -- either RE-CHARACTERISE an event it already has (a new bias... |

## What a call costs

A unit is one ticker's analytics at one model date.

| Rule | Units |
| --- | --- |
| tickers | 1 per ticker named. |
| sector | 10. Flat, however many names the sector holds. |
| industry | 10. Priced the same as a sector. |
| universe | 500. A whole-universe pull costs less than naming every ticker individually. This is the volume discount. |
| model_portfolio | 25. |
| own_portfolio | 1 per holding, minimum 25. |
| free | 0. |

Every rule reads only the request, so the cost of a call is known before it is made. meta.units reports what was charged and meta.units_basis shows the arithmetic.

Never billed: requests refused for an unknown ticker (400); any other 4xx -- a rejected request delivered no analytics; server errors (5xx).

## When a call is refused

| Status | Code | What to do |
| --- | --- | --- |
| 401 | `unauthorized` | No usable key. The body says where to get one. |
| 403 | `ticker_out_of_scope` | The ticker is real but outside your plan. The message names what the plan does cover. |
| 403 | `mode_not_in_plan` | The call needs the whole universe -- a model portfolio, or the all-ticker average. |
| 404 | `ticker_not_found` | Not covered at the current model date. Re-read `vecviz_catalog`, or pass `skip_unknown=true`. |
| 429 | `rate_limited` | Burst brake. Honour `Retry-After`. |
| 429 | `quota_exceeded` | Monthly allowance spent. `reset_at` says when it returns. |

None of these are billed: a refused request delivered no analytics.

## Also here

* MCP server card, tools and schemas, no key needed: https://agents-vecviz.fly.dev/.well-known/mcp/server-card.json
* This page as HTML: https://agents-vecviz.fly.dev/agents
* The human sign-up path: https://agents-vecviz.fly.dev/try
* Public demo dashboards, no key: https://app.vecviz.com/dashboards/demo/