Quickstart

pip install polymarket-us

import os
from polymarket_us import PolymarketUS

client = PolymarketUS(
    key_id=os.environ["POLYMARKET_KEY_ID"],
    secret_key=os.environ["POLYMARKET_SECRET_KEY"],
    timeout=30.0,  # optional, default 30s
)

from polymarket_us import PolymarketUS

client = PolymarketUS()

# Events
events = client.events.list({"limit": 10, "active": True})
event = client.events.retrieve_by_slug("super-bowl-2025")

# Markets
markets = client.markets.list({"limit": 10})
market = client.markets.retrieve_by_slug("btc-100k")
book = client.markets.book("btc-100k")
bbo = client.markets.bbo("btc-100k")

# Search
results = client.search.query({"query": "bitcoin"})

# Series and Sports
series = client.series.list()
sports = client.sports.list()

client.close()

import os
from polymarket_us import PolymarketUS

client = PolymarketUS(
    key_id=os.environ["POLYMARKET_KEY_ID"],
    secret_key=os.environ["POLYMARKET_SECRET_KEY"],
)

# Account
balances = client.account.balances()

# Portfolio
positions = client.portfolio.positions()
activities = client.portfolio.activities()

# Orders
open_orders = client.orders.list()
order = client.orders.create({
    "marketSlug": "your-market-slug",
    "intent": "ORDER_INTENT_BUY_LONG",
    "type": "ORDER_TYPE_LIMIT",
    "price": {"value": "0.555", "currency": "USD"},
    "quantity": 0.5,
    "tif": "TIME_IN_FORCE_GOOD_TILL_CANCEL",
})

client.close()

import asyncio
from polymarket_us import AsyncPolymarketUS

async def main():
    async with AsyncPolymarketUS(
        key_id="your-key-id",
        secret_key="your-secret-key",
    ) as client:
        # Concurrent requests
        events, markets = await asyncio.gather(
            client.events.list({"limit": 10}),
            client.markets.list({"limit": 10}),
        )
        print(f"Found {len(events['events'])} events")

asyncio.run(main())

from polymarket_us import (
    PolymarketUS,
    APIConnectionError,
    APITimeoutError,
    AuthenticationError,
    BadRequestError,
    NotFoundError,
    RateLimitError,
)

client = PolymarketUS(key_id="...", secret_key="...")

try:
    order = client.orders.create({"marketSlug": "..."})
except AuthenticationError as e:
    print(f"Invalid credentials: {e.message}")
except BadRequestError as e:
    print(f"Invalid parameters: {e.message}")
except RateLimitError as e:
    print(f"Rate limited: {e.message}")
except NotFoundError as e:
    print(f"Not found: {e.message}")
except APITimeoutError:
    print("Request timed out")
except APIConnectionError as e:
    print(f"Connection error: {e.message}")