Quantra is a QuantLib-based pricing service built for parallel execution. It exposes pricing functionality over gRPC with FlatBuffers and through an HTTP/JSON gateway for easier integration and generated OpenAPI documentation.
QuantLib is powerful, but it is not naturally suited to high-concurrency service workloads because important state such as Settings::instance().evaluationDate() is global to the process. Quantra works around that by running multiple isolated pricing workers and placing Envoy in front of them as a load balancer.
- A C++ pricing server built on QuantLib
- A gRPC API using FlatBuffers messages, plus a
MetaRPC and the standardgrpc.health.v1.Healthservice - A JSON/HTTP gateway in
jsonserver/ - A C++ client in
clients/cpp/ - A Python client package in
clients/python/
Priced instruments:
- Fixed-rate bonds
- Floating-rate bonds
- Zero-coupon bonds
- Callable / puttable fixed-rate bonds
- Vanilla swaps (two
SwapLeglegs: fixed vs IBOR or CMS coupons) - OIS swaps (two
SwapLeglegs: fixed vs overnight coupons) - Basis swaps (two floating
SwapLeglegs: IBOR or overnight coupons) - Zero-coupon swaps
- Zero-coupon inflation swaps
- Year-on-year inflation swaps
- FRAs
- Caps, floors and collars
- Swaptions (on a vanilla or OIS underlying built from
SwapLeglegs) - Year-on-year inflation caps, floors, and collars
- CDS
- Equity options
- FX forwards
- Cross-currency swaps (two
SwapLeglegs in two currencies: fixed, IBOR or overnight coupons, principal exchanges) - Structured notes on equity-index baskets by Monte Carlo (worst-of / best-of / average autocallables, Phoenix and snowball coupons, low hurdles, step-downs, reverse convertibles, European or daily capital barriers, geared puts, upside participation; quanto underlyings; bump-and-reprice Greeks on common random numbers; opt-in diagnostics)
Utility endpoints cover yield- and inflation-curve bootstrapping, volatility
surface sampling, Hull-White and SABR calibration, calendar date arithmetic,
and the equity market-data chain for the option and structured-note
pricers: implied forwards and dividends from listed option quotes
(/calibrate-implied-forwards), a Black volatility surface
(/calibrate-vol-surface, Andreasen-Huge, SVI per expiry or eSSVI), its
validation against the quotes (/validate-vol-surface: fit, local-vol
arbitrage scan, Monte Carlo repricing) and a correlation matrix from price
histories (/calibrate-correlation, aligned returns, Ledoit-Wolf shrinkage,
eigenvalue floor).
Features that apply across products:
- Amortizing and step-up notionals on swap legs and bonds
- CMS legs, including capped and floored CMS coupons
- Stub periods (short/long first and last coupons) on every schedule
- Bermudan and American swaption exercise on a Hull-White lattice
- American and Bermudan equity exercise and digital payoffs
See examples/data/ for sample payloads. For a worked, QuantLib-verified
example of every product — each one a complete request JSON whose response is
asserted against an independent QuantLib reference in the test gate — browse
the functional parity catalog.
The main runtime model is a multi-process gRPC service fronted by Envoy:
JSON client -> json_server (:8080) -> Envoy (:50051) -> sync_server workers (:50055+)
gRPC client -----------------------> Envoy (:50051) -> sync_server workers (:50055+)
Measured on an AMD Ryzen 9 3900X (12 cores / 24 threads), 62 GiB RAM, Debian 13, Linux 6.1. Both benchmarks are informational (not part of the test gate) and live in tests/bench/.
Pricing the same request across N worker processes behind Envoy, versus pricing it single-threaded with QuantLib. Workload: one EUR multicurve swap (2 curves, 24 bootstrap helpers). Generated by tests/bench/run_throughput.sh.
| Workers | Throughput (req/s) | Speedup vs 1 worker |
|---|---|---|
| 1 | 8.5 | 1.0× |
| 2 | 15.7 | 1.8× |
| 4 | 31.0 | 3.6× |
| 8 | 58.0 | 6.8× |
| 12 | 75.4 | 8.9× |
Single-threaded QuantLib reference: ~16 req/s. Scaling is near-linear up to the 12 physical cores.
Per-request latency with the curve cache off vs on (200 requests, mean). Generated by tests/bench/run_bench.sh. A cache hit reuses the bootstrapped curve and skips re-bootstrapping.
| Workload | No cache | Cache | Speedup |
|---|---|---|---|
| Bond (1 curve, 8 helpers) | 2.11 ms | 1.10 ms | 1.9× |
| Swap (2 curves, 24 helpers) | 117.12 ms | 2.02 ms | 57.9× |
The stable quantity is the work removed: on a cache hit the curve set is not re-bootstrapped. The ratio above is not portable, because the cache removes bootstrapping but not a request's fixed transport overhead (parsing, gRPC, serialization). On this hardware that floor is ~1 ms, so a bootstrap-heavy multicurve request shows a large ratio; on a deployment with higher per-request overhead the same workload shows a smaller ratio, and a light single-curve request — whose bootstrap is a small share of the total — shows almost none regardless of hardware. Measure your own with tests/bench/run_bench.sh. The model-calibration cache behaves the same way for swaption Hull-White calibration.
The published GHCR image starts both the JSON API and the gRPC/Envoy endpoint:
- HTTP/JSON API:
8080 - gRPC/Envoy endpoint:
50051
docker pull ghcr.io/joseprupi/quantra-server:0.16.10
docker run --rm \
-p 8080:8080 \
-p 50051:50051 \
ghcr.io/joseprupi/quantra-server:0.16.10Check the running service:
curl http://localhost:8080/health
curl http://localhost:8080/metaBy default the container runs one worker per CPU core (capped at 8). Each worker
is a single-threaded pricing process, so sizing workers to cores is what gives
you parallel throughput. Override the count with QUANTRA_WORKERS:
docker run --rm \
-e QUANTRA_WORKERS=2 \
-p 8080:8080 \
-p 50051:50051 \
ghcr.io/joseprupi/quantra-server:0.16.10See docs/process-manager.md for the full scaling model (load balancing, health
checks, and per-worker caches), and docs/configuration.md for every
environment variable the image reads.
gRPC callers get the same coverage plus two service RPCs: Meta returns the
API version, build metadata, dependency versions, and the product and RPC
lists; grpc.health.v1.Health answers standard Check/Watch probes. See
docs/client.md.
Request rules, HTTP status codes, the error body, and the X-Request-Id /
X-Quantra-Api-Version headers are documented in docs/http-api.md, as are
per-request calendar holiday overrides (calendar_overrides).
The public API reference is available at https://quantra.io/docs/api.
See docs/build.md for environment setup details. Once dependencies are available:
./scripts/build.sh Release
./scripts/quantra start --workers 4 --foreground
./build/jsonserver/json_server localhost:50051 8080You can then call the HTTP API with sample requests from examples/data/:
curl -X POST http://localhost:8080/price-fixed-rate-bond \
-H "Content-Type: application/json" \
-d @examples/data/bonds/fixed_rate_bond_request.jsonThe generated OpenAPI files live in jsonserver/openapi/.
./scripts/build.sh regenerates schemas, recreates build/, and compiles the project.
./scripts/build.sh
./scripts/build.sh ReleaseIf you are editing FlatBuffers schemas and want to regenerate artifacts without a full build:
./scripts/generate_schemas.shThe build dependencies live in the quantraserver:test image, so the gate runs
in Docker — the same command CI runs:
docker run --rm -v "$(pwd):/workspace" -w /workspace quantraserver:test \
bash -lc './scripts/build.sh Release && bash tests/run_all_tests.sh'Inside an environment that already has the dependencies, bash tests/run_all_tests.sh runs the gate directly against an existing build.
The test suite exercises:
- C++ pricing parity against QuantLib
- C++ gRPC integration
- JSON HTTP API scenarios, including the functional parity catalog
- Python client scenarios
See tests/README.md for how the suites are organized and how to run the
whole gate in Docker.
tools/version_diff/ is a cross-version diff tool: it sends the same requests
to two running servers (for example the published image of the release you run
today and the one you are evaluating) and reports every response field that
differs, with both values and the size of the move. Replay your own requests
with it before adopting a release built on a newer QuantLib:
python3 tools/version_diff/quantra_version_diff.py --old http://localhost:8091 --new http://localhost:8093 --requests my_requests/ --md-out diff.mdSee tools/version_diff/README.md for the options (including --catalog,
which replays the functional catalog). What changed, and why, at each QuantLib
upgrade shipped in a release is documented in docs/quantlib-upgrades/
(docs/quantlib-upgrades/1.41-to-1.44.md for 0.11.0, QuantLib 1.41 → 1.44).
src/: the pricing engine internals, in role-based folders —transport/(per-product handlers, product catalog),decode/(FlatBuffers → C++:decode/market/for the market-data tables,decode/products/for the per-product request/response tables),evaluators/(pure QuantLib pricing),market/(curves, indices, vol surfaces, correlation matrices, quanto curves, caches),mc/(the shared Monte Carlo core: basket processes, time grids, the path engine),domain/(plain types),common/(enums, dates, errors). Seesrc/README.md.server/: gRPC pricing server executablejsonserver/: HTTP/JSON gateway and generated OpenAPI docsclients/cpp/: C++ client libraryclients/python/: Python client packageflatbuffers/: schema sources plus generated C++, Python, and JSON artifacts;flatbuffers/grpc/holds the gRPC service definition and its generated bindingsexamples/data/: example JSON requests, one folder per product family (structured_note/holds the two factsheet transcriptions with placeholder market data and their README)examples/structured_note_workflow/: a structured note priced at three levels of market data, with a script that runs the option quotes → forwards → vol surface → note chaintests/: parity, integration, and client testsscripts/: build, code generation, and runtime helperstools/quantra-manager/: packaged process-manager implementationtools/version_diff/: cross-version diff tool (same requests against two servers)docs/: project documentation and reference notes
docs/README.md: documentation indexdocs/build.md: environment setup and build detailsdocs/configuration.md: every environment variable the runtime readsdocs/http-api.md: request rules, status codes, error body, and headersdocs/scripts.md: build and schema toolingdocs/testing.md: test suite detailsdocs/process-manager.md: process-manager behavior and runtime modeldocs/client.md: C++ client, gRPCMeta, and health checkingdocs/versioning.md: versioning policydocs/quantlib-upgrades/: what changes in your numbers at each QuantLib upgrade, and why (docs/quantlib-upgrades/1.41-to-1.44.mdfor 0.11.0)src/README.md: engine layering and the request flowCONTRIBUTING.md: contribution workflow
The repository currently documents and builds around:
- CMake
3.16+ - GCC
12+or Clang14+ - gRPC
v1.60.0 - FlatBuffers
v24.12.23 - QuantLib
1.44in Docker builds - Envoy for worker load balancing
BSD 3-Clause. See LICENSE.txt.