polymarket-apis 0.2.2__py3-none-any.whl

polymarket_apis/types/gamma_types.py

@@ -0,0 +1,313 @@
+from __future__ import annotations
+
+from datetime import datetime
+
+from pydantic import (
+    BaseModel,
+    Field,
+    Json,
+    ValidationInfo,
+    ValidatorFunctionWrapHandler,
+    field_validator,
+)
+
+from .common import EthAddress, Keccak256, TimestampWithTZ
+
+
+class Event(BaseModel):
+    # Basic identification
+    id: str
+    slug: str
+    ticker: str | None = None
+
+    # Core event information
+    title: str
+    description: str | None = None
+    resolution_source: str | None = Field(None, alias="resolutionSource")
+    category: str | None = None
+
+    # Visual representation
+    image: str | None = None
+    icon: str | None = None
+
+    # Temporal information
+    start_date: datetime | None = Field(None, alias="startDate")
+    end_date: datetime | None = Field(None, alias="endDate")
+    creation_date: datetime | None = Field(None, alias="creationDate")
+    created_at: datetime = Field(alias="createdAt")
+    updated_at: datetime | None = Field(None, alias="updatedAt")
+    published_at: TimestampWithTZ | None = None
+    closed_time: datetime | None = Field(None, alias="closedTime")
+
+    # Status flags
+    active: bool
+    closed: bool
+    archived: bool | None = None
+    new: bool | None = None
+    featured: bool | None = None
+    restricted: bool | None = None
+    cyom: bool
+    automatically_active: bool | None = Field(None, alias="automaticallyActive")
+
+    # Financial metrics
+    liquidity: float | None = None
+    volume: float | None = None
+    open_interest: int | None = Field(None, alias="openInterest")
+    competitive: float | None = None
+    volume_24hr: float | None = Field(None, alias="volume24hr")
+    liquidity_amm: float | None = Field(None, alias="liquidityAmm")
+    liquidity_clob: float | None = Field(None, alias="liquidityClob")
+
+    # Related data
+    markets: list[GammaMarket] | None = None
+    series: list[Series] | None = None
+    tags: list[Tag] | None = None
+
+    # User interaction
+    comment_count: int | None = Field(None, alias="commentCount")
+
+    # Display and functionality settings
+    sort_by: str | None = Field(None, alias="sortBy")
+    show_all_outcomes: bool = Field(alias="showAllOutcomes")
+    show_market_images: bool = Field(alias="showMarketImages")
+    gmp_chart_mode: str | None = Field(None, alias="gmpChartMode")
+
+    # Negative risk settings
+    enable_neg_risk: bool = Field(alias="enableNegRisk")
+    neg_risk: bool | None = Field(None, alias="negRisk")
+    neg_risk_market_id: str | None = Field(None, alias="negRiskMarketID")
+    neg_risk_augmented: bool | None = Field(None, alias="negRiskAugmented")
+
+    # Order book settings
+    enable_order_book: bool | None = Field(None, alias="enableOrderBook")
+
+
+class GammaMarket(BaseModel):
+    # Basic identification
+    id: str
+    slug: str
+    condition_id: Keccak256 = Field(alias="conditionId")
+    question_id: Keccak256 | None = Field(None, alias="questionID")
+
+    # Core market information
+    question: str
+    description: str
+    resolution_source: str | None = Field(None, alias="resolutionSource")
+    outcome: list | None = None
+    outcome_prices: Json[list[float]] | list[float] | None = Field(None, alias="outcomePrices")
+
+    # Visual representation
+    image: str | None = None
+    icon: str | None = None
+
+    # Temporal information
+    start_date: datetime | None = Field(None, alias="startDate")
+    end_date: datetime | None = Field(None, alias="endDate")
+    created_at: datetime = Field(alias="createdAt")
+    updated_at: datetime | None = Field(None, alias="updatedAt")
+    start_date_iso: datetime | None = Field(None, alias="startDateIso")
+    end_date_iso: datetime | None = Field(None, alias="endDateIso")
+    deployed_timestamp: datetime | None = Field(None, alias="deployedTimestamp")
+    accepting_orders_timestamp: datetime | None = Field(
+        None, alias="acceptingOrdersTimestamp",
+    )
+
+    # Status flags
+    active: bool
+    closed: bool
+    archived: bool
+    new: bool | None = None
+    featured: bool | None = None
+    restricted: bool
+    ready: bool
+    deployed: bool | None = None
+    funded: bool
+    cyom: bool
+    approved: bool
+
+    # Financial metrics
+    liquidity: float | None = None
+    volume: float | None = None
+    volume_num: float | None = Field(None, alias="volumeNum")
+    liquidity_num: float | None = Field(None, alias="liquidityNum")
+    volume_24hr: float | None = Field(None, alias="volume24hr")
+    volume_24hr_clob: float | None = Field(None, alias="volume24hrClob")
+    volume_clob: float | None = Field(None, alias="volumeClob")
+    liquidity_clob: float | None = Field(None, alias="liquidityClob")
+    competitive: float | None = None
+    spread: float
+
+    # Order book settings
+    enable_order_book: bool | None = Field(None, alias="enableOrderBook")
+    order_price_min_tick_size: float | None = Field(
+        None, alias="orderPriceMinTickSize",
+    )
+    order_min_size: float | None = Field(None, alias="orderMinSize")
+    accepting_orders: bool | None = Field(None, alias="acceptingOrders")
+
+    # Related data
+    events: list[Event] | None = None
+    clob_rewards: list[ClobReward] | None = Field(None, alias="clobRewards")
+
+    # User interaction
+    comment_count: int | None = Field(None, alias="commentCount")
+
+    # Market maker information
+    market_maker_address: str = Field(alias="marketMakerAddress")
+
+    # Additional settings
+    group_item_title: str | None = Field(None, alias="groupItemTitle")
+    group_item_threshold: int | None = Field(None, alias="groupItemThreshold")
+    token_ids: Json[list[str]] | list[str] | None = Field(None, alias="clobTokenIds")
+    uma_bond: int | None = Field(None, alias="umaBond")
+    uma_reward: float | None = Field(None, alias="umaReward")
+    neg_risk: bool | None = Field(None, alias="negRisk")
+    pager_duty_notification_enabled: bool = Field(alias="pagerDutyNotificationEnabled")
+    review_status: str | None = Field(None, alias="reviewStatus")
+    rewards_min_size: int = Field(alias="rewardsMinSize")
+    rewards_max_spread: float = Field(alias="rewardsMaxSpread")
+
+    # Resolution information
+    submitted_by: str | None = None
+    resolved_by: EthAddress | None = Field(None, alias="resolvedBy")
+    has_reviewed_dates: bool | None = Field(None, alias="hasReviewedDates")
+
+    @field_validator("condition_id", mode="wrap")
+    @classmethod
+    def validate_condition_id(
+            cls, value: str, handler: ValidatorFunctionWrapHandler, info: ValidationInfo,
+    ) -> str:
+        try:
+            # First attempt standard Keccak256 validation
+            return handler(value)
+        except ValueError:
+            active = info.data.get("active", False)
+
+            # Only allow empty string when inactive
+            if not active and value == "":
+                return value
+
+            # Re-raise original error for other cases
+            raise
+
+class ClobReward(BaseModel):
+    # Basic identification
+    id: str
+    condition_id: Keccak256 = Field(alias="conditionId")
+
+    # Reward information
+    asset_address: str = Field(alias="assetAddress")
+    rewards_amount: float = Field(alias="rewardsAmount")
+    rewards_daily_rate: float | None = Field(None, alias="rewardsDailyRate")
+
+    # Temporal information
+    start_date: datetime = Field(alias="startDate")
+    end_date: datetime = Field(alias="endDate")
+
+
+class Tag(BaseModel):
+    # Basic identification
+    id: str
+    label: str
+    slug: str
+
+    # Display settings
+    force_show: bool | None = Field(None, alias="forceShow")
+    force_hide: bool | None = Field(None, alias="forceHide")
+
+    # Temporal information
+    published_at: TimestampWithTZ | datetime | None = Field(None, alias="publishedAt")
+    created_at: datetime | None = Field(None, alias="createdAt")
+    updated_at: datetime | None = Field(None, alias="updatedAt")
+
+    # User information
+    created_by: int | None = Field(None, alias="createdBy")
+    updated_by: int | None = Field(None, alias="updatedBy")
+
+
+class Series(BaseModel):
+    # Basic identification
+    id: str
+    slug: str
+    ticker: str
+    title: str
+
+    # Series characteristics
+    series_type: str | None = Field(None,  alias="seriesType")
+    recurrence: str | None = None
+    layout: str | None = None
+
+    # Visual representation
+    icon: str | None = None
+    image: str | None = None
+
+    # Temporal information
+    start_date: datetime | None = Field(None, alias="startDate")
+    created_at: datetime = Field(alias="createdAt")
+    updated_at: datetime | None = Field(None, alias="updatedAt")
+    published_at: TimestampWithTZ | datetime | None = Field(None, alias="publishedAt")
+
+    # Status flags
+    active: bool | None = None
+    archived: bool | None = None
+    closed: bool | None = None
+    featured: bool | None = None
+    new: bool | None = None
+    restricted: bool | None = None
+
+    # Financial metrics
+    liquidity: float | None = None
+    volume: float | None = None
+    volume_24hr: float | None = Field(None, alias="volume24hr")
+    competitive: str | None = None
+
+    # User interaction
+    comment_count: int = Field(alias="commentCount")
+    comments_enabled: bool | None = Field(None, alias="commentsEnabled")
+
+    # User information
+    created_by: str | None = Field(None, alias="createdBy")
+    updated_by: str | None = Field(None, alias="updatedBy")
+
+
+class QueryEvent(BaseModel):
+    # Basic identification
+    id: str
+    slug: str
+    title: str
+
+    # Visual representation
+    image: str | None = None
+
+    # Status flags
+    active: bool
+    closed: bool
+    archived: bool
+    neg_risk: bool | None = Field(None, alias="negRisk")
+
+    # Temporal information
+    start_date: datetime | None = Field(None, alias="startDate")
+    end_date: datetime | None = Field(None, alias="endDate")
+    ended: bool
+
+    # Related data
+    markets: list[QueryMarket] | None = None
+
+
+class QueryMarket(BaseModel):
+    # Basic identification
+    slug: str
+    question: str
+    group_item_title: str | None = Field(None, alias="groupItemTitle")
+
+    # Market data
+    outcomes: list | None = None
+    outcome_prices: Json[list[float]] | list[float] | None = Field(None, alias="outcomePrices")
+    last_trade_price: float | None = Field(None, alias="lastTradePrice")
+    best_ask: float | None = Field(None, alias="bestAsk")
+    best_bid: float | None = Field(None, alias="bestBid")
+    spread: float
+
+    # Status flags
+    closed: bool
+    archived: bool

polymarket_apis/types/websockets_types.py

@@ -0,0 +1,191 @@
+from datetime import datetime
+from typing import Literal
+
+from pydantic import BaseModel, Field, field_validator
+
+from ..types.clob_types import MakerOrder, OrderBookSummary, PriceLevel, TickSize
+from ..types.common import EthAddress, Keccak256
+
+
+# wss://ws-subscriptions-clob.polymarket.com/ws/market types
+class OrderBookSummaryEvent(OrderBookSummary):
+    event_type: Literal["book"]
+
+class PriceChangeEvent(BaseModel):
+    token_id: str = Field(alias="asset_id")
+    changes: list[PriceLevel]
+    hash: str
+    market: str
+    timestamp: datetime # time of event
+    event_type: Literal["price_change"]
+
+class TickSizeChangeEvent(BaseModel):
+    token_id: str = Field(alias="asset_id")
+    condition_id: Keccak256 = Field(alias="market")
+    old_tick_size: TickSize
+    new_tick_size: TickSize
+    side: Literal["BUY", "SELL"]
+    timestamp: datetime # time of event
+    event_type: Literal["tick_size_change"]
+
+# wss://ws-subscriptions-clob.polymarket.com/ws/user types
+class OrderEvent(BaseModel):
+    token_id: str = Field(alias="asset_id")
+    condition_id: Keccak256 = Field(alias="market")
+    order_id: Keccak256 = Field(alias="id")
+    associated_trades: list[str] | None = None # list of trade ids which
+    maker_address: EthAddress
+    order_owner: str # api key of order owner
+    event_owner: str = Field(alias="owner") # api key of event owner
+
+
+    price: float
+    side: Literal["BUY", "SELL"]
+    size_matched: float
+    original_size: float
+    outcome: str
+    order_type: Literal["GTC", "FOK", "GTD"]
+
+    created_at: datetime
+    expiration: datetime | None = None
+    timestamp: datetime # time of event
+
+    event_type: Literal["order"]
+    type: Literal["PLACEMENT", "UPDATE" , "CANCELLATION"]
+
+    status: Literal["LIVE", "CANCELED", "MATCHED"]
+
+    @field_validator("expiration", mode="before")
+    def validate_expiration(cls, v):
+        if v == "0":
+            return None
+        return v
+
+class TradeEvent(BaseModel):
+    token_id: str = Field(alias="asset_id")
+    condition_id: Keccak256 = Field(alias="market")
+    taker_order_id: Keccak256
+    maker_orders: list[MakerOrder]
+    trade_id: str = Field(alias="id")
+    trade_owner: str # api key of trade owner
+    event_owner: str = Field(alias="owner") # api key of event owner
+
+    price: float
+    size: float
+    side: Literal["BUY", "SELL"]
+    outcome: str
+
+    last_update: datetime # time of last update to trade
+    matchtime: datetime | None = None # time trade was matched
+    timestamp: datetime # time of event
+
+    event_type: Literal["trade"]
+    type: Literal["TRADE"]
+
+    status: Literal["MATCHED", "MINED", "CONFIRMED", "RETRYING", "FAILED"]
+
+# wss://ws-live-data.polymarket.com types
+class LiveDataTrade(BaseModel):
+    token_id: str = Field(alias="asset") # ERC1155 token ID of conditional token being traded
+    condition_id: str = Field(alias="conditionId")  # Id of market which is also the CTF condition ID
+    event_slug: str = Field(alias="eventSlug")  # Slug of the event
+    outcome: str  # Human readable outcome of the market
+    outcome_index: int = Field(alias="outcomeIndex")  # Index of the outcome
+    price: float  # Price of the trade
+    side: Literal["BUY", "SELL"]  # Side of the trade
+    size: float  # Size of the trade
+    slug: str  # Slug of the market
+    timestamp: datetime  # Timestamp of the trade
+    title: str  # Title of the event
+    transaction_hash: str = Field(alias="transactionHash")  # Hash of the transaction
+    proxy_wallet: str = Field(alias="proxyWallet")  # Address of the user proxy wallet
+    icon: str  # URL to the market icon image
+    name: str  # Name of the user of the trade
+    bio: str  # Bio of the user of the trade
+    pseudonym: str  # Pseudonym of the user
+    profile_image: str = Field(alias="profileImage")  # URL to the user profile image
+    profile_image_optimized: str | None = Field(None, alias="profileImageOptimized")
+
+
+class Comment(BaseModel):
+    id: str  # Unique identifier of comment
+    body: str  # Content of the comment
+    parent_entity_type: str = Field(alias="parentEntityType")  # Type of the parent entity (Event or Series)
+    parent_entity_id: int = Field(alias="parentEntityID")  # ID of the parent entity
+    parent_comment_id: str | None = Field(None, alias="parentCommentID")  # ID of the parent comment
+    user_address: str = Field(alias="userAddress")  # Address of the user
+    reply_address: str | None = Field(None, alias="replyAddress")  # Address of the reply user
+    created_at: datetime = Field(alias="createdAt")  # Creation timestamp
+    updated_at: datetime | None = Field(None, alias="updatedAt")  # Last update timestamp
+
+class Reaction(BaseModel):
+    id: str  # Unique identifier of reaction
+    comment_id: int = Field(alias="commentID")  # ID of the comment
+    reaction_type: str = Field(alias="reactionType")  # Type of the reaction
+    icon: str | None = None  # Icon representing the reaction
+    user_address: str = Field(alias="userAddress")  # Address of the user
+    created_at: datetime = Field(alias="createdAt")  # Creation timestamp
+
+class Request(BaseModel):
+    request_id: str = Field(alias="requestId")  # Unique identifier for the request
+    proxy_address: str = Field(alias="proxyAddress")  # Proxy address
+    user_address: str = Field(alias="userAddress")  # User address
+    condition_id: Keccak256 = Field(alias="market")  # Id of market which is also the CTF condition ID
+    token_id: str = Field(alias="token")  # ERC1155 token ID of conditional token being traded
+    complement_token_id: str = Field(alias="complement")  # Complement ERC1155 token ID of conditional token being traded
+    state: Literal["STATE_REQUEST_EXPIRED", "STATE_USER_CANCELED", "STATE_REQUEST_CANCELED", "STATE_MAKER_CANCELED", "STATE_ACCEPTING_QUOTES", "STATE_REQUEST_QUOTED", "STATE_QUOTE_IMPROVED"]  # Current state of the request
+    side: Literal["BUY", "SELL"]  # Indicates buy or sell side
+    price: float  # Price from in/out sizes
+    size_in: float = Field(alias="sizeIn")  # Input size of the request
+    size_out: float = Field(alias="sizeOut")  # Output size of the request
+    expiry: datetime | None = None
+
+class Quote(BaseModel):
+    quote_id: str = Field(alias="quoteId")  # Unique identifier for the quote
+    request_id: str = Field(alias="requestId")  # Associated request identifier
+    proxy_address: str = Field(alias="proxyAddress")  # Proxy address
+    user_address: str = Field(alias="userAddress")  # User address
+    condition_id: Keccak256 = Field(alias="condition")  # Id of market which is also the CTF condition ID
+    token_id: str = Field(alias="token")  # ERC1155 token ID of conditional token being traded
+    complement_token_id: str = Field(alias="complement")  # Complement ERC1155 token ID of conditional token being traded
+    state: Literal["STATE_REQUEST_EXPIRED", "STATE_USER_CANCELED", "STATE_REQUEST_CANCELED", "STATE_MAKER_CANCELED", "STATE_ACCEPTING_QUOTES", "STATE_REQUEST_QUOTED", "STATE_QUOTE_IMPROVED"]  # Current state of the quote
+    side: Literal["BUY", "SELL"]  # Indicates buy or sell side
+    size_in: float = Field(alias="sizeIn")  # Input size of the quote
+    size_out: float = Field(alias="sizeOut")  # Output size of the quote
+    expiry: datetime | None = None
+
+class LiveDataTradeEvent(BaseModel):
+    payload: LiveDataTrade
+    timestamp: datetime
+    type: Literal["trades"]
+    topic: Literal["activity"]
+
+class LiveDataOrderMatchEvent(BaseModel):
+    payload: LiveDataTrade
+    timestamp: datetime
+    type: Literal["orders_matched"]
+    topic: Literal["activity"]
+
+class CommentEvent(BaseModel):
+    payload: Comment
+    timestamp: datetime
+    type: Literal["comment_created", "comment_removed"]
+    topic: Literal["comments"]
+
+class ReactionEvent(BaseModel):
+    payload: Reaction
+    timestamp: datetime
+    type: Literal["reaction_created", "reaction_removed"]
+    topic: Literal["comments"]
+
+class RequestEvent(BaseModel):
+    payload: Request
+    timestamp: datetime
+    type: Literal["request_created", "request_edited", "request_canceled", "request_expired"]
+    topic: Literal["rfq"]
+
+class QuoteEvent(BaseModel):
+    payload: Quote
+    timestamp: datetime
+    type: Literal["quote_created", "quote_edited", "quote_canceled", "quote_expired"]
+    topic: Literal["rfq"]

polymarket_apis/utilities/config.py

@@ -0,0 +1,36 @@
+from ..types.clob_types import ContractConfig
+
+CONFIG = {
+    137: ContractConfig(
+        exchange="0x4bFb41d5B3570DeFd03C39a9A4D8dE6Bd8B8982E",
+        collateral="0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174",
+        conditional_tokens="0x4D97DCd97eC945f40cF65F87097ACe5EA0476045",
+    ),
+    80002: ContractConfig(
+        exchange="0xdFE02Eb6733538f8Ea35D585af8DE5958AD99E40",
+        collateral="0x9c4e1703476e875070ee25b56a58b008cfb8fa78",
+        conditional_tokens="0x69308FB512518e39F9b16112fA8d994F4e2Bf8bB",
+    ),
+}
+
+NEG_RISK_CONFIG = {
+    137: ContractConfig(
+        exchange="0xC5d563A36AE78145C45a50134d48A1215220f80a",
+        collateral="0x2791bca1f2de4661ed88a30c99a7a9449aa84174",
+        conditional_tokens="0x4D97DCd97eC945f40cF65F87097ACe5EA0476045",
+    ),
+    80002: ContractConfig(
+        exchange="0xd91E80cF2E7be2e162c6513ceD06f1dD0dA35296",
+        collateral="0x9c4e1703476e875070ee25b56a58b008cfb8fa78",
+        conditional_tokens="0x69308FB512518e39F9b16112fA8d994F4e2Bf8bB",
+    ),
+}
+
+def get_contract_config(chain_id: int, neg_risk: bool = False) -> ContractConfig:
+    """Get the contract configuration for the chain."""
+    config = NEG_RISK_CONFIG.get(chain_id) if neg_risk else CONFIG.get(chain_id)
+    if config is None:
+        msg = f"Invalid chain_id: ${chain_id}"
+        raise ValueError(msg)
+
+    return config

polymarket_apis/utilities/constants.py

@@ -0,0 +1,26 @@
+# Access levels
+L0 = 0
+L1 = 1
+L2 = 2
+
+
+CREDENTIAL_CREATION_WARNING = """🚨🚨🚨
+Your credentials CANNOT be recovered after they've been created.
+Be sure to store them safely!
+🚨🚨🚨"""
+
+
+L1_AUTH_UNAVAILABLE = "A private key is needed to interact with this endpoint!"
+
+L2_AUTH_UNAVAILABLE = "API Credentials are needed to interact with this endpoint!"
+
+ZERO_ADDRESS = "0x0000000000000000000000000000000000000000"
+HASH_ZERO = "0x0000000000000000000000000000000000000000000000000000000000000000"
+
+AMOY = 80002
+POLYGON = 137
+
+END_CURSOR = "LTE="
+
+BUY = "BUY"
+SELL = "SELL"

polymarket_apis/utilities/endpoints.py

@@ -0,0 +1,37 @@
+TIME = "/time"
+CREATE_API_KEY = "/auth/api-key"
+GET_API_KEYS = "/auth/api-keys"
+DELETE_API_KEY = "/auth/api-key"
+DERIVE_API_KEY = "/auth/derive-api-key"
+TRADES = "/data/trades"
+GET_ORDER_BOOK = "/book"
+GET_ORDER_BOOKS = "/books"
+ORDERS = "/data/orders"
+POST_ORDER = "/order"
+POST_ORDERS = "/orders"
+CANCEL = "/order"
+CANCEL_ORDERS = "/orders"
+CANCEL_ALL = "/cancel-all"
+CANCEL_MARKET_ORDERS = "/cancel-market-orders"
+MID_POINT = "/midpoint"
+MID_POINTS = "/midpoints"
+PRICE = "/price"
+GET_PRICES = "/prices"
+GET_SPREAD = "/spread"
+GET_SPREADS = "/spreads"
+GET_LAST_TRADE_PRICE = "/last-trade-price"
+GET_LAST_TRADES_PRICES = "/last-trades-prices"
+GET_NOTIFICATIONS = "/notifications"
+DROP_NOTIFICATIONS = "/notifications"
+GET_BALANCE_ALLOWANCE = "/balance-allowance"
+UPDATE_BALANCE_ALLOWANCE = "/balance-allowance/update"
+IS_ORDER_SCORING = "/order-scoring"
+ARE_ORDERS_SCORING = "/orders-scoring"
+GET_TICK_SIZE = "/tick-size"
+GET_NEG_RISK = "/neg-risk"
+GET_SAMPLING_SIMPLIFIED_MARKETS = "/sampling-simplified-markets"
+GET_SAMPLING_MARKETS = "/sampling-markets"
+GET_SIMPLIFIED_MARKETS = "/simplified-markets"
+GET_MARKETS = "/markets"
+GET_MARKET = "/markets/"
+GET_MARKET_TRADES_EVENTS = "/live-activity/events/"

polymarket_apis/utilities/exceptions.py

@@ -0,0 +1,11 @@
+class InvalidPriceError(Exception):
+    pass
+
+class InvalidTickSizeError(Exception):
+    pass
+
+class LiquidityError(Exception):
+    pass
+
+class MissingOrderbookError(Exception):
+    pass

polymarket_apis/utilities/headers.py

@@ -0,0 +1,54 @@
+from datetime import UTC, datetime
+from typing import Optional
+
+from ..types.clob_types import ApiCreds, RequestArgs
+from .signing.eip712 import sign_clob_auth_message
+from .signing.hmac import build_hmac_signature
+from .signing.signer import Signer
+
+POLY_ADDRESS = "POLY_ADDRESS"
+POLY_SIGNATURE = "POLY_SIGNATURE"
+POLY_TIMESTAMP = "POLY_TIMESTAMP"
+POLY_NONCE = "POLY_NONCE"
+POLY_API_KEY = "POLY_API_KEY"
+POLY_PASSPHRASE = "POLY_PASSPHRASE"
+
+
+def create_level_1_headers(signer: Signer, nonce: Optional[int] = None):
+    """Creates Level 1 Poly headers for a request."""
+    timestamp = int(datetime.now(tz=UTC).timestamp())
+
+    n = 0
+    if nonce is not None:
+        n = nonce
+
+    signature = sign_clob_auth_message(signer, timestamp, n)
+    headers = {
+        POLY_ADDRESS: signer.address(),
+        POLY_SIGNATURE: signature,
+        POLY_TIMESTAMP: str(timestamp),
+        POLY_NONCE: str(n),
+    }
+
+    return headers
+
+
+def create_level_2_headers(signer: Signer, creds: ApiCreds, request_args: RequestArgs):
+    """Creates Level 2 Poly headers for a request."""
+    timestamp = str(int(datetime.now(tz=UTC).timestamp()))
+
+    hmac_sig = build_hmac_signature(
+        creds.secret,
+        timestamp,
+        request_args.method,
+        request_args.request_path,
+        request_args.body,
+    )
+
+    return {
+        POLY_ADDRESS: signer.address(),
+        POLY_SIGNATURE: hmac_sig,
+        POLY_TIMESTAMP: timestamp,
+        POLY_API_KEY: creds.api_key,
+        POLY_PASSPHRASE: creds.passphrase,
+    }