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

> Explore the goldsky/orderFilled.csv schema in warproxxx/poly_data. Understand on-chain trade data including timestamps, addresses, asset IDs, filled amounts, and transaction hashes for completed orders.

- Repository: [warproxxx/poly_data](https://github.com/warproxxx/poly_data)
- Tags: api-reference
- Published: 2026-04-21

---

**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`](https://github.com/warproxxx/poly_data/blob/main/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`](https://github.com/warproxxx/poly_data/blob/main/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`](https://github.com/warproxxx/poly_data/blob/main/update_utils/update_goldsky.py) and the README Data Files section.*

## How the File Is Generated

The [`update_utils/update_goldsky.py`](https://github.com/warproxxx/poly_data/blob/main/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`](https://github.com/warproxxx/poly_data/blob/main/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`](https://github.com/warproxxx/poly_data/blob/main/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)

```python
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

```python
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.

```python

# 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`](https://github.com/warproxxx/poly_data/blob/main/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`](https://github.com/warproxxx/poly_data/blob/main/update_goldsky.py) with resumable cursor logic using [`cursor_state.json`](https://github.com/warproxxx/poly_data/blob/main/cursor_state.json)
- **Consumption**: Processed by [`process_live.py`](https://github.com/warproxxx/poly_data/blob/main/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`](https://github.com/warproxxx/poly_data/blob/main/update_goldsky.py) script implements idempotent writes by tracking progress in a **[`goldsky/cursor_state.json`](https://github.com/warproxxx/poly_data/blob/main/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.