Polymarket Python Order Utilities

Warnings

• breaking Breaking change in cryptographic dependencies. Version 0.3.1 replaced `pysha3` with compatible libraries.
  Fix: Users upgrading from versions prior to 0.3.1 should ensure their environment is free of `pysha3` dependencies if experiencing import errors or unexpected behavior. The library now uses standard `web3.py` and `eth-account` cryptographic primitives internally, which should resolve compatibility issues.
• breaking Major contract migrations (e.g., to Amoy testnet) frequently require updates to contract addresses and ABIs.
  Fix: Always use the latest stable version of `py-order-utils`. Ensure that `EXCHANGE_ADDRESS`, `CHAIN_ID`, and any token/market addresses used in `OrderData` are up-to-date with the current Polymarket deployment. Refer to Polymarket's official documentation or contract repositories for the latest addresses.
• gotcha Signature formatting for submissions must include the '0x' prefix.
  Fix: As of v0.3.2, the library explicitly forces the signature to include the '0x' prefix. If manually handling signatures or using older versions, ensure the signature string is prefixed with '0x' before sending to APIs or contracts.
• breaking Frequent updates to `OrderData` schema, including new required fields like `minAmountReceived` and `timeInForce`.
  Fix: Always review the `OrderData` model definition in the library or the latest release notes when upgrading. Ensure all required fields are present and correctly formatted in your order payloads to avoid validation errors.

Install

• pip install py-order-utils Install with pip

Imports

• OrderBuilder

  from py_order_utils.builders import OrderBuilder

• Signer

  from py_order_utils.signer import Signer

• OrderData

  from py_order_utils.models import OrderData

  Assumed path based on common Python package structure for models/data classes. Not explicitly shown in quickstart snippet but necessary.

Quickstart

This quickstart demonstrates how to initialize the `Signer` and `OrderBuilder` classes, construct a sample `OrderData` object with placeholder values, and generate a signed order suitable for submission to Polymarket's CLOB API. Ensure environment variables for `POLYMARKET_PRIVATE_KEY`, `POLYMARKET_RPC_URL`, `POLYMARKET_EXCHANGE_ADDRESS`, and `POLYMARKET_CHAIN_ID` are set for a runnable example.

import os
import json
from web3 import Web3
from py_order_utils.builders import OrderBuilder
from py_order_utils.signer import Signer
from py_order_utils.models import OrderData, SignedOrder

# Configuration (replace with your actual values or environment variables)
PRIVATE_KEY = os.environ.get('POLYMARKET_PRIVATE_KEY', '0x...') # Your Ethereum private key
RPC_URL = os.environ.get('POLYMARKET_RPC_URL', 'https://rpc-amoy.polygon.technology/') # e.g., Polygon Amoy RPC URL
EXCHANGE_ADDRESS = os.environ.get('POLYMARKET_EXCHANGE_ADDRESS', '0x...') # Polymarket CLOB Exchange Contract Address
CHAIN_ID = int(os.environ.get('POLYMARKET_CHAIN_ID', '80002')) # e.g., 80002 for Polygon Amoy

def main():
    if PRIVATE_KEY == '0x...' or EXCHANGE_ADDRESS == '0x...':
        print("Please configure POLYMARKET_PRIVATE_KEY, POLYMARKET_RPC_URL, EXCHANGE_ADDRESS, and CHAIN_ID environment variables.")
        return

    w3 = Web3(Web3.HTTPProvider(RPC_URL))
    if not w3.is_connected():
        print(f"Failed to connect to RPC at {RPC_URL}")
        return

    print(f"Connected to chain ID: {w3.eth.chain_id}")
    
    signer_instance = Signer(PRIVATE_KEY)
    builder = OrderBuilder(EXCHANGE_ADDRESS, CHAIN_ID, signer_instance)

    # Example OrderData payload (replace with actual order parameters)
    order_data = OrderData(
        maker='0x' + signer_instance.address[2:], # Your wallet address
        taker='0x0000000000000000000000000000000000000000', # Taker address (0x0 for open orders)
        longToken='0x...', # Address of the long token for the market
        shortToken='0x...', # Address of the short token for the market
        longTokenAmount='1000000000000000000', # 1 Long Token (example: 1e18 wei)
        shortTokenAmount='500000000000000000', # 0.5 Short Token (example: 0.5e18 wei)
        salt=w3.eth.get_block('latest').number, # Unique salt for the order
        expiry=w3.eth.get_block('latest').timestamp + 3600, # Expires in 1 hour
        feeRate='0', # Example fee rate
        isPostOnly=False,
        market='0x...', # Market contract address
        minAmountReceived='0' # Minimum amount to receive
    )

    try:
        # Create and sign the order
        signed_order: SignedOrder = builder.build_signed_order(order_data)

        # Generate the Order and Signature JSON to be sent to the CLOB API
        print("\n--- Signed Order JSON ---")
        print(json.dumps(signed_order.dict(), indent=2))

    except Exception as e:
        print(f"An error occurred: {e}")

if __name__ == '__main__':
    main()