Polymarket

This page documents the Polymarket adapter module in nautilus_trader.adapters.polymarket.

Integration adapter for Polymarket.

class PolymarketCryptoPrice

Bases: object

Polymarket PolyBolt crypto spot price sample from the price.crypto channel.

The adapter normalizes both live frames and the two-minute subscription snapshot into this per-tick custom data type.

classmethod from_json(data)
message_timestamp_ms
price_timestamp_ms
source
symbol
to_json()
ts_event
ts_init
value
class PolymarketCryptoTwap

Bases: object

Chainlink-computed 60-second crypto TWAP sample from the price.crypto.twap channel.

The adapter derives value only from the exact full_accuracy_value field. The numeric display field in the payload is validated but never authoritative.

Subscriptions begin with a two-minute snapshot and continue with live updates. The adapter suppresses older observations and exact same-timestamp redeliveries, including snapshot replay after a reconnect. A changed value at the same observation timestamp is reported as a protocol error and is not emitted; the previous observation remains authoritative, so emission resumes only at a newer timestamp in a subsequent frame. Snapshot processing stops at the first conflicting or invalid point and discards the remaining points in that frame.

classmethod from_json(data)
message_timestamp_ms
observation_timestamp_ms
source
symbol
to_json()
ts_event
ts_init
value
window_seconds
class PolymarketDataClientConfig

Bases: object

Configuration for the Polymarket data client.

filters and new_market_filter hold Arc<dyn InstrumentFilter> trait objects and are skipped during serialization; they default to empty/None and must be installed programmatically after deserialization.

auto_load_debounce_ms
auto_load_max_retries
auto_load_missing_instruments
auto_load_retry_delay_initial_secs
auto_load_retry_delay_max_secs
base_url_data_api
base_url_gamma
base_url_http
base_url_reference_prices
base_url_ws
book_snapshot_timeout_secs
book_stale_check_interval_secs
book_stale_threshold_secs
compute_effective_deltas
drop_quotes_missing_side
has_proxy_url
http_timeout_secs
instrument_config
new_market_fetch_max_concurrency
resolve_poll_enabled
resolve_poll_grace_secs
resolve_poll_interval_secs
resolve_poll_max_wait_secs
subscribe_new_markets
transport_backend
update_instruments_interval_mins
ws_max_subscriptions
ws_timeout_secs
class PolymarketDataClientFactory

Bases: object

Factory for creating Polymarket data clients.

name()
class PolymarketDataLoader

Bases: object

condition_id

Returns the on-chain condition ID.

static from_event_slug(slug, token_index=0, base_url_http=None, base_url_gamma=None, base_url_data_api=None, timeout_secs=10)

Creates one loader for every market in a Gamma event slug.

static from_market_slug(slug, token_index=0, base_url_http=None, base_url_gamma=None, base_url_data_api=None, timeout_secs=10)

Creates one loader from a Gamma market slug.

instrument

Returns the normalized binary option instrument.

load_trades(start=None, end=None, limit=None)

Loads historical trades from the Rust Data API client.

static query_event_by_slug(slug, base_url_gamma=None, timeout_secs=10)

Queries one Gamma event by slug.

static query_events(filters=None, base_url_gamma=None, timeout_secs=10)

Lists Gamma events with validated filters and keyset pagination.

static query_market_by_slug(slug, base_url_gamma=None, timeout_secs=10)

Queries one Gamma market by slug.

static query_market_details(condition_id, base_url_http=None, timeout_secs=10)

Queries public CLOB market details by condition ID.

static query_markets(filters=None, base_url_gamma=None, timeout_secs=10)

Lists Gamma markets with validated filters and keyset pagination.

Searches Gamma markets and events.

static query_tags(base_url_gamma=None, timeout_secs=10)

Lists Gamma tags.

resolution_metadata

Returns resolution lifecycle metadata retained separately from instrument.info.

Shared market identity such as resolutionSource is also available from instrument.info[“resolution_source”].

token_id

Returns the selected CLOB token ID.

class PolymarketEquityPrice

Bases: object

Polymarket PolyBolt equity price sample from the price.equity channel.

Covers equities, ETFs, forex pairs, metals, and commodities. The adapter normalizes both live frames and the two-minute subscription snapshot into this per-tick custom data type.

classmethod from_json(data)
is_carried_forward
message_timestamp_ms
price_timestamp_ms
received_at_ms
source
symbol
to_json()
ts_event
ts_init
value
class PolymarketExecutionClientConfig

Bases: object

Configuration for the Polymarket execution client.

account_id
base_url_data_api
base_url_http
base_url_ws
funder
has_proxy_url
heartbeat_enabled
http_timeout_secs
instrument_config
max_retries
retry_delay_initial_ms
retry_delay_max_ms
signature_type
signer_type
transport_backend
class PolymarketExecutionClientFactory

Bases: object

Factory for creating Polymarket execution clients.

name()
class PolymarketFeeModel

Bases: FeeModel

Polymarket fee model for binary-option backtests.

Taker fills pay the market’s fee-equivalent amount. Maker fills receive a per-fill approximation of the daily maker rebate by applying the market’s configured rebate rate to that fee-equivalent amount.

get_commission(order, fill_quantity, fill_px, instrument)
get_commission_with_context(order, fill_quantity, fill_px, instrument, _underlying_px=None)
class PolymarketInstrumentProviderConfig

Bases: object

Configuration for the Polymarket instrument provider.

This mirrors the Python adapter’s instrument_config layering so scoped market bootstrap can migrate naturally to the Rust/pyO3 live path.

event_slug_builder
event_slugs
filters
load_all
load_ids
log_warnings
market_slugs
series_ids
use_gamma_markets
class PolymarketPositionClient

Bases: object

Deposit Wallet client for split, merge, and redeem position operations.

merge_positions(condition_id, amount)

Merges amount complete sets of outcome tokens back into pUSD.

redeem_positions(condition_id)

Redeems both binary outcome balances for a resolved market.

split_position(condition_id, amount)

Splits amount pUSD into a complete set of outcome tokens.

class PolymarketPositionOutcome

Bases: object

Terminal result of a Polymarket split, merge, or redeem operation.

error_msg

Relayer error detail when present.

status

confirmed, failed, or invalid.

Type:

Relayer terminal status

transaction_hash

On-chain transaction hash when the Relayer supplied one.

transaction_id

Relayer transaction identifier.

class PolymarketPositionTransaction

Bases: object

Submitted position operation that can be polled to a terminal Relayer state.

transaction_id

Relayer transaction identifier returned at submit time.

wait()

Polls the Relayer until the transaction is confirmed, failed, or invalid.

class PolymarketSessionKey

Bases: object

address
scopes
valid_until
class PolymarketSessionKeyClient

Bases: object

authorize_session_key(address)
list_session_keys()
revoke_session_key(address)
class PolymarketSessionKeyClientConfig

Bases: object

base_url_http
base_url_relayer
funder
has_proxy_url
class PolymarketSignatureType

Bases: object

EIP-712 signature type for order signing.

Serialized as a numeric value (0/1/2/3) on the wire.

Eoa = PolymarketSignatureType.Eoa
Poly1271 = PolymarketSignatureType.Poly1271
PolyGnosisSafe = PolymarketSignatureType.PolyGnosisSafe
PolyProxy = PolymarketSignatureType.PolyProxy
class PolymarketSignerType

Bases: object

Role of the private key used to sign orders, independent of the wallet signature format.

Owner = PolymarketSignerType.Owner
Session = PolymarketSignerType.Session
class PolymarketUpDownEventSlugConfig

Bases: object

Rust-backed event slug builder for Polymarket Up/Down markets.

Up/Down event slugs follow the pattern {asset}-updown-{interval_mins}m-{unix_timestamp}, where the timestamp is aligned to the start of the interval. The builder emits slugs for each configured asset and period.

assets
interval_mins
periods
start_offset_periods