> ## Documentation Index
> Fetch the complete documentation index at: https://scalarfield.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Polymarket Prediction Markets

> Search prediction markets, query OHLCV price bars, inspect live order books, analyze trade flow, track wallet leaderboards and positions, and view trader profiles — all from Polymarket's on-chain CLOB.

<Info>**Python functions:** `screenPolymarkets()`, `getPolymarketOHLCV()`, `getPolymarketPriceAndBook()`, `getPolymarketTrades()`, `screenPolymarketWallets()`, `getPolymarketPositions()`, `getPolymarketProfile()`</Info>

| Specification      | Value                                                 |
| ------------------ | ----------------------------------------------------- |
| Delivery Frequency | continuous, real-time                                 |
| Data Frequency     | event-driven (trades), bar-aggregated (OHLCV)         |
| Coverage           | All active and resolved Polymarket prediction markets |
| OHLCV Timeframes   | daily, hourly, 5-min, 15-min, 30-min                  |
| Availability       | Free                                                  |

# Product Overview

## Overview

Polymarket Data provides comprehensive access to Polymarket's on-chain prediction market exchange. The dataset spans seven functions covering market discovery, price history, live order books, trade-level data, wallet analytics, position tracking, and trader profiles.

Prediction markets on Polymarket are binary or multi-outcome events (e.g. "Will X happen?") where outcome tokens trade between $0.00 and $1.00. Each market has one or more **outcome tokens** identified by `token_id`, which you obtain from `screenPolymarkets()` and use across all other functions.

Because prices are probabilities and every trade is on-chain, this dataset supports strategies that have no equivalent in traditional markets: probability arbitrage between related markets, event-driven signals extracted from prediction prices, and copy-trading of wallets with verified track records.

<Note>Polymarket is a tradable venue on Scalar Field: outcome tokens execute live or in paper mode through `venue.trade()` or `strategy.execute()`. See [Trading on Polymarket](/docs/trading/venues/polymarket) for order semantics, funding, and connection steps.</Note>

## Functions at a Glance

| Function                      | Purpose                                                           | Example strategy use                                      |
| ----------------------------- | ----------------------------------------------------------------- | --------------------------------------------------------- |
| `screenPolymarkets()`         | Search and filter markets by keyword, tags, volume, status        | Universe selection; finding mispriced or related markets  |
| `getPolymarketOHLCV()`        | OHLCV price bars for outcome tokens (daily to 5-min)              | Backtesting probability drift and event-reaction patterns |
| `getPolymarketPriceAndBook()` | Live last-trade price and CLOB order book                         | Slippage checks and spread-capture before entering        |
| `getPolymarketTrades()`       | Trade-level history with wallet, price, size, USDC value          | Whale-flow signals; detecting informed money              |
| `screenPolymarketWallets()`   | Wallet leaderboards by PnL or volume, filterable by category      | Finding wallets worth copying, per category               |
| `getPolymarketPositions()`    | Open and closed positions for a wallet or all holders of a market | Copy-trading; mapping who is on each side of a market     |
| `getPolymarketProfile()`      | Trader profile: name, bio, portfolio value, markets traded        | Vetting a wallet's scale and history before mirroring     |

## Data Pipeline

Scalar Field ingests Polymarket data through several complementary paths:

* **Events & Markets:** Polled from the Polymarket Gamma API every \~1 minute. Market metadata (questions, outcomes, prices, volume, status) stays current within seconds of changes on Polymarket.
* **On-chain Trades:** Indexed directly from Polymarket's exchange contracts on Polygon, with \~2-second polling. Each trade is enriched with market and event metadata before storage.
* **OHLCV Bars:** Aggregated from on-chain trades at 5-minute, hourly, and daily granularity. 15-minute and 30-minute bars are derived from 5-minute bars at query time.
* **Order Books & Last Trade:** Fetched live from Polymarket's CLOB API per query — full bid/ask depth, tick size, and minimum order size per outcome token.
* **Wallet, Position & Profile data:** Proxied live from the Polymarket API — each query fetches current data directly, with no local caching delay.

## Coverage

* **Markets:** All active and resolved Polymarket prediction markets, continuously synced.
* **Trades:** On-chain trade history from Polymarket's V2 exchange contracts on Polygon, plus earlier indexed trades.
* **Categories:** sports, politics, crypto, culture, weather, economics, tech, finance.
* **OHLCV Timeframes:** daily, hourly, 30-min, 15-min, 5-min.

# Querying the Data

## `screenPolymarkets()`

Search and filter prediction markets. Returns market metadata, current prices, volume, token IDs, and resolution status.

**Strategy angle:** the universe-selection step. An event-driven strategy screens for open markets in its category (e.g. `'crypto'` or `'economics'`); an arbitrage strategy searches for *related* markets (e.g. several markets about the same election) whose implied probabilities should be consistent — and trades when they are not. `market_outcome_prices` is a live probability estimate you can compare against your own model.

```python theme={null}
from scalarlib import screenPolymarkets

# Browse top markets by volume
df = screenPolymarkets()

# Search for bitcoin-related markets
df = screenPolymarkets(query="bitcoin")

# Open sports markets with minimum volume
df = screenPolymarkets(event_tags='sports', closed=False, min_volume=10000)

# Get token_ids for use in other functions
df = screenPolymarkets(query="super bowl", closed=False)
token_ids = df.iloc[0]['token_ids']

# Bulk lookup of specific markets by ID
df = screenPolymarkets(market_ids=['1476588', '1519231', '1518255'], closed=True)
```

### Parameters

| Parameter            | Type        | Required | Description                                                                                  |
| -------------------- | ----------- | -------- | -------------------------------------------------------------------------------------------- |
| `query`              | str         | No       | Search string (e.g. `"trump election"`, `"bitcoin price"`).                                  |
| `market_ids`         | list of str | No       | Specific market IDs for bulk lookup (faster than filtering).                                 |
| `event_tags`         | str or list | No       | Filter by tag(s), OR logic. Options: `'sports'`, `'politics'`, `'crypto'`, `'culture'`, etc. |
| `exclude_event_tags` | str or list | No       | Exclude markets with these tags.                                                             |
| `closed`             | bool        | No       | `False` = open markets, `True` = resolved markets.                                           |
| `min_volume`         | float       | No       | Minimum USD volume. Defaults to 1,000 when `query` is provided.                              |
| `start_date`         | str         | No       | `"YYYY-MM-DD"`. Filter on market lifecycle: `market_start_date >= start_date`.               |
| `end_date`           | str         | No       | `"YYYY-MM-DD"`. Filter on market lifecycle: `market_end_date <= end_date`.                   |
| `sort_by`            | str         | No       | `"volume"` (default) or `"created_at"`.                                                      |
| `limit`              | int         | No       | Maximum results (default 50).                                                                |
| `offset`             | int         | No       | Pagination offset (default 0).                                                               |

### Return Schema

| Column                    | Type        | Description                                                       |
| ------------------------- | ----------- | ----------------------------------------------------------------- |
| `market_id`               | string      | Unique market identifier                                          |
| `market_question`         | string      | The market's question (e.g. "Will X happen?")                     |
| `market_slug`             | string      | URL-friendly market slug                                          |
| `market_volume`           | float       | Total traded volume (USD)                                         |
| `market_closed`           | bool        | Whether the market has resolved                                   |
| `market_outcomes`         | list        | Outcome labels (e.g. `['Yes', 'No']`)                             |
| `market_outcome_prices`   | list        | Current prices for each outcome (0 to 1)                          |
| `market_best_bid`         | float       | Best bid price                                                    |
| `market_best_ask`         | float       | Best ask price                                                    |
| `market_last_trade_price` | float       | Last trade price                                                  |
| `market_start_date`       | datetime    | Market start date                                                 |
| `market_end_date`         | datetime    | Market end/resolution date                                        |
| `market_created_at`       | datetime    | Market creation timestamp                                         |
| `event_id`                | string      | Parent event identifier                                           |
| `event_title`             | string      | Parent event title                                                |
| `event_slug`              | string      | Parent event slug                                                 |
| `token_ids`               | list of str | Outcome token IDs — use these with all other Polymarket functions |
| `winning_outcome_index`   | int or None | Index of the winning outcome (None if unresolved)                 |

***

## `getPolymarketOHLCV()`

OHLCV price bars for prediction market outcome tokens. Supports daily, hourly, and sub-hourly timeframes. Omit `start` and `end` for live mode (latest bar).

**Strategy angle:** since prices are probabilities, these bars are a time series of the market's belief. Backtest how fast markets converge to resolution (buying favorites at 0.90 and holding to resolution is a measurable, testable strategy), study overreaction to news with 5-minute bars around known events, or use a Polymarket probability series (e.g. a Fed-decision market) as an input feature for strategies trading other asset classes.

```python theme={null}
from scalarlib import getPolymarketOHLCV

# Daily bars
data = getPolymarketOHLCV(token_ids=['abc123...'], start='2026-01-01', end='2026-02-01')
df = data['abc123...']

# Hourly bars (inferred from datetime format)
data = getPolymarketOHLCV(token_ids=['abc123...'], start='2026-02-01T09:00:00', end='2026-02-01T18:00:00')

# 5-minute bars with explicit timeframe
data = getPolymarketOHLCV(token_ids=['abc123...'], start='2026-02-01', end='2026-02-02', timeframe='5min')

# Live mode — latest bar
data = getPolymarketOHLCV(token_ids=['abc123...', 'def456...'])
```

### Parameters

| Parameter   | Type        | Required | Description                                                                                                                         |
| ----------- | ----------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `token_ids` | list of str | Yes      | Outcome token IDs from `screenPolymarkets()`.                                                                                       |
| `start`     | str         | No       | `"YYYY-MM-DD"` or `"YYYY-MM-DDTHH:MM:SS"` (New York time). Omit for live mode.                                                      |
| `end`       | str         | No       | Same format as `start`. Omit for live mode.                                                                                         |
| `timeframe` | str         | No       | `"day"`, `"hour"`, `"5min"`, `"15min"`, or `"30min"`. If omitted, inferred from date format (date-only = daily, datetime = hourly). |

### Return Schema

Returns `Dict[str, pd.DataFrame]` keyed by token ID. Each DataFrame:

| Column    | Type                        | Description                   |
| --------- | --------------------------- | ----------------------------- |
| `ts_recv` | datetime64\[ns, US/Eastern] | Bar timestamp (New York time) |
| `ticker`  | string                      | Token identifier              |
| `open`    | float                       | Opening price (0–1)           |
| `high`    | float                       | High price                    |
| `low`     | float                       | Low price                     |
| `close`   | float                       | Closing price                 |
| `volume`  | float                       | Trading volume                |

***

## `getPolymarketPriceAndBook()`

Latest trade price and live order book for outcome tokens, fetched from Polymarket's CLOB API: full bid/ask depth plus the last executed trade per token.

**Strategy angle:** the pre-trade check for any Polymarket strategy. Prediction market books can be thin — walk the ask side to see how much of your intended size fills near the quoted probability before committing. The bid-ask spread is also an opportunity in itself: wide spreads in low-attention markets reward patient limit orders over market orders, and `tick_size` / `min_order_size` tell you exactly how to place them.

```python theme={null}
from scalarlib import getPolymarketPriceAndBook

data = getPolymarketPriceAndBook(token_ids=['abc123...'])
info = data['abc123...']

info['last_trade_price']           # 0.962
info['asks'].iloc[0]['price']      # best ask
info['bids'].iloc[0]['price']      # best bid

# How much can be bought within 1 cent of the best ask?
asks = info['asks']
asks[asks['price'] <= asks.iloc[0]['price'] + 0.01]['size'].sum()
```

### Parameters

| Parameter    | Type        | Required | Description                                             |
| ------------ | ----------- | -------- | ------------------------------------------------------- |
| `token_ids`  | list of str | Yes      | Outcome token IDs from `screenPolymarkets()`.           |
| `book_depth` | int         | No       | Price levels per side (default 10). `None` = full book. |

### Return Schema

Returns `Dict[str, dict]` keyed by token ID:

| Field              | Type         | Description                                    |
| ------------------ | ------------ | ---------------------------------------------- |
| `last_trade_price` | float        | Last executed trade price (0–1)                |
| `last_trade_side`  | string       | `"BUY"` or `"SELL"`                            |
| `ts`               | datetime     | Book snapshot timestamp (New York time, naive) |
| `tick_size`        | float        | Minimum price increment                        |
| `min_order_size`   | float        | Minimum order size in shares                   |
| `bids`             | pd.DataFrame | Columns `price`, `size` — best bid first       |
| `asks`             | pd.DataFrame | Columns `price`, `size` — best ask first       |

***

## `getPolymarketTrades()`

Trade-level history for prediction markets. Filter by token, wallet, market, event, side, size, price, or USDC value. At least one filter parameter is required.

**Strategy angle:** the informed-money detector. Filtering by `min_usdc_value` isolates whale trades — a sudden cluster of large buys on one outcome often precedes a price move, since big prediction-market bets tend to be information-driven. Filtering by `wallets` turns this into the monitoring leg of a copy-trading strategy: watch a proven wallet's trades in near real time and mirror them.

```python theme={null}
from scalarlib import getPolymarketTrades

# Recent trades on specific tokens
df = getPolymarketTrades(token_ids=['abc...'], start='2026-02-01')

# Wallet trade history
df = getPolymarketTrades(wallets=['0x1234...'], start='2026-01-01')

# Whale trades (> $50k)
df = getPolymarketTrades(min_usdc_value=50000, start='2026-02-01', sort_by='usdc_value')

# Buy-side only, sorted by size
df = getPolymarketTrades(market_ids=['1356546'], side='BUY', start='2026-02-01', sort_by='size')
```

### Parameters

| Parameter             | Type        | Required | Description                                                                             |
| --------------------- | ----------- | -------- | --------------------------------------------------------------------------------------- |
| `token_ids`           | list of str | No       | Filter by outcome token IDs.                                                            |
| `wallets`             | list of str | No       | Filter by wallet addresses (0x-prefixed).                                               |
| `market_ids`          | list of str | No       | Filter by market IDs.                                                                   |
| `event_ids`           | list of str | No       | Filter by event IDs.                                                                    |
| `side`                | str         | No       | `"BUY"` or `"SELL"`.                                                                    |
| `min_size`            | float       | No       | Minimum trade size in shares.                                                           |
| `max_size`            | float       | No       | Maximum trade size in shares.                                                           |
| `min_usdc_value`      | float       | No       | Minimum USDC value.                                                                     |
| `max_usdc_value`      | float       | No       | Maximum USDC value.                                                                     |
| `min_price`           | float       | No       | Minimum price (0–1).                                                                    |
| `max_price`           | float       | No       | Maximum price (0–1).                                                                    |
| `start`               | str         | No       | `"YYYY-MM-DD"` or `"YYYY-MM-DDTHH:MM:SS"` (New York time). Recommended for performance. |
| `end`                 | str         | No       | Same format as `start`.                                                                 |
| `include_market_info` | bool        | No       | Enrich with market question, outcomes, event title (default `True`).                    |
| `sort_by`             | str         | No       | `"timestamp"` (default), `"size"`, `"usdc_value"`, or `"price"`.                        |
| `ascending`           | bool        | No       | `False` = newest/largest first (default).                                               |
| `limit`               | int         | No       | Maximum results (default 1,000).                                                        |
| `offset`              | int         | No       | Pagination offset (default 0).                                                          |

### Return Schema

**Base columns** (always present):

| Column             | Type                        | Description                     |
| ------------------ | --------------------------- | ------------------------------- |
| `ts_recv`          | datetime64\[ns, US/Eastern] | Trade timestamp (New York time) |
| `timestamp`        | int                         | Unix timestamp                  |
| `wallet`           | string                      | Trader wallet address           |
| `side`             | string                      | `"BUY"` or `"SELL"`             |
| `price`            | float                       | Execution price (0–1)           |
| `size`             | float                       | Number of shares traded         |
| `usdc_value`       | float                       | Trade value in USDC             |
| `outcome_token_id` | string                      | Outcome token traded            |
| `outcome_index`    | int                         | Outcome index (0 or 1)          |
| `market_id`        | string                      | Market identifier               |
| `event_id`         | string                      | Event identifier                |

**Additional columns** (when `include_market_info=True`, the default):

| Column            | Type   | Description                 |
| ----------------- | ------ | --------------------------- |
| `market_question` | string | Market question text        |
| `market_outcomes` | list   | Outcome labels              |
| `market_volume`   | float  | Total market volume         |
| `market_closed`   | bool   | Whether market has resolved |
| `traded_outcome`  | string | Name of the traded outcome  |
| `event_title`     | string | Parent event title          |
| `event_url`       | string | Polymarket event URL        |

***

## `screenPolymarketWallets()`

Wallet leaderboards by PnL or volume, filterable by prediction market category and time period.

**Strategy angle:** the discovery step of a copy-trading pipeline — and the category filter is the edge. A wallet at the top of the `'sports'` leaderboard has demonstrated skill in sports markets specifically; follow it there rather than in politics. Comparing `week` vs `all` rankings separates durable performers from hot streaks before you commit to mirroring anyone.

```python theme={null}
from scalarlib import screenPolymarketWallets

# Top 10 wallets by PnL
df = screenPolymarketWallets(limit=10)

# Most active sports traders this week
df = screenPolymarketWallets(category='sports', time_period='week', sort_by='volume')

# Crypto wallets with > $100k PnL this month
df = screenPolymarketWallets(category='crypto', time_period='month', min_value=100000)

# PnL leaderboard in a range
df = screenPolymarketWallets(min_value=10000, max_value=50000)
```

### Parameters

| Parameter     | Type  | Required | Description                                                                                                                  |
| ------------- | ----- | -------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `category`    | str   | No       | `"overall"` (default), `"sports"`, `"crypto"`, `"politics"`, `"culture"`, `"weather"`, `"economics"`, `"tech"`, `"finance"`. |
| `time_period` | str   | No       | `"all"` (default), `"month"`, `"week"`, `"day"`.                                                                             |
| `sort_by`     | str   | No       | `"pnl"` (default) or `"volume"`.                                                                                             |
| `min_value`   | float | No       | Minimum PnL or volume threshold (depends on `sort_by`).                                                                      |
| `max_value`   | float | No       | Maximum PnL or volume threshold.                                                                                             |
| `limit`       | int   | No       | Maximum results (default 50).                                                                                                |
| `offset`      | int   | No       | Pagination offset (default 0).                                                                                               |

### Return Schema

| Column          | Type   | Description                    |
| --------------- | ------ | ------------------------------ |
| `rank`          | int    | Leaderboard rank               |
| `wallet`        | string | Wallet address                 |
| `pnl`           | float  | Profit and loss (USD)          |
| `volume`        | float  | Total trading volume (USD)     |
| `username`      | string | Polymarket username            |
| `profile_image` | string | Profile image URL              |
| `verified`      | bool   | Whether the wallet is verified |
| `x_username`    | string | X (Twitter) username           |

***

## `getPolymarketPositions()`

Open and closed positions for a wallet in prediction markets, or all holders of a specific market. At least one of `wallet` or `token_id` is required.

**Strategy angle:** two strategies in one function. In **wallet mode**, poll a top trader's open positions on a schedule and trade the changes — new positions and exits are the copy-trading signal. In **token mode**, map who holds each side of a market you are researching: if the largest, most profitable holders are concentrated on one outcome, that is a smart-money positioning signal; `realized_pnl` on closed positions shows who exited early — and whether they were right.

```python theme={null}
from scalarlib import getPolymarketPositions

# Wallet's open positions
df = getPolymarketPositions(wallet='0x6a72...')

# Wallet's closed (resolved) positions
df = getPolymarketPositions(wallet='0x6a72...', status='closed', sort_by='realized_pnl')

# All holders of a market
df = getPolymarketPositions(token_id='7546712961...')

# Biggest holders by size
df = getPolymarketPositions(token_id='7546712961...', sort_by='size')

# A specific wallet's position in a market
df = getPolymarketPositions(wallet='0x6a72...', token_id='7546712961...')

# Who exited a market?
df = getPolymarketPositions(token_id='7546712961...', status='closed', sort_by='realized_pnl')
```

### Parameters

| Parameter   | Type | Required | Description                                                                                              |
| ----------- | ---- | -------- | -------------------------------------------------------------------------------------------------------- |
| `wallet`    | str  | No\*     | Wallet address, 0x-prefixed. \*At least one of `wallet` or `token_id` required.                          |
| `token_id`  | str  | No\*     | Outcome token ID from `screenPolymarkets()`. \*At least one of `wallet` or `token_id` required.          |
| `event_id`  | int  | No       | Filter by event ID.                                                                                      |
| `status`    | str  | No       | `"open"` (default), `"closed"`, or `"all"`.                                                              |
| `sort_by`   | str  | No       | `"size"` (default), `"pnl"`, `"percent_pnl"`, `"realized_pnl"`, `"price"`, `"avg_price"`, `"total_pnl"`. |
| `ascending` | bool | No       | `False` = largest first (default).                                                                       |
| `limit`     | int  | No       | Maximum results (default 100).                                                                           |
| `offset`    | int  | No       | Pagination offset (default 0).                                                                           |

### Return Schema

Columns vary depending on the query:

**By wallet (open positions):**

| Column          | Type     | Description               |
| --------------- | -------- | ------------------------- |
| `wallet`        | string   | Wallet address            |
| `asset`         | string   | Token identifier          |
| `condition_id`  | string   | Market condition ID       |
| `size`          | float    | Position size (shares)    |
| `avg_price`     | float    | Average entry price       |
| `initial_value` | float    | Cost basis                |
| `current_value` | float    | Current market value      |
| `cash_pnl`      | float    | Unrealized P\&L           |
| `percent_pnl`   | float    | P\&L percentage           |
| `realized_pnl`  | float    | Realized P\&L             |
| `cur_price`     | float    | Current price             |
| `title`         | string   | Market question           |
| `outcome`       | string   | Outcome name (e.g. "Yes") |
| `outcome_index` | int      | Outcome index             |
| `event_slug`    | string   | Event URL slug            |
| `end_date`      | datetime | Market end date           |

**By wallet (closed positions):**

| Column          | Type   | Description            |
| --------------- | ------ | ---------------------- |
| `wallet`        | string | Wallet address         |
| `asset`         | string | Token identifier       |
| `condition_id`  | string | Market condition ID    |
| `avg_price`     | float  | Average entry price    |
| `total_bought`  | float  | Total shares purchased |
| `realized_pnl`  | float  | Realized P\&L          |
| `cur_price`     | float  | Settlement price       |
| `title`         | string | Market question        |
| `outcome`       | string | Outcome name           |
| `outcome_index` | int    | Outcome index          |
| `event_slug`    | string | Event URL slug         |

**By token\_id (all holders):**

| Column          | Type   | Description                        |
| --------------- | ------ | ---------------------------------- |
| `wallet`        | string | Holder wallet address              |
| `name`          | string | Polymarket username                |
| `profile_image` | string | Profile image URL                  |
| `verified`      | bool   | Whether verified                   |
| `asset`         | string | Token identifier                   |
| `avg_price`     | float  | Average entry price                |
| `size`          | float  | Position size                      |
| `cur_price`     | float  | Current price                      |
| `current_value` | float  | Current market value               |
| `cash_pnl`      | float  | Unrealized P\&L                    |
| `realized_pnl`  | float  | Realized P\&L                      |
| `total_pnl`     | float  | Total P\&L (unrealized + realized) |
| `outcome`       | string | Outcome name                       |
| `outcome_index` | int    | Outcome index                      |

***

## `getPolymarketProfile()`

Trader profile information for a Polymarket wallet.

**Strategy angle:** the vetting step before copying a wallet. `portfolio_value` and `markets_traded` distinguish a seasoned trader with broad experience from a one-market lottery winner, and `created_at` reveals whether a strong PnL was earned over years or weeks.

```python theme={null}
from scalarlib import getPolymarketProfile

df = getPolymarketProfile(wallet='0x6a72...')
print(df.iloc[0]['portfolio_value'])
print(df.iloc[0]['name'], df.iloc[0]['verified'])
```

### Parameters

| Parameter | Type | Required | Description                  |
| --------- | ---- | -------- | ---------------------------- |
| `wallet`  | str  | Yes      | Wallet address, 0x-prefixed. |

### Return Schema

Returns a single-row DataFrame:

| Column            | Type     | Description                           |
| ----------------- | -------- | ------------------------------------- |
| `wallet`          | string   | Wallet address                        |
| `name`            | string   | Display name                          |
| `pseudonym`       | string   | Pseudonym                             |
| `bio`             | string   | Profile bio                           |
| `profile_image`   | string   | Profile image URL                     |
| `verified`        | bool     | Whether the account is verified       |
| `x_username`      | string   | X (Twitter) username                  |
| `created_at`      | datetime | Account creation date (New York time) |
| `portfolio_value` | float    | Total portfolio value (USD)           |
| `markets_traded`  | int      | Number of markets traded              |

# Strategy Playbook

Concrete ways to combine these functions into a strategy:

* **Copy-trading.** `screenPolymarketWallets(category=...)` to shortlist category specialists, `getPolymarketProfile()` and closed positions from `getPolymarketPositions()` to vet their history, then poll `getPolymarketTrades(wallets=[...])` and mirror new trades via `venue.trade()` on the Polymarket venue.
* **Whale-flow momentum.** `getPolymarketTrades(min_usdc_value=50000)` as a rolling scanner for large one-sided flow; confirm with `getPolymarketPriceAndBook()` that the book still offers a reasonable entry, and size against visible depth.
* **Favorite convergence.** Screen for high-volume markets trading at 0.85–0.95, backtest resolution convergence with `getPolymarketOHLCV()` on resolved markets (`closed=True`, using `winning_outcome_index`), and hold near-certain outcomes to resolution while managing tail risk.
* **Cross-market consistency.** Related markets (same event, different framings or thresholds) imply probability relationships that must hold. Screen them together with `screenPolymarkets()`, compare `market_outcome_prices`, and trade violations when book depth on both legs supports it.
* **Prediction prices as signals elsewhere.** Markets on rate decisions, elections, or crypto milestones produce clean probability series via `getPolymarketOHLCV()` — usable as features in strategies that execute in equities (Alpaca) or crypto (Hyperliquid, Jupiter) rather than on Polymarket itself.