# falcon.sol structures

> Structured-note pricing API for crypto, built for agents and desks. Price autocallables, barrier reverse convertibles, range accruals, principal-protected notes and shark fins on BTC, ETH and SOL. Monte Carlo (risk-neutral GBM, daily monitoring, antithetic, common-random-number greeks) on live Deribit implied vol (DVOL) and exchange spot. Paid per call with x402 v2: $0.02 USDC on Solana or Base. No account, no key.

## Endpoints
- POST https://falcon-structures.vercel.app/v1/preview (free): fair coupon/participation rounded down to 0.5%, probabilities, payoff diagram.
- POST https://falcon-structures.vercel.app/v1/quote ($0.02, x402): exact fair term with Monte Carlo std error, PV decomposition (PV = A + term*B), autocall/coupon probability per observation date, knock-in/knock-out/loss probabilities, expected life, delta/gamma/vega/rho/theta, 5x3 spot x vol scenario grid in USD, payoff diagram, USD cash flows. Malformed term sheets return 400 before payment.
- GET https://falcon-structures.vercel.app/v1/market/{BTC|ETH|SOL} (free): spot, implied vol, realized vol, rate used.
- MCP (streamable HTTP): https://falcon-structures.vercel.app/mcp - tools preview_note (free), market_snapshot (free), price_note (paid via x402-in-MCP).

## Term sheet
JSON Schema: https://falcon-structures.vercel.app/schema/term-sheet.json. Levels are fractions of strike-date spot (0.7 = 70%). Leave the free term (couponPerPeriod / couponPa / participation) empty to solve for it; set it to get PV and implied margin instead. issuerMarginBpsPa (default 200) sets target PV = 1 - margin x tenor.
Products: autocallable{tenorDays, obsFreqDays, autocallBarrier, couponBarrier, knockInBarrier, memory, nonCallDays}; reverse_convertible{tenorDays, knockInBarrier, strike}; range_accrual{tenorDays, rangeLow, rangeHigh, protection}; principal_protected{tenorDays, protection, strike, cap}; shark_fin{tenorDays, protection, strike, knockOutBarrier, rebate}.
Override market with market:{spot, vol, rate}. Max 730 days, 60k paths.

Example: {"underlying":"ETH","notionalUsd":10000,"issuerMarginBpsPa":200,"product":{"type":"autocallable","tenorDays":30,"obsFreqDays":7,"autocallBarrier":1,"couponBarrier":0.8,"knockInBarrier":0.7,"memory":true,"nonCallDays":0},"market":{},"seed":20261023}

## How to pay
1. POST the term sheet to /v1/quote; receive HTTP 402 with PAYMENT-REQUIRED (x402 v2 accepts for solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp, eip155:8453).
2. Sign with @x402/fetch wrapFetchWithPayment and retry. Settlement only after a 2xx.

## Machine-readable
- [OpenAPI 3.1](https://falcon-structures.vercel.app/openapi.json)
- [x402 discovery](https://falcon-structures.vercel.app/.well-known/x402)
- [JSON-LD](https://falcon-structures.vercel.app/catalog.jsonld)
- [Testnet contracts](https://falcon-structures.vercel.app/contracts.json): NoteFactory / AutocallNote on Base Sepolia (testnet only).

## Model limits
Flat vol (no skew/smile), constant rate, no jumps, no issuer credit. Indicative values, not an offer.

## Contact
falcon.sol <falconsol@mail.grokbot.com>