Flash Guidance Engine Developer Portal

Welcome to the Flash Guidance Engine API documentation. Flash is a stateless engine with two core APIs:

Calculate API — Tier-aware simulations, tax brackets, solve, strategy analysis
Guidance API — Progressive Disclosure Value Exchange for AI journeys

⚡ Interactive API Docs

Modern API docs with form-based request builder. Test endpoints live!

Open API Docs →

🤖 MCP Playground

Test 9 MCP tools (4 calculate + 1 primitives + 4 guidance) for AI agent integration.

Open Playground →

🔢 Primitives Library

18 financial math functions: NPV, IRR, Sharpe, bonds. All with formula transparency.

Explore Primitives →

🆕 New in v7.1

Financial Primitives Library: 18 math functions with formula transparency
CFP Endpoints: Capital gains tax, stock valuation, penalty exceptions
MCP Redesign: 26 → 9 tools for better AI agent usability

New in v7.1: Financial Primitives Library

18 stateless financial calculation functions that return formula transparency explaining step-by-step how results were computed.

Example: NPV with Formula Transparency

curl -X POST "https://flash-engine.fly.dev/api/v1/calculate/primitives/npv" \
  -H "Content-Type: application/json" \
  -d '{
    "discount_rate": 0.08,
    "cash_flows": [-10000, 3000, 4000, 5000]
  }'

→ Returns:
{
  "result": 176.29,
  "formula": {
    "name": "Net Present Value (NPV)",
    "calculation_steps": [
      "Period 0: -$10,000.00 / (1.08)^0 = -$10,000.00",
      "Period 1: $3,000.00 / (1.08)^1 = $2,777.78",
      ...
    ]
  }
}

See all 18 primitives in API docs → | Read full guide →

CFP Exam Accuracy Endpoints

3 specialized calculators for complex financial planning scenarios:

1. Capital Gains Tax Calculator

POST /api/v1/calculate/tax/capital-gains

STCG/LTCG netting with proper tax treatment
NIIT (3.8% surtax) for high earners
State capital gains exceptions (e.g., Washington 7% tax)
Handles CFP Q141-type questions

2. Stock Valuation Toolkit

POST /api/v1/calculate/investment/stock-valuation

Gordon Growth Model (constant growth DDM)
Multi-Stage Dividend Discount Model
Free Cash Flow DCF
Handles CFP Q38-type questions

3. IRS Penalty Exceptions Calculator

POST /api/v1/calculate/retirement/penalty-exceptions

Rule 72(t) SEPP (3 calculation methods)
Rule of 55 (401k separation at 55+)
Medical, education, disability exceptions
Handles CFP Q5-type questions

Read CFP endpoints guide →

Calculate API Quick Start

1. Tier-Aware Simulation (v8 API)

curl -X POST "https://flash-engine.fly.dev/api/v1/calculate/simulate" \
  -H "Content-Type: application/json" \
  -d '{
    "tier": 1,
    "user_profile": {
      "current_age": 45,
      "income": 200000
    }
  }'

2. Tier 3 with Account Breakdown

curl -X POST "https://flash-engine.fly.dev/api/v1/calculate/simulate" \
  -H "Content-Type: application/json" \
  -d '{
    "tier": 3,
    "user_profile": {
      "current_age": 45,
      "income": 200000,
      "state_code": "CA"
    },
    "portfolio": {
      "accounts": [
        {"type": "taxable", "balance": 500000},
        {"type": "traditional_401k", "balance": 800000}
      ]
    }
  }'

3. Tax Bracket Analysis

curl "https://flash-engine.fly.dev/api/v1/calculate/tax-bracket?income=200000&state_code=CA"

4. Goal-Seek Solver

curl -X POST "https://flash-engine.fly.dev/api/v1/calculate/solve" \
  -H "Content-Type: application/json" \
  -d '{
    "user_profile": {"current_age": 45, "income": 200000},
    "solver": {
      "mode": "RETIREMENT_AGE",
      "target": {"success_probability": 0.90},
      "constraints": {"min": 55, "max": 75}
    }
  }'

Guidance API Quick Start

Get Journey Context (for AI)

curl -X POST "https://flash-engine.fly.dev/api/v1/guidance/context" \
  -H "Content-Type: application/json" \
  -d '{
    "user_profile": {
      "current_age": 45,
      "income": 200000,
      "state_code": "CA"
    },
    "user_concern": "TAX_DRAG"
  }'

List Entry Themes

curl "https://flash-engine.fly.dev/api/v1/guidance/user-concerns"

List Value Exchange Stages

curl "https://flash-engine.fly.dev/api/v1/guidance/stages"

MCP Integration (AI Agents)

Flash exposes 12 tools via Model Context Protocol at /mcp:

Calculate Tools (New)

calculate_simulate — Tier-aware retirement simulation
calculate_tax_bracket — Tax bracket analysis
calculate_solve — Goal-seek solver
calculate_analyze — Strategy analysis (9 types)

Guidance Tools (New)

guidance_context — Journey context (no calculations)
guidance_user_concerns — List user concerns
guidance_stages — List stages
guidance_differentiators — List differentiators

Legacy Tools (Deprecated)

flash_simulate, flash_solve, flash_tax_bracket, flash_strategy

SDK Generation

# Generate TypeScript client
npx @openapitools/openapi-generator-cli generate \
  -i https://flash-engine.fly.dev/openapi.json \
  -g typescript-fetch \
  -o ./flash-client

⚡ Flash Guidance Engine