PineForge Data

Fetch normalized market data and run raw PineScript strategies through PineForge.

PineForge Data provides Python adapters for exchanges, CSV files, SQLite, and SQLAlchemy-compatible databases. Its backtest harness sends normalized OHLCV to the pineforge-release container, which transpiles the PineScript, compiles it, and runs pineforge-engine.

exchange / CSV / database
          ↓
    pineforge-data
          ↓
 pineforge-release container
          ↓
     backtest report

The provider layer is Python-only. You do not need a C++ compiler, Git submodules, or local engine and codegen checkouts.

Quick start

You need Python 3.11 or newer. Docker is required only for backtests; fetching and normalizing data does not use Docker.

1. Install an exchange provider

python -m pip install 'pineforge-data[ccxt]'

2. Fetch confirmed OHLCV

import asyncio

from pineforge_data import BarRequest, CcxtProvider


async def main() -> None:
    async with CcxtProvider("bitstamp") as provider:
        market = await provider.resolve_market("BTC/USD")
        bars = await provider.fetch_bars(
            BarRequest(
                instrument=market.instrument,
                timeframe="15m",
                start_ms=1_751_328_000_000,
                end_ms=1_751_414_400_000,
            )
        )
        print(bars[-1])


asyncio.run(main())

Symbols are resolved through the provider catalog. For example, CCXT spot BTC/USDT and linear swap BTC/USDT:USDT are distinct instruments with different contract metadata.

3. Backtest raw PineScript

Save a strategy as strategy.pine:

//@version=6
strategy("SMA cross", initial_capital=10000, default_qty_type=strategy.percent_of_equity, default_qty_value=10)

fast = ta.sma(close, 2)
slow = ta.sma(close, 4)

if ta.crossover(fast, slow)
    strategy.entry("Long", strategy.long)

if ta.crossunder(fast, slow)
    strategy.close("Long")

Then run:

pineforge-backtest \
  --pine strategy.pine \
  --provider ccxt \
  --venue bitstamp \
  --symbol BTC/USD \
  --timeframe 15m \
  --start 2025-07-01T00:00:00Z \
  --end 2025-07-08T00:00:00Z \
  --warmup-bars 100 \
  --output report.json \
  --pretty

The first run pulls the digest-pinned pineforge-release 1.0.0 image (engine 1.0.0, codegen 1.0.0). Results can differ between releases, notably for scripts that omit their capital or order size; the runtime image policy explains why and how to pin another release with --runtime-image. The JSON report includes trades, performance statistics, the equity curve, data provenance, and exact runtime versions. The strategy is compiled inside an isolated Docker container; the provider and its credentials remain on the host.

Bring your own data

PineForge does not require a fixed table definition. Local providers inspect headers or reflected database columns at runtime, infer common OHLCV names, and accept an explicit mapping when your schema uses different names.

The same pineforge-backtest command supports --provider csv, sqlite, and sqlalchemy. See the backtesting guide for provider configuration, warmup behavior, strategy inputs, reports, and local versus remote execution.

Documentation

Contributing

Community providers are welcome. Keep vendor SDKs and schemas inside the adapter, resolve instruments through the upstream market catalog, normalize timestamps to Unix milliseconds, and add deterministic offline tests.

git clone https://github.com/pineforge-4pass/pineforge-data.git
cd pineforge-data
python -m pip install -e '.[dev,ccxt,database-e2e,server,docs,release]'
ruff check .
mypy src
pytest
mkdocs build --strict

Run ./scripts/run_database_e2e.sh to seed corpus OHLCV into disposable SQLite, MySQL, and PostgreSQL databases and verify the public provider API against all three.

Read CONTRIBUTING.md for the provider contract, entry points, security rules, and full validation checklist.

Apache-2.0 licensed.