worm-sdk

Official Python client for the Worm prediction markets API.

Features

• Full coverage of the Worm REST API — markets, events, search, spot orders, margin, redeems, and account data
• Typed responses with Pydantic models
• HMAC authentication for private endpoints
• Optional Solana wallet signing for order, margin, and redeem flows
• Cursor-based pagination helpers
• HTTP/2 via httpx

Requirements

• Python 3.10 or later

Installation

pip install worm-sdk

Install from source:

git clone https://github.com/wormwtf/worm-sdk.git
cd worm-sdk
pip install -e .

For wallet signing (orders, margin, redeems):

pip install "worm-sdk[signing]"

Quickstart

Fetch public market data — no credentials required:

from worm_sdk import WormClient

with WormClient() as client:
    page = client.markets.list(sort="trending", limit=5)
    for market in page.items:
        print(market.title, market.condition_id)

Authentication

Worm uses HMAC-signed API keys. Create a key once with a Solana wallet, then reuse the key and secret for all authenticated calls.

from worm_sdk import WormClient
from worm_sdk.auth import SolanaWalletSigner

# One-time setup — store the returned credentials securely
signer = SolanaWalletSigner("YOUR_SOLANA_PRIVATE_KEY")
credentials = WormClient.create_api_key(signer)

# Authenticated client
client = WormClient(
    api_key=credentials.api_key,
    api_secret=credentials.secret,
    signer=signer,  # optional; needed for place/redeem/open_position helpers
)

profile = client.account.get_summary()
print(profile.username)

SolanaWalletSigner accepts a base58 string, 128-character hex keypair, or raw 64-byte keypair bytes. You can also provide any object that implements SignerProtocol (Ledger, KMS, etc.).

Set credentials via environment variables when running the examples:

export WORM_API_KEY="..."
export WORM_API_SECRET="..."
export WORM_PRIVATE_KEY="..."   # only for signing flows

Usage

WormClient exposes namespaced APIs:

List endpoints return a CursorPage[T] with items, next_cursor, and limit:

page = client.markets.list(limit=20)
while page.next_cursor:
    page = client.markets.list(limit=20, cursor=page.next_cursor)

Convenience methods combine draft, sign, and submit in one call when a signer is configured:

from worm_sdk import OrderSide, OrderType

client.orders.place(
    market_condition_id="...",
    is_yes=True,
    side=OrderSide.BUY,
    order_type=OrderType.LIMIT,
    amount="10",
    price="0.55",
)

See the examples/ directory for complete scripts covering markets, orders, margin, redeems, and more.

Error handling

from worm_sdk import AuthenticationRequired, WormAPIError

try:
    client.orders.list(limit=1)
except WormAPIError as exc:
    print(exc.error_code, exc.slug, exc.message)
except AuthenticationRequired:
    print("Pass api_key and api_secret to WormClient")

Configuration

client = WormClient(
    api_key="...",
    api_secret="...",
    base_url="https://api.worm.wtf",  # default
    timeout=30.0,
    signer=signer,
)

Inspect rate limits and response metadata on client.last_response after each request.

Development

pip install -e ".[dev,signing]"
pytest
ruff check .
mypy src

Build locally:

python -m build

Releases are published to PyPI automatically when you push a version tag (e.g. v0.9.0) or publish a GitHub Release. Set the PYPI_API_TOKEN repository secret first.

Links

• Worm
• API documentation
• Issue tracker

License

MIT — see LICENSE.