nixtla-liquidity-forecaster

name	nixtla-liquidity-forecaster
description	Forecasts orderbook depth and spreads to optimize trade execution timing. Use when needing to estimate market liquidity for large orders. Trigger with 'forecast liquidity', 'predict orderbook', 'estimate depth'.
allowed-tools	Read,Write,Bash(python:*),Glob,Grep,WebFetch
version	1.0.0
author	Jeremy Longshore <[e-mail]>
license	MIT

Liquidity Forecaster

Predicts future orderbook depth and bid-ask spreads using historical market data and TimeGPT.

Overview

This skill analyzes historical trade data and orderbook snapshots from Polymarket to forecast liquidity conditions. It predicts near-term changes in orderbook depth and bid-ask spreads, helping determine optimal trade execution timing. The workflow fetches data via Polymarket API, preprocesses it for TimeGPT compatibility, and generates forecasts with visualizations and reports.

When to use: Determining optimal trade execution timing based on expected liquidity conditions, predicting orderbook depth changes, estimating bid-ask spread evolution.

Trigger phrases: "forecast liquidity", "predict orderbook depth", "estimate spread changes", "analyze market liquidity", "forecast trading conditions".

Prerequisites

Required environment variables:

• NIXTLA_TIMEGPT_API_KEY - Your Nixtla TimeGPT API key

Python packages:

pip install nixtla pandas requests matplotlib

Required tools: Read, Write, Bash, Glob, Grep, WebFetch

Minimum Python version: 3.8+

Instructions

Step 1: Fetch orderbook data

Fetch historical orderbook data from Polymarket API using the market ID. The script retrieves bids and asks, combines them into a single dataset, and saves to CSV format.

Script: {baseDir}/scripts/fetch_data.py

Usage:

python {baseDir}/scripts/fetch_data.py --market_id <MARKET_ID> [--output orderbook_data.csv]

Parameters:

• --market_id (required): Polymarket market identifier
• --output (optional): Output CSV file path (default: orderbook_data.csv)

Output: Raw orderbook data CSV with columns: price, quantity, side

Step 2: Preprocess data

Clean and format orderbook data for TimeGPT input. The script calculates mid-price, spread, and depth metrics, then formats the data according to Nixtla's schema requirements.

Script: {baseDir}/scripts/preprocess_data.py

Usage:

python {baseDir}/scripts/preprocess_data.py --input_file orderbook_data.csv [--output preprocessed_data.csv]

Parameters:

• --input_file (required): Path to raw orderbook CSV from Step 1
• --output (optional): Output CSV file path (default: preprocessed_data.csv)

Output: Preprocessed data CSV with Nixtla format (unique_id, ds, y, spread, depth)

Step 3: Execute forecast

Run TimeGPT forecast on preprocessed data. The script generates predictions for the specified horizon, creates visualizations, and produces a summary report.

Script: {baseDir}/scripts/forecast_liquidity.py

Usage:

python {baseDir}/scripts/forecast_liquidity.py --input_file preprocessed_data.csv --horizon <PERIODS> [--output depth_forecast.csv] [--plot_prefix depth]

Parameters:

• --input_file (required): Path to preprocessed CSV from Step 2
• --horizon (required): Number of periods to forecast
• --output (optional): Output forecast CSV path (default: depth_forecast.csv)
• --plot_prefix (optional): Prefix for plot filename (default: depth)

Output:

• Forecast CSV with predicted values
• PNG plot showing historical data and forecast
• Text report summarizing the forecasting process

Step 4: Interpret results

Review the generated outputs to understand predicted liquidity conditions. The forecast CSV contains time-indexed predictions, the plot visualizes trends, and the report provides metadata about the forecasting run.

Output

Generated files:

• depth_forecast.csv - Time-series predictions for orderbook depth and mid-price
• depth_forecast.png - Visualization showing historical data and forecast overlay
• report.txt - Summary report with market ID, horizon, and output file paths

CSV format: Columns include unique_id, ds (timestamp), y (predicted mid-price), and optional spread/depth metrics.

Error Handling

Invalid Polymarket Market ID Cause: Market ID not recognized by Polymarket API Solution: Verify the market ID at https://polymarket.com or check API documentation

TimeGPT API Key missing Cause: NIXTLA_TIMEGPT_API_KEY environment variable not set Solution: Export your API key: export NIXTLA_TIMEGPT_API_KEY=your_key_here

Insufficient data from Polymarket API Cause: Empty or incomplete orderbook data for the specified market Solution: Check data availability for the market ID, try a different market, or verify API endpoint

TimeGPT forecast failed Cause: Input data format issues or API connection problems Solution: Verify preprocessed data has required columns (unique_id, ds, y), check API status, ensure data types are correct

Missing required columns Cause: Raw orderbook data lacks price, quantity, or side columns Solution: Verify Polymarket API response structure matches expected format, check for API changes

Examples

Example 1: Forecast depth for presidential election market

Predict orderbook depth 6 periods ahead for a political prediction market.

Commands:

python {baseDir}/scripts/fetch_data.py --market_id trump_election_2024
python {baseDir}/scripts/preprocess_data.py --input_file orderbook_data.csv
python {baseDir}/scripts/forecast_liquidity.py --input_file preprocessed_data.csv --horizon 6

Expected output: depth_forecast.csv with 6 forecasted depth values, plot showing trend, summary report.

Example 2: Forecast spread for cryptocurrency market

Predict bid-ask spread 24 periods ahead for an Ethereum price prediction market.

Commands:

python {baseDir}/scripts/fetch_data.py --market_id eth_price_3000 --output eth_orderbook.csv
python {baseDir}/scripts/preprocess_data.py --input_file eth_orderbook.csv --output eth_preprocessed.csv
python {baseDir}/scripts/forecast_liquidity.py --input_file eth_preprocessed.csv --horizon 24 --output eth_spread_forecast.csv --plot_prefix eth_spread

Expected output: eth_spread_forecast.csv with 24 forecasted values, plot named eth_spread_forecast.png, summary report.

Example 3: Quick workflow for sports outcome market

End-to-end workflow for a sports prediction market using default file names.

Commands:

python {baseDir}/scripts/fetch_data.py --market_id superbowl_winner_2025
python {baseDir}/scripts/preprocess_data.py --input_file orderbook_data.csv
python {baseDir}/scripts/forecast_liquidity.py --input_file preprocessed_data.csv --horizon 12

Expected output: Standard output files (depth_forecast.csv, depth_forecast.png, report.txt) with 12-period forecast.

Resources

Nixtla documentation:

• TimeGPT API reference: https://docs.nixtla.io/
• Data format requirements: https://docs.nixtla.io/docs/tutorials-forecasting_with_timegpt

Polymarket API:

• API documentation: https://docs.polymarket.com/
• Market explorer: https://polymarket.com/markets

Related skills:

• nixtla-timegpt-lab - General TimeGPT forecasting workflows
• nixtla-schema-mapper - Data format transformation utilities