# Fathom Profile

POC, value area, VWAP and standard deviation of the session or of each bar.

## What the indicator shows

- POC: the most traded price.
- Value area (VAH / VAL): the range around the POC holding `valueAreaPercent`% of volume, 70% by default.
- VWAP and standard deviation: the volume-weighted average price, and how spread out prices are around it.

## How to use it

- Inside the value area, the market accepts price; outside it, the market rejects it or looks for a new balance.
- With `scope: session`, follow the POC as it migrates: it shows which way the market is building value.
- With `scope: bar`, see where each bar traded.

## How it is computed

- `scope: "session"` measures the session’s profile, accumulated from the open up to this bar, to follow how the session’s values shift; `scope: "bar"` measures each bar’s alone, to see where each bar traded.
- The POC is the highest-volume price. On a tie within a bar, the footprint rule applies: the lowest of the tied prices at or above the open, otherwise the highest of those below it. With `scope: "session"`, a price only replaces the POC when it strictly exceeds it.
- The value area is built tick by tick from the POC: at each step, it extends to the busier neighboring price, above or below, downward on a tie (a price with no volume counts as 0), until it holds `valueAreaPercent`% of the volume; it extends by at least one tick.
- The standard deviation is the volume-weighted standard deviation of prices, with a Bessel correction on volume: √(Σ v·(p − VWAP)² / (V − 1)), where V is the profile’s total volume.

## When it updates

- One final point per finished `timeframe`-second bar, sent when it closes, whose `id` is the start of the bar.

- Reset at every session open, at 6:00 pm New York time (full session, not only the RTH session). The computation, and the replay over history, start from the start of the trading week (`origin: week`); the week’s last bar gets its values on the first trade of the Sunday reopen.

- **Identifier**: `session-profile`

- **Objects received**: `values`

- **Historical cost**: 1 compute unit per trade

## Subscribe

The same `params` work in [real time](https://fathomcharts.com/docs/websocket.md), on [historical data](https://fathomcharts.com/docs/history.md) and in exports. Parameters you omit take their default values.

**Subscribe message**

```json
{
  "t": "subscribe",
  "sub": "session-profile",
  "instrument": "NQ.front",
  "indicator": "session-profile",
  "params": {
    "scope": "session",
    "timeframe": 300,
    "valueAreaPercent": 70
  },
  "mode": "live",
  "from": "live"
}
```

## Parameters

As soon as a parameter differs from its default, the subscription counts as a [custom configuration](https://fathomcharts.com/docs/limits.md#how-limits-are-counted). To change a parameter, open a new subscription.

| Parameter          | Type    | Default   | Allowed values                                                                                  | Unit | Description                                                                                                                                                                                              |
| ------------------ | ------- | --------- | ----------------------------------------------------------------------------------------------- | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `scope`            | choice  | `session` | `session` · `bar`                                                                               | —    | Which volume profile is measured: the session’s, accumulated from the open up to this bar (`session`), or this bar’s alone (`bar`). Each value is a separate stream: open two subscriptions to get both. |
| `timeframe`        | integer | `300`     | `1` · `5` · `10` · `15` · `30` · `60` · `120` · `180` · `300` · `600` · `900` · `1800` · `3600` | —    | Bar duration in seconds: from 1 second (`1`) to 1 hour (`3600`).                                                                                                                                         |
| `valueAreaPercent` | integer | `70`      | 1 to 100                                                                                        | %    | Share of the volume contained in the value area.                                                                                                                                                         |

## Objects received

Each object keeps the same `id` from one update to the next. Its data is in the `data` field. Prices are in ticks: multiply them by the instrument’s tick size (`GET /v1/instruments`) to get points.

### `values` (sent final)

Values at the close of the bar.

`id` format: `<barStartNs>`. Each object is sent once, final (`final: true`).

| Field  | Type    | Unit  | Present | Description                                                                                                                                                                           |
| ------ | ------- | ----- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `poc`  | integer | ticks | always  | POC of the profile (the session’s up to this bar, or this bar’s alone, per `scope`).                                                                                                  |
| `sd`   | number  | ticks | always  | Volume-weighted standard deviation of prices, with a Bessel correction on volume (√(Σ v·(p − VWAP)² / (V − 1)), V = total volume), to draw bands around the VWAP (`vwap` ± n × `sd`). |
| `vah`  | integer | ticks | always  | Value area high (VAH).                                                                                                                                                                |
| `val`  | integer | ticks | always  | Value area low (VAL).                                                                                                                                                                 |
| `vwap` | number  | ticks | always  | VWAP of the profile (session or bar, per `scope`).                                                                                                                                    |

## Example messages

Messages as the WebSocket sends them to the subscription above, taken from a real NQ session. [Historical data](https://fathomcharts.com/docs/history.md) returns the same objects, with the same `cursor`, without the `sub` field.

**Final object**

```json
{
  "sub": "session-profile",
  "cursor": "20720.0.0",
  "t": "upsert",
  "id": "1790207700000000000",
  "final": true,
  "ts": "1790208000058746563",
  "data": {
    "poc": 123076,
    "vah": 123177,
    "val": 122990,
    "vwap": 123131.51652638057,
    "sd": 63.49728844602092
  }
}
```

## JSON schemas

To validate or type your data: the JSON schemas of the parameters and of `data`, also available from `GET /v1/indicators`. The SDK can [generate types from them](https://fathomcharts.com/docs/sdk.md#indicator-types).

**Parameters schema**

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://fathomcharts.com/schemas/session-profile/params.json",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "scope": {
      "description": "Which volume profile is measured: the session’s, accumulated from the open up to this bar (`session`), or this bar’s alone (`bar`). Each value is a separate stream: open two subscriptions to get both.",
      "type": "string",
      "default": "session",
      "enum": [
        "session",
        "bar"
      ]
    },
    "timeframe": {
      "description": "Bar duration in seconds: from 1 second (`1`) to 1 hour (`3600`).",
      "type": "integer",
      "default": 300,
      "enum": [
        1,
        5,
        10,
        15,
        30,
        60,
        120,
        180,
        300,
        600,
        900,
        1800,
        3600
      ]
    },
    "valueAreaPercent": {
      "description": "Share of the volume contained in the value area.",
      "type": "integer",
      "default": 70,
      "minimum": 1,
      "maximum": 100
    }
  }
}
```

**`data` field schema**

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://fathomcharts.com/schemas/session-profile/data.json",
  "title": "values",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "poc": {
      "description": "POC of the profile (the session’s up to this bar, or this bar’s alone, per `scope`).",
      "type": "integer"
    },
    "sd": {
      "description": "Volume-weighted standard deviation of prices, with a Bessel correction on volume (√(Σ v·(p − VWAP)² / (V − 1)), V = total volume), to draw bands around the VWAP (`vwap` ± n × `sd`).",
      "type": "number"
    },
    "vah": {
      "description": "Value area high (VAH).",
      "type": "integer"
    },
    "val": {
      "description": "Value area low (VAL).",
      "type": "integer"
    },
    "vwap": {
      "description": "VWAP of the profile (session or bar, per `scope`).",
      "type": "number"
    }
  },
  "required": [
    "poc",
    "vah",
    "val",
    "vwap",
    "sd"
  ]
}
```