Skip to main content

Getting Started

DerivFabric is a derivatives pricing and risk engine delivered as an HTTP API: you send an instrument and a market, and it returns a price, Greeks, or a risk number. Every priced number comes back with a run manifest saying which pricer produced it, at what version, and how far that implementation has been validated — so a valuation can be explained months later without archaeology.

This page takes you from no access to a priced option.

1. Get access​

DerivFabric is commercial software. There is no public sandbox and no self-service signup — access begins with a tenant provisioned for your organisation, and an API key issued inside it. If you do not yet have a console sign-in, talk to your DerivFabric contact first, because nothing below will work without one.

Once your tenant exists, an API key is created through the admin console, signed in as a Tenant Admin:

  1. Sign in to the console for your deployment.
  2. Select your tenant in the header — keys belong to a tenant.
  3. Open Platform → API Keys.
  4. Give the key a name that says where it will run (risk-desk-nightly, not key1), optionally set an expiry in days, and choose the live or test environment.
  5. Create the key.

Copy the key immediately. The raw secret is returned once, at creation, and is not stored in recoverable form. Afterwards the list shows the key's prefix, scopes, expiry, last use and state — never the secret again.

Keys carry scopes, and endpoints declare what they require: price, calibrate, portfolio, xva, jobs, governance, validate and admin. admin satisfies any requirement, and there is no wildcard. The pricing call below needs price.

Two authorisation failures are reported separately because they need different remedies: DF-AUTH-004 is a missing scope, fixed by issuing a key that carries it, and DF-AUTH-005 is an insufficient tier, fixed by changing plan.

2. Set your environment​

Two values drive everything that follows. DerivFabric is deployed per customer, so the base URL is yours, not a shared one.

export DERIVFABRIC_BASE_URL=https://your-deployment.example
export DERIVFABRIC_API_KEY=df_live_...

Every request authenticates with the X-API-Key header. The single exception is /health, which needs no key.

Keep the key out of source control and out of shell history — read it from your secret manager into the environment rather than pasting it into a file.

3. Your first request​

Price an at-the-money one-year call: spot 100, strike 100, 5% continuously compounded rate, 20% volatility.

curl -X POST "$DERIVFABRIC_BASE_URL/api/v1/price" \
  -H "X-API-Key: $DERIVFABRIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "spot": 100,
    "strike": 100,
    "rate": 0.05,
    "dividend": 0.0,
    "volatility": 0.20,
    "time": 1.0,
    "optionType": "call"
  }'

spot, strike, rate, volatility and time are required — all numbers, with time in years and rate and volatility as decimals, not percentages. dividend (continuous yield) defaults to 0, and optionType defaults to "call"; the only other accepted value is "put".

The response, in full​

{
  "success": true,
  "data": {
    "price": 10.450583572185565,
    "spot": 100.0,
    "strike": 100.0,
    "optionType": "call"
  },
  "meta": {
    "manifest": {
      "engineVersion": "0.1.0",
      "runId": "019fd7c6-3b1a-7c4e-9f2d-8e5a1b0c4d7e",
      "pricerId": "bs_analytical",
      "pricerVersion": 1,
      "pricerFingerprint": "fp:v1:blake3:11fc25828bb872dc164d06e4908a27928ed8f4851a0d953c9a7787e759fc7904",
      "capabilityStatus": "ga-validated",
      "marketDataAsOf": "2026-08-20"
    }
  },
  "correlationId": "019fd7c6-3b1a-7c4e-9f2d-8e5a1b0c4d7e",
  "timestamp": "2026-08-20T09:00:00Z"
}

Three things are worth understanding before you build against it.

Every response is wrapped. The documented schema for an operation describes the payload, not the bytes on the wire; data holds it. This matters most if you generate a client from the OpenAPI spec: a generated type expecting price at the top level will fail, because the top level is success. The correlation id is present on success and failure alike — quote it in a support ticket. It is emitted under both correlationId and correlation_id, carrying the same value.

meta.manifest says what produced the number. Here bs_analytical at version 1, with a capabilityStatus of ga-validated — the strongest of five statuses (roadmap, experimental, production-candidate, ga-validated, retired). The pricerFingerprint is a deterministic BLAKE3 hash over the pricer's identity and version; identical inputs give an identical fingerprint on any process or binary, which makes reproducibility checkable rather than asserted. runId always equals the envelope's correlation id, so one identifier ties a result to its stored receipt.

A manifest may also carry a warnings array — a non-production capability status, an unregistered pricer, or a pricer that needed a curve or surface this deployment has not connected. Read it. It is omitted when empty, so its presence always means something.

On failure, success is false, data is absent, and error holds a stable machine-readable code with a human-readable message:

{
  "success": false,
  "error": { "code": "DF-AUTH-001", "message": "Missing X-API-Key header" },
  "correlationId": "019fd7c6-3b1a-7c4e-9f2d-8e5a1b0c4d7e",
  "timestamp": "2026-08-20T09:00:00Z"
}

One more thing worth knowing early: 202 Accepted is a success, not an error. Job submission returns it with data populated. A client that treats every status at or above 300 as failure without reading success will break on asynchronous work.

4. The same call from an SDK​

The SDKs handle the envelope for you: methods return the unwrapped data, and the manifest is exposed as client state. They share one retry policy — 408, 429 and 5xx, two retries, exponential backoff from 500 ms — and one family of typed errors that preserves the correlation id.

Python​

Requires Python 3.10 or newer. Async, built on httpx, with pydantic models.

pip install derivfabric
import asyncio
import os

from derivfabric import DerivFabricClient


async def main() -> None:
    async with DerivFabricClient(
        api_key=os.environ["DERIVFABRIC_API_KEY"],
        base_url=os.environ["DERIVFABRIC_BASE_URL"],
    ) as client:
        result = await client.pricing.price_vanilla(
            spot=100.0,
            strike=100.0,
            rate=0.05,
            volatility=0.20,
            time=1.0,
            option_type="call",
        )
        print(f"price: {result.price:.6f}")

        # Provenance for the call just made. Read it immediately: it reflects
        # whichever call finished last, so on a shared client with requests in
        # flight it belongs to whoever got there first.
        manifest = client.last_manifest
        if manifest is not None:
            print(f"pricer: {manifest.pricer_id} v{manifest.pricer_version}")
            print(f"status: {manifest.capability_status}")


asyncio.run(main())

Every method is a coroutine, and the client is an async context manager — async with closes the connection pool for you. An omitted keyword is omitted from the request body rather than sent as None.

TypeScript​

Requires Node 18 or newer. Ships ESM and CommonJS builds with type declarations for both, built on standard fetch — so it also runs in Deno, Bun and the browser, with no runtime dependencies.

npm install derivfabric
import { DerivFabricClient } from "derivfabric";

const client = new DerivFabricClient({
  apiKey: process.env.DERIVFABRIC_API_KEY!,
  baseUrl: process.env.DERIVFABRIC_BASE_URL,
});

const result = await client.pricing.priceVanilla({
  spot: 100,
  strike: 100,
  rate: 0.05,
  volatility: 0.2,
  time: 1.0,
  optionType: "call",
});

console.log(`price: ${result.price.toFixed(6)}`);

const manifest = client.lastManifest;
if (manifest) {
  console.log(`pricer: ${manifest.pricerId} v${manifest.pricerVersion}`);
  console.log(`status: ${manifest.capabilityStatus}`);
}

Every method returns a Promise. Requests are plain object literals, so an optional field you leave out is simply absent. Errors are thrown rather than returned, all descending from DerivFabricError.

Other languages​

Clients for Java (com.derivfabric:derivfabric-sdk), .NET (DerivFabric.Sdk) and Rust (derivfabric-client) offer the same namespaces over the same routes, differing only in idiom. Python and TypeScript are the two Maintained SDKs — published, released on a cadence, and the ones to build on today; the others are Provisional: complete and tested, but not yet proven against production traffic. A Go client exists but its distribution is not yet public; ask your DerivFabric contact if you need it.

See SDK Installation for the full per-language surface, and SDK Conventions for the behaviour they share.

5. Where to go next​

Learn the API

  • REST API Overview — the routes, and how they are organised.
  • Vanilla Pricing — pricing, Greeks and implied volatility in depth.
  • Greeks — sensitivities, and the conventions they follow.
  • Contract DSL — express a spread, an autocall or a bespoke payoff.

Go further

  • Calibration — SABR, Heston and yield-curve bootstrapping.
  • Exotic Options — barriers, Asians, lookbacks and structured products.
  • Portfolio & Risk — book pricing, VaR, stress and hedge optimisation.
  • XVA — CVA, DVA, FVA and related adjustments.

Operate it

Check the evidence

  • Capability Matrix — every instrument family, the pricer that serves it, its validation status, the oracles it was measured against, and its stated limitations. Read this before booking against any capability.
  • Glossary — the terms this documentation uses, defined once.