FinPull API reference

All endpoints are served under https://api.finpull.dev/api/v1. The version is part of the path, so a breaking change ships as a new prefix instead of mutating v1 in place.

# Production
https://api.finpull.dev/api/v1

# Local development
http://localhost:8000/api/v1

Symbols accept the spelling your data source uses (BTCUSDT, BTC/USD, AAPL). Responses always contain the canonical form.

Send the key as a bearer token. Keys are generated at Settings → API Keys and shown exactly once; only a SHA-256 hash is stored.

curl "https://api.finpull.dev/api/v1/public/price/BTC/USD" \
  -H "Authorization: Bearer $FINPULL_API_KEY"

Keys are opaque random tokens, not JWTs. Revoking a key takes effect on the next request and closes new WebSocket handshakes. Entitlement failures return 402 with an upgrade payload; a key without the required scope gets 403.

Every payload that carries a price includes a provenance block. Read delay_class before calling a value live: realtime, delayed_seconds, delayed_15m, eod, or daily_ref. Forex is an ECB daily reference rate, not a tradable quote.

curl "https://api.finpull.dev/api/v1/public/candles/BTC/USD?timeframe=1d" \
  -H "Authorization: Bearer $FINPULL_API_KEY"

curl "https://api.finpull.dev/api/v1/public/freshness/BTC/USD" \
  -H "Authorization: Bearer $FINPULL_API_KEY"

Datasets are Parquet exports of stored ticks with point-in-time availability cutoffs, so a label can never see the future. Builds are asynchronous: POST returns { dataset_id, status: "accepted", estimated_rows, license } and you poll the detail endpoint until status is ready or failed.

curl -X POST "https://api.finpull.dev/api/v1/public/datasets" \
  -H "Authorization: Bearer $FINPULL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "BTC/USD",
    "timeframe": "1h",
    "start": "2026-01-01T00:00:00Z",
    "end": "2026-02-01T00:00:00Z",
    "features": {"ohlcv": true, "indicators": true, "session": true},
    "labels": ["forward_return_1h", "volatility_regime"],
    "split": {
      "train":      {"start": "2026-01-01", "end": "2026-01-21"},
      "validation": {"start": "2026-01-22", "end": "2026-01-26"},
      "test":       {"start": "2026-01-27", "end": "2026-02-01"}
    },
    "format": "parquet"
  }'

Export rights are checked per symbol, not per account. Binance crypto is cleared for redistribution and AI training; Yahoo-sourced stocks and futures are display-only and refused. A forward label needs a bar interval at or below its horizon (for example forward_return_1h needs 1h bars or finer).

Both are write-scope Pro endpoints. Backtests persist results under a run id you can fetch later. Paper orders simulate fills against the same honest, latency-labeled prices the app shows; suspect ticks are excluded from marks and fills.

curl -X POST "https://api.finpull.dev/api/v1/public/paper/orders" \
  -H "Authorization: Bearer $FINPULL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"symbol": "BTC/USD", "side": "buy", "quantity": 0.01}'

Paper trading accepts crypto and stocks only. Forex reference rates and futures are not paper-tradable and return 422.

Webhooks are a Pro feature managed from the app with a session cookie (not an API key) under /api/v1/webhooks: create, list, patch, rotate the secret, delete, and inspect deliveries. Each account may hold a bounded number of endpoints, and targets must be public http(s) URLs (private ranges are rejected at registration).

Every delivery is a JSON envelope with id, type, api_version, created_at, and data. When a signing secret is set, the request also carries X-FinPull-Signature: t=<unix>,v1=<hex> and X-FinPull-Timestamp, where the digest is HMAC-SHA256 over {timestamp}.{raw_body} using the endpoint secret.

import { createHmac, timingSafeEqual } from "node:crypto";

export function verify(secret, header, rawBody, toleranceSeconds = 300) {
  const parts = Object.fromEntries(
    header.split(",").map((part) => part.split("=", 2)),
  );
  const timestamp = Number(parts.t);
  if (!Number.isFinite(timestamp)) return false;
  if (Math.abs(Date.now() / 1000 - timestamp) > toleranceSeconds) return false;

  const expected = createHmac("sha256", secret)
    .update(`${parts.t}.`)
    .update(rawBody)
    .digest();
  const received = Buffer.from(parts.v1 ?? "", "hex");
  return received.length === expected.length && timingSafeEqual(received, expected);
}

Verify against the exact bytes you received, not a re-serialized object, and reject timestamps outside your tolerance window so a captured delivery cannot be replayed.

Connect to wss://api.finpull.dev/api/v1/public/stream with the key as ?api_key= (browsers cannot set handshake headers) or as an Authorization: Bearer header from non-browser clients. Then subscribe by message. Free sockets are capped at 5 symbol subscriptions, 30 messages/minute and 2 concurrent connections, with the data-quality channel only; Pro sockets use the higher configured limits and can subscribe to Trend Radar and events.

const socket = new WebSocket(
  "wss://api.finpull.dev/api/v1/public/stream?api_key=" + key,
);

socket.addEventListener("open", () => {
  socket.send(JSON.stringify({ action: "subscribe", channel: "ticks", symbol: "BTC/USD" }));
  socket.send(JSON.stringify({ action: "subscribe", channel: "trends" }));
});

socket.addEventListener("message", (event) => {
  const message = JSON.parse(event.data);
  if (message.error) console.warn(message.error);
  if (message.status === "subscribed") console.log("ready", message);
});

Each subscription is acknowledged with { status: "subscribed", channel, symbol? }. A socket caps out at 20 symbols and 60 messages per minute; exceeding either closes the connection. The legacy { action: "subscribe", symbol } form still subscribes to both ticks and book for that symbol.

The official clients wrap every REST resource and the stream, with retries that honor Retry-After and typed errors.

pip install finpull-sdk
pip install "finpull-sdk[stream]"

npm install @finpull/sdk

from finpull_sdk import FinPull

fp = FinPull(api_key="...")  # defaults to https://api.finpull.dev/api/v1

snapshot = fp.features.get("BTC/USD", timeframe="15m", features=["ohlcv"], limit=100)
for trend in fp.trends.list(direction="bullish")["trends"]:
    print(trend["trend_type"], trend["strength"])

import { FinPull } from "@finpull/sdk";

const fp = new FinPull({ apiKey: "..." });

const snapshot = await fp.features.get("BTC/USD", {
  timeframe: "15m",
  features: ["ohlcv"],
  limit: 100,
});

Errors are JSON with a detail field. A structured detail object may carry code, feature, and upgrade context. Status codes:

Default limits per key or account, configurable per deployment: