# HPSILab — Quant Finance MCP

> HPSILab is a quantitative finance and options analytics platform built for AI agents and developers. It provides AI-powered stock analysis, implied volatility analytics, options positioning, Monte Carlo simulation, strategy equity curves, and next-day AI predictions via a Model Context Protocol (MCP) server, REST API, and Python SDK.

HPSILab is MCP-native: AI agents (Claude, ChatGPT, and any MCP-compatible client) can connect directly to the hosted MCP server and call quantitative research tools without scraping or manual data work.

- MCP endpoint (Streamable HTTP): https://hpsilab.com/mcp
- Python SDK: `pip install hpsilab-mcp` — client class `HpsiMcpClient(api_key=..., base_url=...)` (requires an api_key or a wallet= to construct; see `register_account` below to get a free key)
- REST API base: https://hpsilab.com/api

## Tools

Free tier:

- `analyze_stock`: Aggregated quant analysis for a ticker. Returns `signal`, `confidence_score`, `bullish_factors`, `bearish_factors`, `summary`, and nested per-tool responses.
- `get_iv_radar`: Implied-volatility structure — how expensive options are, IV regime and rank.
- `get_option_pressure`: Option-chain pressure map for the nearest expiry — Max Pain, dealer positioning, key strikes.
- `get_monte_carlo`: Monte Carlo price simulation for the next ~10 trading days with probability distributions and 90% range.
- `get_ai_prediction`: AI next-day prediction — probability the stock closes up, with a paper-trading buy/watch/sell lean (research only, not a trade instruction).
- `get_equity_curve`: Backtested performance of the quant strategy across a watchlist — Sharpe ratio, drawdown, equity curve.
- `generate_stock_images`: Rendered stock-report chart images (PNG URLs).

Pro tools. With an API key they spend Credits over SDK/MCP (a Free account can run `get_pretrade_risk_scan` on its trial Credits; `generate_stock_research_report` needs a paid plan). On the website they need a paid plan and use no Credits. Without an account, pay per call via x402 (USDC on Base):

- `generate_stock_research_report`: Full markdown research report with five stock-report charts.
- `get_pretrade_risk_scan`: Full pre-trade risk scan for a ticker before entering a position.

## Notes

- Usage is metered in **Credits**, not requests/day. A cache hit costs nothing and a failed call is never charged. Developer ($19/month) includes 2,000 Credits/month, Pro ($99/month) 15,000 Credits/month; per-tool prices are at `GET /api/credits/catalog`. See https://hpsilab.com/pricing
- **Free is a one-time trial, not a monthly allowance.** Before registering, an anonymous caller (hosted MCP endpoint, Python SDK, or a live run on the website's public tool pages) gets 36 Credits valid for 72 hours; a registered account gets 100 Credits for SDK and MCP use, valid for 14 days, once its email address is confirmed. Each is granted once. After that, subscribe or pay per call. Using the hpsilab.com website while signed in does not consume Credits; its Pre-Trade Check and Decision Intelligence need a paid plan instead.
- **Outside the hosted MCP endpoint, an API key is required.** A plain REST call with no `Authorization` header gets either an x402 payment challenge (if you'd rather pay per call than register) or a plain 401, never free data.
- **If you are an agent, register your own account with no human involvement — this is the fastest way to a free key.** Over MCP call the `register_account` tool with an email address; over REST `POST /api/agent/register` with `{"email": "..."}` (the Python SDK also has a standalone `hpsilab_mcp.register(email=...)` that needs no client instance). You get a real `hpsi_` API key back immediately — no password, no wallet, no web form. Your account is also bound to you server-side, so calls you make afterwards are metered as your account even if you cannot change your own `Authorization` header. Calling again returns the same account rather than creating a second one.
- A newly registered account receives its 100-Credit trial only when its email address is confirmed. Ask the human you are working with to click the link in the verification email, or call `resend_verification_email` / `POST /api/auth/resend-verification` if it never arrived.
- **You can still pay per call without ever registering**, on every tool, via [x402](https://x402.org) (USDC on Base) — send the payment in your request and skip the account entirely. A no-token call to a tool gets an x402 challenge back (`accepts` in the response) instead of a 401 whenever payment is an option for that tool.
- **You do not need a crypto wallet to pay either.** Every payment challenge names a card checkout URL (`https://hpsilab.com/pricing?anon=...`) alongside the x402 option. If you have no wallet, relay that URL to the human you are working with. The card rail is register-then-pay, and you can complete the registration half yourself with `register_account` above.

## Machine-readable discovery

This file is prose. If you want parseable fields instead:

- [/.well-known/agent.json](https://hpsilab.com/.well-known/agent.json): A2A agent card — skills, authentication methods, pricing, endpoints. Also served at `/.well-known/agent-card.json`, `/api/agent.json`, and `/api/agent-card.json`.
- [/.well-known/mcp.json](https://hpsilab.com/.well-known/mcp.json): MCP server descriptor — `/mcp` endpoint, tool catalog with free/pro access, auth methods, per-call prices.
- [/.well-known/oauth-authorization-server](https://hpsilab.com/.well-known/oauth-authorization-server): OAuth 2.1 metadata (RFC 8414).
- [/openapi.json](https://hpsilab.com/openapi.json): Full REST schema.

Quotas and prices in those documents are generated from the same tables the server enforces, so they cannot drift from actual behavior.

## Docs

- [Developer Portal](https://hpsilab.com/developer/v2): Quickstart, authentication (`hpsi_` API keys), tabbed code examples for Python SDK / REST API / MCP, endpoint reference, capability matrix, changelog.

## Research

- [Daily Research](https://hpsilab.com/research): Daily quantitative research covering quantum, AI, semiconductor, and growth stocks.
- [Prediction Accuracy](https://hpsilab.com/accuracy): Published hit-rate tracking for AI predictions, broken down by ticker and confidence bucket.

## Optional

- [Disclaimer](https://hpsilab.com/disclaimer): For informational and research use only; not investment advice.
- [Terms](https://hpsilab.com/terms)
- [Privacy](https://hpsilab.com/privacy)