Candle API Pagination for Historical Backtesting | Toss Auto-Trading Dev Journal #14

🌐 한국어로 보기

The backtest engine itself — buy/sell simulation, performance reports — was already finished in the previous Phase 4 entry (#13). The one thing still missing was an answer to “where does the historical price data actually come from?” This post closes that last gap.

Toss Securities does have a candle endpoint

A quick note for readers unfamiliar with the platform: Toss Securities is a Korean retail brokerage, and its Open API lets individual developers automate trading on their own KRW-denominated account. Whether it exposed historical price data at all was the first thing to check. The official docs at developers.tossinvest.com confirmed a real endpoint: GET /api/v1/candles, with parameters symbol, interval (only 1m/1d supported), count (max 200), before (for pagination), and adjusted (adjusted-price flag).

Worth noting: rate limiting for this endpoint is tracked under its own group, MARKET_DATA_CHART, separate from order/balance endpoints — so hammering candle requests wouldn’t threaten the trading-critical calls.

Writing the parser before the schema was confirmed

The docs didn’t fully spell out the exact response wrapper. Every other endpoint in this project had followed a {"result": [...]} shape, so get_candles() was written in toss_common.py against that assumption, wrapped in the existing retry decorator.

Alongside it, toss_test.py got a diagnostic function, fetch_candles_raw(), for inspecting the raw response directly — the same pattern used earlier to confirm the holdings-endpoint schema. Assumptions get written down, but they don’t get trusted until they’re checked against a real response.

def get_candles(symbol: str, interval: str = "1d", count: int = 200, before: str | None = None):
    """Fetch candles from Toss Securities API (defensive parsing)."""
    params = {"symbol": symbol, "interval": interval, "count": count}
    if before:
        params["before"] = before
    resp = _request_with_retry("GET", "/api/v1/candles", params=params)
    data = resp.json()
    result = data.get("result", {})
    return result.get("candles", []), result.get("nextBefore")

Getting past the 200-item cap

One call alone couldn’t pull enough history for a meaningful backtest. fetch_and_store_historical_prices() was added to backtest.py to loop on the before parameter, collect candles across pages, sort them chronologically, and write them into price_snapshots.

One detail mattered here: when backfilling old data, the stored timestamp can’t just be “now” — it has to be when the candle actually occurred, or later simulation math breaks. insert_price_snapshot() in db.py got an optional captured_at parameter so the real candle timestamp could be preserved.

def insert_price_snapshot(conn, symbol: str, price: float, captured_at: str | None = None):
    ts = captured_at or datetime.utcnow().isoformat()
    conn.execute(
        "INSERT INTO price_snapshots (symbol, price, captured_at) VALUES (?, ?, ?)",
        (symbol, price, ts),
    )
    conn.commit()

The Toss Securities candle endpoint (GET /api/v1/candles) paginates via a before parameter and returns {“result”: {“candles”: […], “nextBefore”: …}}. It caps out at 200 items per call, so backfilling history requires looping.

Mock first, real token second

With the schema unconfirmed, the whole pipeline — two-page pagination, chronological sort, DB write with preserved timestamps, and hand-off to the existing run_backtest() — was validated against mocks first. Only after that passed did the real account token get used to run toss_test.py and inspect the actual response.

The defensive assumption held exactly: {"result": {"candles": [...], "nextBefore": ...}} matched the live response with zero changes needed. It also confirmed candles come back newest-first, which meant the sorting logic written in advance wasn’t just precaution — it was actually necessary. (Sample tickers were masked to placeholder codes such as 005930 and 000660 for testing.)

Phase 0 through 4, done

7 new tests (3 for candle parsing, 2 for pagination integration, 2 for timestamp preservation) brought the suite to 78 passing tests. That closes out all three pieces of Phase 4 — historical data collection/storage, simulation, and performance reporting — and wraps up the roadmap arc that started back at Phase 0.

FAQ

Q1. Does the Toss Securities Open API expose historical candle data?

A. Yes — GET /api/v1/candles supports daily (1d) and 1-minute (1m) intervals, capped at 200 items per call, so pagination via the before parameter is required for longer histories.

Q2. Does candle fetching share rate limits with trading calls?

A. No, it’s tracked under a separate MARKET_DATA_CHART group, isolated from order/balance rate limits.

Q3. How do you handle an unconfirmed response schema?

A. Write the parser against the most likely shape based on existing endpoints, add a raw-response diagnostic function, then confirm against a real token before trusting it.

Q4. How is the backfill timestamp handled?

A. insert_price_snapshot() takes an optional captured_at parameter so the actual candle time is stored instead of the insert time.