How to Track Options Flow & Block Trades Programmatically with Mboum API

Institutional investors, often referred to as "whales," possess the capital to move markets. Unlike retail traders who might buy a single contract, institutions buy thousands of contracts at a time, often executing "sweeps" across multiple exchanges to fill large orders without alerting the broader market immediately.

Tracking Options Flow allows developers and traders to monitor these large-scale transactions in real-time. By analyzing data points such as premiums, trade sides, and contract sizes, you can gauge market sentiment and identify potential breakouts or hedging activity before they become obvious on a standard price chart.

To access this data programmatically, you can use the Mboum API.

https://mboum.com/pages/api

The Options Flow Endpoint

To retrieve significant option transactions across US exchanges, use the Options Flow endpoint. This endpoint returns data regarding institutional buying and selling, providing visibility into where smart money is being allocated.

Documentation:
https://docs.mboum.com#stocks-options-GETapi-v1-markets-options-options-flow

Primary Parameters

• type – Filters the asset class. Accepted values include STOCKS, ETFS, or INDICES.

• page – Handles pagination to retrieve older flow data.

Python Implementation

The following Python script demonstrates how to request options flow data. It includes logic to parse the raw JSON response and filter for "Golden Sweeps"—trades with a premium exceeding $1,000,000, which often signify high-conviction bets.

import requests
import json

# Configuration
API_KEY = "{YOUR_AUTH_KEY}"
BASE_URL = "https://api.mboum.com/v1/markets/options/options-flow"

# Request Parameters
params = {
    "type": "STOCKS",
    "page": "1"
}

headers = {
    "Authorization": f"Bearer {API_KEY}"
}

try:
    response = requests.get(BASE_URL, headers=headers, params=params)
    response.raise_for_status()
    data = response.json()
    
    # Check if body exists in response
    trades = data.get("body", [])
    
    print(f"Analyzing {len(trades)} recent institutional trades...\n")

    for trade in trades:
        # Parse Premium (remove '$' and ',') to perform logic checks
        raw_premium = trade.get("premium", "$0")
        clean_premium = float(raw_premium.replace("$", "").replace(",", ""))
        
        # Filter for "Golden Sweeps" (Premium > $1,000,000)
        if clean_premium > 1000000:
            symbol = trade.get("symbol")
            side = trade.get("side")
            expiration = trade.get("expiration")
            
            print(f"LARGE BLOCK DETECTED:")
            print(f"Contract: {symbol}")
            print(f"Expiration: {expiration}")
            print(f"Side: {side.upper()} | Premium: {raw_premium}")
            print("-" * 30)

except requests.exceptions.RequestException as e:
    print(f"Error fetching data: {e}")

Analyzing the Flow Response

The API returns a JSON object containing detailed metadata for every trade. Understanding these fields is required for building effective algorithmic trading signals or dashboards.

Sample Response Object

{
  "symbol": "AMD|20240621|150.00C",
  "baseSymbol": "AMD",
  "lastPrice": "183.22",
  "symbolType": "Call",
  "strikePrice": "150.00",
  "expiration": "06/21/24",
  "dte": "120",
  "tradePrice": "41.50",
  "tradeSize": "10,000",
  "side": "ask",
  "premium": "$41,500,000",
  "volume": "10,048",
  "openInterest": "9,011",
  "volatility": "48.50%",
  "tradeCondition": "SLCN",
  "label": "BuyToOpen"
}

Key Data Fields

• baseSymbol – The underlying ticker symbol (e.g., AMD)

• symbolType – The type of option contract, either Put or Call

• strikePrice – The price at which the option can be exercised

• premium – The total cash value of the transaction. High premiums indicate high conviction

• side – Indicates the aggressor side. Ask usually implies buying pressure, while Bid implies selling pressure

• tradeCondition – Codes indicating execution details, such as SLCN (Sold Last Sale) or Sweep

• label – Algorithmic determination of intent, such as BuyToOpen

Practical Use Cases

Momentum Trading

Traders often look for repeated "sweeps" on the ask side for the same ticker with short-term expirations. This indicates that institutions are aggressively building a position and expecting immediate price movement.

Contrarian Indicators

If a stock is hitting new highs but the Options Flow endpoint reports massive block trades on Puts at the ask, institutions may be hedging their portfolios or betting on a reversal.

Volume vs. Open Interest

By comparing volume against openInterest provided in the response, you can determine if a trade is opening new positions or closing existing ones. Volume significantly higher than Open Interest suggests new capital entering the market.

Conclusion

Programmatic access to options flow data levels the playing field, giving retail traders and developers the same visibility as institutional desks. By filtering for high-premium transactions via the Mboum API, you can automate the discovery of significant market anomalies.

Get your free API key to start tracking flow today:
https://mboum.com/pages/api