Polymarket

Polymarket decentralized prediction market integration adapter.

This subpackage provides instrument providers, data and execution client configurations, factories, constants, and credential helpers for connecting to and interacting with the Polymarket Central Limit Order Book (CLOB) API.

For convenience, the most commonly used symbols are re-exported at the subpackage’s top level, so downstream code can simply import from posei_trader.adapters.polymarket.

class PolymarketDataClientConfig

Bases: LiveDataClientConfig

Configuration for PolymarketDataClient instances.

• Parameters:
  • venue (Venue , default POLYMARKET_VENUE) – The venue for the client.
  • private_key (str , optional) – The private key for the wallet on the Polygon network. If None then will source the POLYMARKET_PK environment variable.
  • signature_type (int , default 0 *(*EOA )) – The Polymarket signature type.
  • funder (str , optional) – The wallet address (public key) on the Polygon network used for funding USDC. If None then will source the POLYMARKET_FUNDER environment variable.
  • api_key (str , optional) – The Polymarket API public key. If None then will source the POLYMARKET_API_KEY environment variable.
  • api_secret (str , optional) – The Polymarket API public key. If None then will source the POLYMARKET_API_SECRET environment variable.
  • passphrase (str , optional) – The Polymarket API passphrase. If None then will source the POLYMARKET_PASSPHRASE environment variable.
  • base_url_http (str , optional) – The HTTP client custom endpoint override.
  • base_url_ws (str , optional) – The WebSocket client custom endpoint override.
  • ws_connection_initial_delay_secs (PositiveFloat , default 5) – The delay (seconds) prior to the first websocket connection to allow initial subscriptions to arrive.
  • ws_connection_delay_secs (PositiveFloat , default 0.1) – The delay (seconds) prior to making a new websocket connection to allow non-initial subscriptions to arrive.
  • update_instruments_interval_mins (PositiveInt or None , default 60) – The interval (minutes) between updating Polymarket instruments.
  • compute_effective_deltas (bool , default False) – If True, computes effective deltas by comparing old and new order book states, reducing snapshot size. This takes ~1 millisecond, so is not recommended for latency-sensitive strategies.

api_key : str | None

api_secret : str | None

base_url_http : str | None

base_url_ws : str | None

compute_effective_deltas : bool

funder : str | None

passphrase : str | None

private_key : str | None

signature_type : int

update_instruments_interval_mins : Annotated[int, msgspec.Meta(gt=0)] | None

venue : Venue

ws_connection_delay_secs : Annotated[float, msgspec.Meta(gt=0.0)]

ws_connection_initial_delay_secs : Annotated[float, msgspec.Meta(gt=0.0)]

dict() → dict[str, Any]

Return a dictionary representation of the configuration.

• Return type: dict[str, Any]

classmethod fully_qualified_name() → str

Return the fully qualified name for the NautilusConfig class.

• Return type: str

handle_revised_bars : bool

property id : str

Return the hashed identifier for the configuration.

• Return type: str

instrument_provider : InstrumentProviderConfig

json() → bytes

Return serialized JSON encoded bytes.

• Return type: bytes

json_primitives() → dict[str, Any]

Return a dictionary representation of the configuration with JSON primitive types as values.

• Return type: dict[str, Any]

classmethod json_schema() → dict[str, Any]

Generate a JSON schema for this configuration class.

• Return type: dict[str, Any]

classmethod parse(raw: bytes | str) → Any

Return a decoded object of the given cls.

• Parameters:
  • cls (type) – The type to decode to.
  • raw (bytes or str) – The raw bytes or JSON string to decode.
• Return type: Any

routing : RoutingConfig

validate() → bool

Return whether the configuration can be represented as valid JSON.

• Return type: bool

class PolymarketExecClientConfig

Bases: LiveExecClientConfig

Configuration for PolymarketExecutionClient instances.

• Parameters:
  • venue (Venue , default POLYMARKET_VENUE) – The venue for the client.
  • private_key (str , optional) – The private key for the wallet on the Polygon network. If None then will source the POLYMARKET_PK environment variable.
  • signature_type (int , default 0 *(*EOA )) – The Polymarket signature type.
  • funder (str , optional) – The wallet address (public key) on the Polygon network used for funding USDC. If None then will source the POLYMARKET_FUNDER environment variable.
  • api_key (str , optional) – The Polymarket API public key. If None then will source the POLYMARKET_API_KEY environment variable.
  • api_secret (str , optional) – The Polymarket API public key. If None then will source the POLYMARKET_API_SECRET environment variables.
  • passphrase (str , optional) – The Polymarket API passphrase. If None then will source the POLYMARKET_PASSPHRASE environment variable.
  • base_url_http (str , optional) – The HTTP client custom endpoint override.
  • base_url_ws (str , optional) – The WebSocket client custom endpoint override.
  • max_retries (PositiveInt , optional) – The maximum number of times a submit or cancel order request will be retried.
  • retry_delay_initial_ms (PositiveInt , optional) – The initial delay (milliseconds) between retries. Short delays with frequent retries may result in account bans.
  • retry_delay_max_ms (PositiveInt , optional) – The maximum delay (milliseconds) between retries.
  • generate_order_history_from_trades (bool , default False) – If True, uses trades history to generate reports for orders which are no longer active. The Polymarket API only returns active orders and trades. This feature is experimental and is not currently recommended (leave set to False).
  • log_raw_ws_messages (bool , default False) – If raw websocket messages should be logged with debug level. Note: there will be a performance penalty parsing the JSON without an efficient msgspec decoder.

api_key : str | None

api_secret : str | None

base_url_http : str | None

base_url_ws : str | None

funder : str | None

generate_order_history_from_trades : bool

log_raw_ws_messages : bool

max_retries : Annotated[int, msgspec.Meta(gt=0)] | None

passphrase : str | None

private_key : str | None

retry_delay_initial_ms : Annotated[int, msgspec.Meta(gt=0)] | None

retry_delay_max_ms : Annotated[int, msgspec.Meta(gt=0)] | None

signature_type : int

venue : Venue

dict() → dict[str, Any]

Return a dictionary representation of the configuration.

• Return type: dict[str, Any]

classmethod fully_qualified_name() → str

Return the fully qualified name for the NautilusConfig class.

• Return type: str

property id : str

Return the hashed identifier for the configuration.

• Return type: str

instrument_provider : InstrumentProviderConfig

json() → bytes

Return serialized JSON encoded bytes.

• Return type: bytes

json_primitives() → dict[str, Any]

Return a dictionary representation of the configuration with JSON primitive types as values.

• Return type: dict[str, Any]

classmethod json_schema() → dict[str, Any]

Generate a JSON schema for this configuration class.

• Return type: dict[str, Any]

classmethod parse(raw: bytes | str) → Any

Return a decoded object of the given cls.

• Parameters:
  • cls (type) – The type to decode to.
  • raw (bytes or str) – The raw bytes or JSON string to decode.
• Return type: Any

routing : RoutingConfig

validate() → bool

Return whether the configuration can be represented as valid JSON.

• Return type: bool

class PolymarketInstrumentProvider

Bases: InstrumentProvider

Provides Nautilus instrument definitions from Polymarket.

• Parameters:
  • client (ClobClient) – The Polymarket CLOB HTTP client.
  • clock (LiveClock) – The clock instance.
  • config (InstrumentProviderConfig , optional) – The instrument provider configuration, by default None.

add(instrument: Instrument) → None

Add the given instrument to the provider.

• Parameters: instrument (Instrument) – The instrument to add.

add_bulk(instruments: list[Instrument]) → None

Add the given instruments bulk to the provider.

• Parameters: instruments (list [Instrument ]) – The instruments to add.

add_currency(currency: Currency) → None

Add the given currency to the provider.

• Parameters: currency (Currency) – The currency to add.

property count : int

Return the count of instruments held by the provider.

• Return type: int

currencies() → dict[str, Currency]

Return all currencies held by the instrument provider.

• Return type: dict[str, Currency]

currency(code: str) → Currency | None

Return the currency with the given code (if found).

• Parameters: code (str) – The currency code.
• Return type: Currency or None
• Raises: ValueError – If code is not a valid string.

find(instrument_id: InstrumentId) → Instrument | None

Return the instrument for the given instrument ID (if found).

• Parameters: instrument_id (InstrumentId) – The ID for the instrument
• Return type: Instrument or None

get_all() → dict[InstrumentId, Instrument]

Return all loaded instruments as a map keyed by instrument ID.

If no instruments loaded, will return an empty dict.

• Return type: dict[InstrumentId, Instrument]

async initialize(reload: bool = False) → None

Initialize the instrument provider.

• Parameters: reload (bool , default False) – If True, then will always reload instruments. If False, then will immediately return if already loaded.

list_all() → list[Instrument]