DeskPricer v3.4.5

Local HTTP pricing microservice for vanilla European and American equity options. Designed for Excel WEBSERVICE + FILTERXML integration — no VBA, no Bloomberg terminal calls inside the service.

Design intent: DeskPricer is a local-only tool for personal desk pricing and option analytics. It is not intended to be run or served as a public/server-style service. All design choices — localhost binding, no auth, no TLS, no rate limiting, XML-by-default — reflect this.

Use with AI Agents (MCP)

DeskPricer is available as an MCP server. Add it to Cursor, Claude Desktop, or any MCP-compatible agent:

pip install deskpricer

Published on PyPI: https://pypi.org/project/deskpricer/

Cursor — add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "deskpricer": {
      "command": "deskpricer-mcp",
      "args": []
    }
  }
}

Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "deskpricer": {
      "command": "deskpricer-mcp"
    }
  }
}

If deskpricer-mcp is not on your PATH, use the full path to the executable in your virtualenv.

Tools: price_option, implied_volatility, pnl_attribution, portfolio_greeks — same pricing engine as the HTTP API.

See docs/mcp_quickstart.md for full setup, conventions, and example prompts.

Try the Demo Workbook

Open sample/DeskPricer_Bitcoin_Demo.xlsx for a ready-to-run example. It contains 3 sheets:

Each sheet has the actual WEBSERVICE and FILTERXML formulas pre-loaded. Just start DeskPricer and the cells will populate automatically.

What it does

• Price + Greeks for single options or multi-leg portfolios
• Implied volatility solver (Brent method via QuantLib)
• PnL attribution — decompose option PnL into delta, gamma, vega, theta, rho, vanna, volga, and residual
• XML by default — Excel WEBSERVICE + FILTERXML work out of the box; JSON available via Accept: application/json
• Localhost-only — binds to 127.0.0.1; no network exposure

Conventions

Borrow cost (b): Optional annualized stock borrow cost (decimal). Effective cost-of-carry is r − q − b. Omitted or 0.0 matches pre-3.4.0 behavior.

Time to expiry (t): Supplied in years under ACT/365. Internally converted to calendar days (round(t * 365)) with a hard floor of 1 day, then rolled to the next business day using the chosen calendar (hong_kong by default). Theta and charm are computed per calendar day, not per business day.

PnL attribution: calendar_days represents the actual elapsed calendar-day hold period. theta_pnl = theta × calendar_days_elapsed. If both valuation dates are omitted, calendar_days defaults to 1. Provide explicit dates for multi-day hold accuracy.

Excel User Guide

Service Status

Check that the service is running before pulling prices:

Expected output: UP

Example 1: Price a Single Option + Greeks

Assume your sheet has:

Step 1 — Build the URL in a helper cell (e.g. H2):

="http://127.0.0.1:8765/v1/greeks?s="&C2&"&k="&K2&"&t="&T2&"&r="&R2&"&q="&Q2&"&b="&B2&"&v="&V2&"&type="&TYPE2&"&style="&STYLE2

Step 2 — Fetch the raw XML (e.g. I2):

=WEBSERVICE(H2)

Step 3 — Extract values into individual cells:

Expected output for the example above:

Tip: Wrap each FILTERXML in IFERROR(...,"ERR") so one bad row doesn't break the whole sheet.

Example 2: Back Out Implied Volatility from Market Price

You observe a mid-market price of 6.50 for the same option and want the implied vol.

Step 1 — Build the URL (e.g. H2):

="http://127.0.0.1:8765/v1/impliedvol?s="&C2&"&k="&K2&"&t="&T2&"&r="&R2&"&q="&Q2&"&b="&B2&"&price=6.50&type="&TYPE2&"&style="&STYLE2

Step 2 — Extract implied vol:

=VALUE(FILTERXML(WEBSERVICE(H2),"//outputs/implied_vol"))

Expected output: 0.417484 (≈ 41.7 % vol)

Example 3: PnL Attribution

You had a position yesterday (t-1) and want to explain today's PnL.

Assume:

Step 1 — Build the URL:

="http://127.0.0.1:8765/v1/pnl_attribution?s_t_minus_1=100&s_t=102&k=105&t_t_minus_1=0.25&t_t=0.2466&r_t_minus_1=0.05&r_t=0.05&q_t_minus_1=0.02&q_t=0.02&b_t_minus_1=0.0&b_t=0.0&v_t_minus_1=0.2&v_t=0.22&type=call&style=european&qty=10&cross_greeks=true"

Step 2 — Extract attribution buckets:

Expected output:

The residual_pnl captures higher-order effects and model differences between t-1 and t. Enable cross_greeks=true to include vanna and volga contributions.

Example 4: Portfolio / Bulk Greeks

For book-level aggregation, use the POST /v1/portfolio/greeks endpoint via Power Query or a small VBA helper. The endpoint accepts a JSON body with multiple legs and returns per-leg and aggregate Greeks.

See docs/api.md for the full request/response schema.

Greek Conventions

Log Location and Structured Logging

• Log path: DESKPRICER_LOG_DIR env var overrides the default (C:\ProgramData\DeskPricer\logs on Windows, ~/.local/share/deskpricer/logs elsewhere).
• Format: Uses Python's stdlib logging module with a custom JSON formatter and RotatingFileHandler (10 MB rotation, 5 backups). This replaces the earlier hand-rolled open() approach.
• Change the path:
  Copy

  $env:DESKPRICER_LOG_DIR = "C:\MyLogs"
  python -m deskpricer.main

Design Decisions

Local-only by design

DeskPricer is built as a personal desktop tool, not a public API. This explains every intentional omission:

• No authentication / authorization — only 127.0.0.1 can reach the service.
• No TLS / HTTPS — local loopback traffic is unencrypted by design.
• No rate limiting — no throttling; concurrent requests are handled by a process pool rather than serialized on a single QuantLib global state.
• No Swagger / Redoc — OpenAPI docs are hidden in production builds to reduce attack surface.
• XML by default — Excel's WEBSERVICE function does not send Accept: application/json.

If you need any of these features, DeskPricer is the wrong tool. Use a proper API gateway or a full-featured pricing platform.

Why QuantLib runs in a process pool

QuantLib's Python bindings rely on a single process-global Settings.instance() object. Rather than serializing all requests with an asyncio.Lock, DeskPricer dispatches QuantLib work to a ProcessPoolExecutor. Each worker process has its own isolated settings, so concurrent agent or Excel calls can price in parallel without corrupting evaluation dates. Pool size defaults to min(4, cpu_count()) and is configurable via DESKPRICER_WORKERS.

Europeans and economically equivalent Americans bypass QuantLib entirely and use a pure-Python BSM implementation (bsm_fast), validated against QuantLib to six decimal places.

Why PnL attribution uses GET with many query params

Excel's WEBSERVICE function only supports HTTP GET. Since the primary user of this service is Excel, the GET /v1/pnl_attribution endpoint is designed specifically for WEBSERVICE compatibility. Programmatic clients that need a cleaner JSON body can use POST /v1/portfolio/greeks today; a POST alternative for PnL attribution may be added in a future release.

Project Structure

DeskPricer/
├── pyproject.toml
├── README.md
├── src/deskpricer/          # FastAPI app + pricing core
│   ├── app.py               # Thin composition root
│   ├── routers/             # APIRouter modules
│   ├── services/            # Pricing orchestration + QL lock
│   ├── pricing/             # QuantLib pricing engines
│   ├── schemas.py           # Pydantic models
│   ├── responses.py         # XML/JSON serializers
│   ├── errors.py            # Custom exceptions
│   ├── logging_config.py    # Structured JSON logging
│   └── main.py              # Uvicorn entrypoint
├── tests/                   # pytest + hypothesis
├── tests/fixtures/          # Regression baseline JSONs
├── scripts/                 # Build + fixture generation
├── sample/                  # Demo Excel workbook
└── docs/                    # API ref + operator guide

Quickstart

Go from clean clone to a working pricing call in under 5 minutes:

# 1. Install
python -m venv .venv
.venv\Scripts\activate
pip install -e ".[dev]"

# 2. Run
python -m deskpricer.main

# 3. Test with curl
curl "http://127.0.0.1:8765/v1/greeks?s=100&k=105&t=0.25&r=0.05&q=0.02&b=0.0&v=0.20&type=call&style=european"

# 4. Test with Excel (copy into a cell)
# =FILTERXML(WEBSERVICE("http://127.0.0.1:8765/v1/greeks?s=100&k=105&t=0.25&r=0.05&q=0.02&b=0.0&v=0.20&type=call&style=european"),"//outputs/price")

Expected output for the curl call (XML):

<?xml version="1.0" encoding="UTF-8"?>
<greeks>
  <meta>
    <service_version>3.4.5</service_version>
    <quantlib_version>1.42.1</quantlib_version>
    <engine>analytic</engine>
    <valuation_date>2026-06-10</valuation_date>
  </meta>
  <inputs>
    <s>100.0</s>
    <k>105.0</k>
    <t>0.25</t>
    <r>0.05</r>
    <q>0.02</q>
    <b>0.0</b>
    <v>0.2</v>
    <type>call</type>
    <style>european</style>
  </inputs>
  <outputs>
    <price>2.288743</price>
    <delta>0.356244</delta>
    <gamma>0.037206</gamma>
    <vega>0.185519</vega>
    <theta>-0.033315</theta>
    <rho>0.083111</rho>
    <charm>-0.001241</charm>
  </outputs>
</greeks>

For JSON, send Accept: application/json or append ?format=json.

Installation Options

Standalone Executable (Recommended)

Download DeskPricer_v3.exe from the Releases page and run:

.\DeskPricer_v3.exe

The service starts on port 8765. To use a different port:

.\DeskPricer_v3.exe --port 9000

From Source

python -m venv .venv
.venv\Scripts\activate
pip install -e ".[dev]"
python -m deskpricer.main

Running Tests

pytest tests -v

Troubleshooting

QuantLib install failures

If pip install fails on QuantLib, ensure you have a C++ compiler and CMake, or use a pre-built wheel. See docs/operator_guide.md for detailed steps.

Zero-DTE surprises

t=0 is floored to 1 calendar day to prevent QuantLib collapse. You will get a small time-value premium rather than pure intrinsic. This is intentional.

Engine/style mismatches

• style=european → only engine=analytic
• style=american → only engine=binomial_crr or binomial_jr

XML vs JSON

Excel receives XML by default. For JSON, send Accept: application/json or ?format=json.

Error codes

Limitations

• No FD engine — closed-form BSM for Europeans and equivalent Americans; binomial CRR/JR for other Americans.
• Concurrent QuantLib via process pool — default min(4, cpu_count()) workers (DESKPRICER_WORKERS). Portfolio legs batch in a single worker call per request.
• Bounded bump ranges — bump_spot_rel ≤ 0.1, bump_vol_abs ≤ 0.01, bump_rate_abs ≤ 0.01.
• No database or persistence — all state is in-memory per-request.
• No auth, TLS, or rate limiting — local-only by design.

License

MIT