# VannaCharm API Documentation

Programmatic access to dealer exposure surfaces for SPY, QQQ, SPX, NDX 0DTE options.

## Usage rights

Premium API access is for personal use. Internal platform or dataset-mirroring use requires a Business license; customer-facing use requires a Commercial agreement. Technical API access alone does not grant these broader rights.

Licensing expands permitted use of available data. Before purchase, we confirm supported data, historical availability, operating limits, authorized users, billing, and activation in writing. These plans do not automatically add endpoints, higher rate limits, user seats, every expiration, complete history, guaranteed point-in-time integrity, or an uptime commitment.

[Which plan do I need?](https://vannacharm.com/api-data-licensing) · [Terms and Conditions](https://vannacharm.com/terms-and-conditions)

## Authentication

All API requests require an API key. Generate one from the [Account page](https://vannacharm.com/account) and send it in the `X-API-Key` request header.

## GET /api/getMinuteSurfaces

Retrieve minute-by-minute dealer exposure surfaces for a given symbol and trading date.

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `symbol` | string | Yes | SPY, QQQ, SPX, or NDX |
| `trade_date` | string | Yes | YYYY-MM-DD format |

### Response

Returns up to 390 minute surface objects, one per minute of Regular Trading Hours from 9:30 AM through 4:00 PM ET.

Each object contains:

- `session_minute` — 0-389 (minute offset from 9:30 AM ET)
- `spot` — underlying price at that minute
- `vix` — VIX level at that minute
- `surfaces_jsonb` — object containing four surface arrays: gamma, vanna, charm, and iv

The REST response uses the public `surfaces_jsonb` field. Official clients normalize it to `surfaces`.

#### `surfaces_jsonb` shape

```json
{
  "gamma": [
    { "strike": 560, "call": 1250000, "put": -980000, "net": 270000 },
    { "strike": 565, "call": 890000, "put": -1100000, "net": -210000 },
    ...
  ],
  "vanna": [
    { "strike": 560, "call": 45000, "put": -32000, "net": 13000 },
    ...
  ],
  "charm": [
    { "strike": 560, "call": 12000, "put": -8500, "net": 3500 },
    ...
  ],
  "iv": [
    { "strike": 560, "call": 0.18, "put": 0.21, "net": 0.195 },
    ...
  ]
}
```

Each surface point contains:

- `strike` — the strike price
- `call` — dealer exposure from call contracts at this strike
- `put` — dealer exposure from put contracts at this strike
- `net` — combined dealer exposure (call + put) at this strike

## Code examples

### curl

```bash
curl --compressed -H "X-API-Key: vannacharm_live_YOUR_KEY" \
  "https://vannacharm.com/api/getMinuteSurfaces?symbol=SPY&trade_date=2026-03-10"
```

### floe - TypeScript

```typescript
import { NewApiClient } from "@fullstackcraftllc/floe";

const client = NewApiClient("vannacharm_live_YOUR_KEY");

const surfaces = await client.GetDealerMinuteSurfaces(null, {
  symbol: "SPY",
  trade_date: "2026-03-10",
});

// surfaces is an array of MinuteSurface objects
// each containing gamma, vanna, charm, and iv arrays
for (const minute of surfaces) {
  console.log(minute.session_minute, minute.spot, minute.vix);
  console.log("First gamma net:", minute.surfaces.gamma[0]?.net);
}
```

### floe-go - Go

```go
package main

import (
    "context"
    "fmt"
    "github.com/FullStackCraft/floe-go/apiclient"
)

func main() {
    client := apiclient.NewApiClient("vannacharm_live_YOUR_KEY", nil)

    surfaces, err := client.GetDealerMinuteSurfaces(
        context.Background(),
        apiclient.DealerMinuteSurfacesRequest{
            Symbol:    "SPY",
            TradeDate: "2026-03-10",
        },
    )
    if err != nil {
        panic(err)
    }

    for _, minute := range surfaces {
        fmt.Printf("Minute %d: spot=%.2f vix=%.2f\n",
            minute.SessionMinute, minute.Spot, minute.Vix)
        if len(minute.Surfaces.Gamma) > 0 {
            fmt.Printf("First gamma net: %.2f\n", minute.Surfaces.Gamma[0].Net)
        }
    }
}
```

### floe-py - Python

```python
from floe import ApiClient, DealerMinuteSurfacesRequest

client = ApiClient("vannacharm_live_YOUR_KEY")

surfaces = client.get_dealer_minute_surfaces(
    DealerMinuteSurfacesRequest(
        symbol="SPY",
        trade_date="2026-03-10",
    )
)

for minute in surfaces:
    print(minute.session_minute, minute.spot, minute.vix)
    print("First gamma net:", minute.surfaces.gamma[0].net)
```

### JavaScript

```javascript
const res = await fetch(
  "https://vannacharm.com/api/getMinuteSurfaces?symbol=SPY&trade_date=2026-03-10",
  { headers: { "X-API-Key": "vannacharm_live_YOUR_KEY" } }
);
const { data } = await res.json();

for (const minute of data) {
  console.log(minute.session_minute, minute.spot, minute.vix);
  console.log("First gamma net:", minute.surfaces_jsonb.gamma[0]?.net);
}
```

### TypeScript

```typescript
interface SurfacePoint {
  strike: number;
  call: number;
  put: number;
  net: number;
}

interface MinuteSurface {
  session_minute: number;
  spot: number;
  vix: number;
  surfaces_jsonb: {
    gamma: SurfacePoint[];
    vanna: SurfacePoint[];
    charm: SurfacePoint[];
    iv: SurfacePoint[];
  };
}

const res = await fetch(
  "https://vannacharm.com/api/getMinuteSurfaces?symbol=SPY&trade_date=2026-03-10",
  { headers: { "X-API-Key": "vannacharm_live_YOUR_KEY" } }
);
const { data }: { data: MinuteSurface[] } = await res.json();

for (const minute of data) {
  console.log(minute.session_minute, minute.surfaces_jsonb.gamma[0]?.net);
}
```

### Python (vanilla)

```python
import requests

res = requests.get(
    "https://vannacharm.com/api/getMinuteSurfaces",
    params={"symbol": "SPY", "trade_date": "2026-03-10"},
    headers={"X-API-Key": "vannacharm_live_YOUR_KEY"},
)
data = res.json()["data"]

for minute in data:
    print(minute["session_minute"], minute["spot"], minute["vix"])
    print("First gamma net:", minute["surfaces_jsonb"]["gamma"][0]["net"])
```

### C#

```csharp
using System.Net.Http;
using System.Net.Http.Json;

var client = new HttpClient();
client.DefaultRequestHeaders.Add("X-API-Key", "vannacharm_live_YOUR_KEY");

var url = "https://vannacharm.com/api/getMinuteSurfaces?symbol=SPY&trade_date=2026-03-10";
var result = await client.GetFromJsonAsync<ApiResponse>(url);

foreach (var minute in result.Data)
{
    Console.WriteLine($"{minute.SessionMinute} spot={minute.Spot} vix={minute.Vix}");
}
```

### Rust

```rust
use reqwest::header;
use serde::Deserialize;

#[derive(Deserialize)]
struct ApiResponse { data: Vec<MinuteSurface> }

#[derive(Deserialize)]
struct MinuteSurface {
    session_minute: u32,
    spot: f64,
    vix: f64,
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = reqwest::Client::new();
    let res: ApiResponse = client
        .get("https://vannacharm.com/api/getMinuteSurfaces")
        .query(&[("symbol", "SPY"), ("trade_date", "2026-03-10")])
        .header("X-API-Key", "vannacharm_live_YOUR_KEY")
        .send().await?
        .json().await?;

    for minute in &res.data {
        println!("{} spot={:.2} vix={:.2}", minute.session_minute, minute.spot, minute.vix);
    }
    Ok(())
}
```

## Official client libraries

### TypeScript / JavaScript

- Install: `npm install @fullstackcraftllc/floe`
- Full Black-Scholes pricing, Greeks calculation, IV surfaces, and API client.
- [View floe documentation](https://fullstackcraft.github.io/floe/)

### Go

- Install: `go get github.com/FullStackCraft/floe-go`
- Native Go implementation with identical feature set.
- [View floe-go documentation](https://fullstackcraft.github.io/floe-go/)

### Python

- Install: `pip install git+https://github.com/FullStackCraft/floe-py.git`
- Zero-dependency Python implementation with the same analytics and API client coverage. The pip install floe-py command will be listed after the 0.1.0 PyPI release is verified.
- [View floe-py documentation](https://fullstackcraft.github.io/floe-py/)

## Data coverage

| Property | Coverage |
| --- | --- |
| Symbols | SPY, QQQ, SPX, NDX |
| Start date | 2022-05-02 |
| Resolution | 1 Minute |
| Type | 0DTE |

Coverage starts on 2022-05-02 for all listed symbols. Available trading days can vary by symbol due to market calendars and data-quality filtering.

## Canonical documentation

https://vannacharm.com/docs