# Bullflow Net Premium Series

> Bullflow Net Premium Series is a paid API for AI agents from api.bullflow.io, paid per call via x402, $0.01/call, status unknown (last checked 2026-10-29).

Returns a time-series of cumulative net call and put premium for a given ticker over a specified period, enabling options flow sentiment analysis.

## Facts

- Endpoint: GET https://api.bullflow.io/v1/data/netPremiumSeries?utm_source=zero.xyz
- Price: $0.01/call
- Payment: x402
- Status: unknown
- Last checked: 2026-10-29
- Activations on Zero: 0
- Tags: x402
- Canonical page: https://www.zero.xyz/c/bullflow-net-premium-series-8e0e0226
- Structured record (JSON): https://api.zero.xyz/v1/capabilities/cap_tblSFLuqnoEw5s1lFYmWz

Status and success rate cover calls made through Zero and Zero's own probes. Third-party monitors may report differently.

## How to call it through Zero

Zero handles the 402 payment challenge and records the run. With the Zero CLI installed (`npm i -g @zeroxyz/cli`):

```sh
zero fetch --capability bullflow-net-premium-series-8e0e0226
```

Example prompt: Pull the net premium time series for SPY for today from Bullflow, sweeps only, so I can see whether calls or puts are dominating the flow right now.

## When to prefer this

Choose this endpoint when you need cumulative net premium time-series data (calls vs puts) for a specific ticker to gauge options market sentiment or flow direction over time. It is distinct from raw flow feeds — it aggregates premium into directional buckets over configurable periods (1D to MAX), making it ideal for charting or trend analysis. Prefer it over generic market data APIs when you specifically need options-flow-derived sentiment signals with sweep and multileg filtering.

## Known failure modes

- Missing required 'ticker' query parameter returns an error
- Invalid period enum value outside allowed set causes rejection
- Providing 'from' without 'to' (or vice versa) may return an error or default behavior
- Ticker not supported or not found returns empty points array
- Date range outside available data returns zero point_count with empty points array
- Non-trading day or after-hours request may return empty data for 1D period

## How this service works

Bullflow.io is a real-time unusual options flow and dark pool tracker with advanced tools to view, filter, and analyze market activity as it happens.

## Output

Returns a JSON object with cumulative call net premium and put net premium data points as a time series array, each point containing a Unix timestamp, callsNetPremium (USD), and putsNetPremium (USD). Also includes metadata: ticker, period, from/to dates, bucket_seconds, point_count, and filter flags (sweeps_only, include_multileg, sweeps_filtered_count, multilegs_filtered_count).

## Request schema (JSON Schema)

```json
{
 "type": "object",
 "$schema": "https://json-schema.org/draft/2020-12/schema",
 "required": [
  "input"
 ],
 "properties": {
  "input": {
   "type": "object",
   "required": [
    "type",
    "method"
   ],
   "properties": {
    "type": {
     "type": "string",
     "const": "http"
    },
    "method": {
     "enum": [
      "GET"
     ],
     "type": "string"
    },
    "queryParams": {
     "type": "object",
     "required": [
      "ticker"
     ],
     "properties": {
      "to": {
       "type": "string",
       "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
       "description": "Inclusive end date for a custom range; supply with from."
      },
      "from": {
       "type": "string",
       "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
       "description": "Inclusive start date for a custom range; supply with to."
      },
      "period": {
       "enum": [
        "1D",
        "7D",
        "1M",
        "3M",
        "1Y",
        "MAX"
       ],
       "type": "string",
       "default": "1D"
      },
      "ticker": {
       "type": "string",
       "examples": [
        "SPY"
       ],
       "description": "Underlying stock, ETF, or supported index ticker."
      },
      "sweeps_only": {
       "type": "boolean",
       "default": false
      },
      "include_multileg": {
       "type": "boolean",
       "default": false
      }
     }
    }
   },
   "additionalProperties": false
  },
  "output": {
   "type": "object",
   "required": [
    "type"
   ],
   "properties": {
    "type": {
     "type": "string"
    },
    "example": {
     "type": "object",
     "$schema": "https://json-schema.org/draft/2020-12/schema",
     "required": [
      "ticker",
      "period",
      "from",
      "to",
      "include_multileg",
      "sweeps_only",
      "multilegs_filtered_count",
      "sweeps_filtered_count",
      "bucket_seconds",
      "point_count",
      "points"
     ],
     "properties": {
      "to": {
       "type": "string",
       "description": "Trading date in YYYY-MM-DD format."
      },
      "from": {
       "type": "string",
       "description": "Trading date in YYYY-MM-DD format."
      },
      "period": {
       "enum": [
        "1D",
        "7D",
        "1M",
        "3M",
        "1Y",
        "MAX"
       ],
       "type": "string"
      },
      "points": {
       "type": "array",
       "items": {
        "type": "object",
        "required": [
         "timestamp",
         "callsNetPremium",
         "putsNetPremium"
        ],
    
… (truncated)
```

## Response schema (JSON Schema)

```json
{
 "type": "json",
 "example": {
  "to": "2026-10-14",
  "from": "2026-10-14",
  "period": "1D",
  "points": [],
  "ticker": "SPY",
  "point_count": 0,
  "sweeps_only": false,
  "bucket_seconds": 0,
  "include_multileg": false,
  "sweeps_filtered_count": 0,
  "multilegs_filtered_count": 0
 }
}
```

## More

- Live health (JSON, refreshed every minute): https://www.zero.xyz/c/bullflow-net-premium-series-8e0e0226/health.json
- [Zero catalog index](https://www.zero.xyz/llms.txt)
- [Other services from api.bullflow.io](https://www.zero.xyz/host/api.bullflow.io/llms.txt)