Polymarket¶
This page documents the Polymarket adapter module in nautilus_trader.adapters.polymarket.
Integration adapter for Polymarket.
- class PolymarketCryptoPrice¶
Bases:
objectPolymarket 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:
objectChainlink-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:
objectConfiguration 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:
objectFactory 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.
- static query_search(query, events_status=None, events_tag=None, sort=None, ascending=None, limit_per_type=None, page=None, keep_closed_markets=None, base_url_gamma=None, timeout_secs=10)¶
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 outcome asset ID.
- class PolymarketEquityPrice¶
Bases:
objectPolymarket 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:
objectConfiguration 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:
objectFactory for creating Polymarket execution clients.
- name()¶
- class PolymarketFeeModel¶
Bases:
FeeModelPolymarket 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:
objectConfiguration 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:
objectDeposit Wallet client for split, merge, and redeem position operations.
- approve_v2_trading(collateral_limit)¶
Approves ExchangeV3 trading from the Deposit Wallet holding the assets.
collateral_limit is an explicit pUSD limit covering BUY spend plus fees. The same batch enables ExchangeV3 to transfer V2 positions for SELL orders. It does not redeem positions. The Relayer requires unlimited ExchangeV3 approvals and rejects this bounded request. V2 trading from a Deposit Wallet therefore requires existing approvals.
# Errors
Returns an error if the limit is invalid, wallet verification fails, or Relayer submission is rejected or ambiguous. A pending wallet submission must be reconciled before retrying.
- merge_positions(condition_id, amount)¶
Merges amount complete sets of outcome tokens back into pUSD.
- redeem_position(condition_id, outcome_index, amount)¶
Redeems an explicit six-decimal share amount of V2 outcome index 0 or 1.
The index is the position ID’s final byte, independent of CLOB token-array order. Reverted or unavailable payout reads fail before submission. Zero losing payouts are valid.
- redeem_positions(condition_id)¶
Redeems both CTF binary outcome balances for a resolved market.
- redeem_positions_batch(condition_ids)¶
- split_position(condition_id, amount)¶
Splits amount pUSD into a complete set of outcome tokens.
- class PolymarketPositionOutcome¶
Bases:
objectTerminal 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:
objectSubmitted 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 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:
objectEIP-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:
objectRole of the private key used to sign orders, independent of the wallet signature format.
- Owner = PolymarketSignerType.Owner¶
- Session = PolymarketSignerType.Session¶
- class PolymarketUpDownEventSlugConfig¶
Bases:
objectRust-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¶