# x402 Derivatives Analytics Desk

> Pay-per-call European option pricing, analytic Greeks, IV surfaces, and multi-leg book risk for power, commodity, equity, and crypto agents. Settle **USDC** via HTTP 402 (x402 exact) on **Solana + Base** — no API keys.

## What this service does (English)

Production x402 quant API for autonomous trading and risk agents. Price European options with full analytic Greeks; invert market premiums to implied vol (single quote or multi-maturity surface); price and revalue books on a submitted IV smile (total-variance bilinear in log-moneyness); aggregate multi-leg net Greeks; reprice books under spot/vol/time scenarios. Designed for power and energy desks (forward marks that differ by maturity), commodities, equities, and crypto — no API keys, USDC exact settlement via HTTP 402 on configured networks (see GET /v1/capabilities). Free fixed demo at /v1/demo/option-price; MCP tools at /mcp and /api/mcp; paid HTTP routes remain the source of truth.

## When to use

European or American options on a listed window or forward (power / commodity / equity), when you already have S or the maturity mark, K, times, r, and σ or a premium; you need fair value + Greeks or IV / surface — not a live market-data feed.

## When not to use

You need market data or realized window volatility from a market data feed; you do not already have model inputs; you want a generic ticker screener or "price any stock."

## Capability summary

- Single-contract Black-Scholes-Merton fair value + delta/gamma/vega/theta/rho
- Implied vol from one premium (fast) or a full strike×maturity surface (book)
- Price / scenario on a submitted IV surface (TV bilinear in k,T; flat_vol wings)
- Per-row underlyings so power/commodity forwards can differ by maturity
- Multi-leg portfolio net Greeks, MTM, optional dollar Greeks, scenario reprice
- x402 USDC exact on Solana mainnet and Base mainnet; free fixed demo for discovery
- MCP façade: one tool per paid HTTP route (same services + USDC prices)

- **Version:** 1.6.0
- **Protocol:** x402 (exact scheme, USDC)
- **Networks:** solana, base (`solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp, eip155:8453`)
- **Facilitator:** https://facilitator.payai.network
- **Markets:** power_and_energy, commodities, equities, crypto, fx_style_european

## Price list (USDC exact)

| Path | Price | Purpose |
|------|-------|---------|
| POST /v1/option/price | $0.01 | European option fair value and analytic Greeks |
| POST /v1/option/implied-vol | $0.03 | Implied volatility from a single market premium |
| POST /v1/volatility/surface | $0.10 | Implied-vol grid from a market option book |
| POST /v1/option/price-from-surface | $0.08 | Price options on a submitted IV surface |
| POST /v1/option/scenario-from-surface | $0.15 | Sticky smile book reval under surface shocks |
| POST /v1/portfolio/greeks | $0.15 | Net MTM and Greeks for a multi-leg option book |
| POST /v1/portfolio/scenario | $0.25 | Scenario P&L for a scalar-σ option book |
| GET/POST /v1/demo/option-price | free | Fixed ATM sample (discovery seeding) |

## Paid endpoint links

- [POST /v1/option/price](https://derivatives-pricer-production.up.railway.app/v1/option/price) — **$0.01**
- [POST /v1/option/implied-vol](https://derivatives-pricer-production.up.railway.app/v1/option/implied-vol) — **$0.03**
- [POST /v1/volatility/surface](https://derivatives-pricer-production.up.railway.app/v1/volatility/surface) — **$0.10**
- [POST /v1/option/price-from-surface](https://derivatives-pricer-production.up.railway.app/v1/option/price-from-surface) — **$0.08**
- [POST /v1/option/scenario-from-surface](https://derivatives-pricer-production.up.railway.app/v1/option/scenario-from-surface) — **$0.15**
- [POST /v1/portfolio/greeks](https://derivatives-pricer-production.up.railway.app/v1/portfolio/greeks) — **$0.15**
- [POST /v1/portfolio/scenario](https://derivatives-pricer-production.up.railway.app/v1/portfolio/scenario) — **$0.25**

Unpaid paid-path calls return **HTTP 402** with `PAYMENT-REQUIRED` (base64). Pay on **any** listed network.

## Free discovery

- [Service card (JSON)](https://derivatives-pricer-production.up.railway.app/)
- [Capabilities matrix](https://derivatives-pricer-production.up.railway.app/v1/capabilities) — models, greek units, caps, networks, prices
- [Health](https://derivatives-pricer-production.up.railway.app/health)
- [OpenAPI](https://derivatives-pricer-production.up.railway.app/openapi.json)
- [Swagger alias](https://derivatives-pricer-production.up.railway.app/swagger.json) — same as OpenAPI
- [Skill](https://derivatives-pricer-production.up.railway.app/skill.md) · [SKILL.md](https://derivatives-pricer-production.up.railway.app/SKILL.md)
- [x402 well-known](https://derivatives-pricer-production.up.railway.app/.well-known/x402.json)
- [Agent card](https://derivatives-pricer-production.up.railway.app/.well-known/agent.json)
- [A2A agent card](https://derivatives-pricer-production.up.railway.app/.well-known/agent-card.json) — alias of agent.json
- [llms.txt](https://derivatives-pricer-production.up.railway.app/llms.txt) — this file
- [Free demo option price](https://derivatives-pricer-production.up.railway.app/v1/demo/option-price) — fixed ATM BSM sample
- [MCP Streamable HTTP](https://derivatives-pricer-production.up.railway.app/mcp) — alias `/api/mcp`. Tools: `health` and `service_info` (free, `paymentStatus=free`), `price_option`, `implied_vol`, `implied_vol_surface`, `price_from_surface`, `scenario_from_surface`, `portfolio_greeks`, `portfolio_scenario` (paid).
- **MCP GET:** JSON discovery document (`name`, `version`, `transport` `streamable-http`, `url`, `methods`, `accept`) when Accept is omitted or includes `*/*`, `application/json`, or `text/event-stream`.
- **MCP POST:** JSON-RPC. Returns `application/json` when the client accepts it.
- **MCP Accept (required on POST):** `Accept: application/json, text/event-stream` on every `POST /mcp` and `POST /api/mcp` (missing → HTTP 406).
- **MCP server card:** [/.well-known/mcp/server-card.json](https://derivatives-pricer-production.up.railway.app/.well-known/mcp/server-card.json) — transport kind `streamable-http`, tools, x402 prices.
- **MCP initialize curl:** `curl -sS -X POST 'https://derivatives-pricer-production.up.railway.app/mcp' -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl","version":"1.0.0"}}}'`

## When to call which route

- **POST /v1/option/price**: Known S/K/T/r/σ (power forward as S OK) → price + Greeks. Prefer over surface when not inverting premiums.
- **POST /v1/option/implied-vol**: One premium to mark or hedge → σ̂ + Greeks. Use /v1/volatility/surface for books and multi-maturity grids.
- **POST /v1/volatility/surface**: Multi-quote book → IV surface. Then optionally price-from-surface / scenario-from-surface.
- **POST /v1/option/price-from-surface**: Have a smile/surface grid and want European prices + Greeks at interpolated σ. Use scalar /v1/option/price if you already know one σ.
- **POST /v1/option/scenario-from-surface**: Need base vs scenario MTM on a smile with sticky conventions. Use price-from-surface for static pricing only.
- **POST /v1/portfolio/greeks**: Aggregate delta/gamma/vega/theta/rho across a multi-leg scalar-σ book. Use scenario for shocked MTM.
- **POST /v1/portfolio/scenario**: Need shocked MTM and Greeks (spotShock, volShock, timeDecayDays). Use portfolio/greeks for base risk only.

## How agents should pay

1. Discover via this file, `GET /`, or `GET /.well-known/x402.json`.
2. Optional: hit free demo to validate JSON shape without a wallet.
3. `POST` paid path unpaid → parse `PAYMENT-REQUIRED` accepts (any listed network: Solana + Base).
4. Settle USDC; retry with payment proof. Optional `Idempotency-Key`.
5. MCP hosts: connect to the MCP URL; paid tools may require USDC the same way.

## Notes

- Model: European Black-Scholes-Merton with continuous dividend/convenience yield.
- Greeks: raw analytic derivatives (not per-1% / per-day desk scalings).
- No accounts, no API keys — public payTo only on the server.