What Data Is Stored in goldsky/orderFilled.csv: Complete Schema Reference

The goldsky/orderFilled.csv file in the warproxxx/poly_data repository stores raw on-chain trade execution events from the Polymarket Goldsky subgraph, capturing timestamps, maker/taker Ethereum addresses, asset IDs, filled amounts (in 6-decimal raw units), and transaction hashes for every completed order.

This CSV serves as the foundational data layer for Polymarket trade analysis within the warproxxx/poly_data open-source project. Automatically generated by the update_goldsky.py script, it contains unprocessed "order-filled" events that downstream processors transform into structured, analytics-ready datasets. Each row represents a single atomic trade execution recorded on the Polygon blockchain.

Column Structure and Data Definitions

The schema follows the exact column whitelist defined in update_utils/update_goldsky.py at lines 15-18, stored in the COLUMNS_TO_SAVE constant. All monetary values use raw integer representations with 6 decimal places (standard for USDC on Polygon).

Column	Description
timestamp	Unix epoch time in seconds when the order was filled on-chain.
maker	Ethereum address (0x...) that placed the maker side of the order.
makerAssetId	Token ID of the asset the maker provided. 0 represents USDC; non-zero values indicate specific outcome tokens.
makerAmountFilled	Quantity of makerAssetId transferred in raw units (divide by 1,000,000 for USDC).
taker	Ethereum address that executed the taker side of the trade.
takerAssetId	Token ID of the asset the taker provided (0 for USDC).
takerAmountFilled	Quantity of takerAssetId transferred in raw units.
transactionHash	The Ethereum transaction hash that recorded this fill event.

Source: Column definitions derived from COLUMNS_TO_SAVE in update_utils/update_goldsky.py and the README Data Files section.

How the File Is Generated

The update_utils/update_goldsky.py script manages the extraction pipeline through its scrape() function, implementing resumable pagination to handle large historical datasets without creating gaps or duplicates.

Extraction and Storage Process:

1. GraphQL Pagination – The scrape() function builds paginated queries against the Goldsky Polymarket subgraph endpoint, specifically targeting orderFilledEvents.
2. JSON Flattening – Nested GraphQL responses are flattened using flatten_json to create tabular row structures.
3. Column Filtering – Only fields listed in COLUMNS_TO_SAVE are retained to minimize file size and ensure schema consistency.
4. Append Logic – Rows append to goldsky/orderFilled.csv without headers; the file initializes automatically on first run.
5. Resume Capability – A cursor file (goldsky/cursor_state.json) tracks the latest timestamp and event ID, enabling safe resumption without duplicates.

Implementation reference: See the scrape() loop in update_utils/update_goldsky.py (lines 15-34 and 68-85).

Loading and Analyzing the Data

Use Polars for high-performance analysis of this potentially large CSV, or Pandas for exploratory data science. The examples below reference the exact column names defined in the source code.

Load with Polars (Recommended)

import polars as pl

# Load the raw order-filled events

df = pl.read_csv(
    "goldsky/orderFilled.csv",
    columns=[
        "timestamp",
        "maker",
        "makerAssetId",
        "makerAmountFilled",
        "taker",
        "takerAssetId",
        "takerAmountFilled",
        "transactionHash",
    ],
)

# Convert Unix timestamps to datetime

df = df.with_columns(
    pl.col("timestamp")
    .cast(pl.Int64)
    .alias("datetime")
)

print(df.head())

Filter Trades by Specific Address

import pandas as pd

df = pd.read_csv("goldsky/orderFilled.csv")

# Filter for a specific maker address

user_address = "0x9d84ce0306f8551e02efef1680475fc0f1dc1344"
maker_trades = df[df["maker"] == user_address]

print(f"Found {len(maker_trades)} trades for this maker.")

Calculate USDC Volume

Since asset ID 0 represents USDC, aggregate volume by filtering for this identifier and dividing by 10^6 to account for the 6-decimal standard.

# Calculate total USDC volume from raw amounts

usdc_maker = df.loc[df["makerAssetId"] == 0, "makerAmountFilled"].sum()
usdc_taker = df.loc[df["takerAssetId"] == 0, "takerAmountFilled"].sum()
total_usdc = (usdc_maker + usdc_taker) / 1_000_000

print(f"Total USDC volume: {total_usdc:,.2f}")

Role in the Data Pipeline

The goldsky/orderFilled.csv functions as the immutable raw archival layer before transformation. According to the warproxxx/poly_data source code, the update_utils/process_live.py script consumes this file via Polars to:

• Map makerAssetId and takerAssetId to human-readable market identifiers
• Calculate trade prices and implied probabilities
• Generate the cleaned processed/trades.csv dataset used for final analytics

This architectural separation ensures the raw on-chain data remains auditable and replayable, while the processed layer optimizes for query performance.

Summary

• Primary Source: Raw dump of Polymarket orderFilledEvents from the Goldsky subgraph
• Key Fields: timestamp, maker/taker addresses, makerAssetId/takerAssetId (0=USDC), filled amounts (6-decimal raw units), transactionHash
• Generation: Automated via update_goldsky.py with resumable cursor logic using cursor_state.json
• Consumption: Processed by process_live.py to generate processed/trades.csv
• File Location: Repository root at goldsky/orderFilled.csv

Frequently Asked Questions

What does asset ID 0 represent in the maker and taker columns?

Asset ID 0 represents USDC (USD Coin) in the Polymarket token system. When makerAssetId equals 0, the maker provided USDC; when takerAssetId equals 0, the taker provided USDC. Non-zero values correspond to specific conditional outcome tokens for prediction market positions. All USDC amounts in the CSV are stored as raw integers with 6 decimal places.

How does the update script prevent duplicate records when resuming?

The update_goldsky.py script implements idempotent writes by tracking progress in a goldsky/cursor_state.json file. This JSON stores the latest processed timestamp and event ID from the subgraph. Upon restart, the script reads this cursor and queries only for events occurring after that point, ensuring append-only writes without gaps or duplication.

What is the difference between maker and taker in this dataset?

The maker is the Ethereum address that placed a resting limit order on Polymarket's order book, specifying the price and quantity they were willing to trade. The taker is the address that actively executed against that resting order, immediately filling it at the maker's specified price. The CSV records both counterparties along with their respective asset IDs and filled amounts to document the complete token exchange for that transaction hash.

How do I convert the amount columns to actual USDC dollar values?

Divide makerAmountFilled or takerAmountFilled by 1,000,000 when the corresponding asset ID equals 0. The raw CSV stores integers representing the smallest unit (wei-like units for 6-decimal tokens), consistent with the ERC-20 standard for USDC. For example, a raw value of 5,000,000 equals 5.00 USDC, and 1,500,000 equals 1.50 USDC.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}