worm-sdk 0.9.0__tar.gz

worm_sdk-0.9.0/.github/workflows/release.yml

@@ -0,0 +1,44 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.x"
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+      - name: Validate metadata
+        run: |
+          python -m pip install --upgrade twine
+          python -m twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/worm-sdk
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1

worm_sdk-0.9.0/.gitignore

@@ -0,0 +1,22 @@
+.venv/
+venv/
+.pip-cache/
+__pycache__
+dist/
+build/
+*.egg-info/
+.pypirc
+__MACOSX/
+.idea/
+.vscode/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.DS_Store
+.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+local

worm_sdk-0.9.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Worm
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

worm_sdk-0.9.0/Makefile

@@ -0,0 +1,10 @@
+PYTHON=python
+
+build:
+	$(PYTHON) -m build
+
+clean:
+	rm -rf dist/ build/ src/worm_sdk.egg-info worm_sdk.egg-info
+
+upload:
+	twine upload dist/*

worm_sdk-0.9.0/PKG-INFO

@@ -0,0 +1,218 @@
+Metadata-Version: 2.4
+Name: worm-sdk
+Version: 0.9.0
+Summary: Python SDK for the Worm prediction markets platform
+Project-URL: Homepage, https://worm.wtf
+Project-URL: Documentation, https://docs.worm.wtf
+Project-URL: Repository, https://github.com/wormwtf/worm-sdk
+Project-URL: Issues, https://github.com/wormwtf/worm-sdk/issues
+Author-email: Worm <support@worm.wtf>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api-client,prediction-markets,sdk,solana,worm
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx[http2]>=0.25
+Requires-Dist: pydantic>=2.4.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Provides-Extra: signing
+Requires-Dist: base58>=2.1; extra == 'signing'
+Requires-Dist: solders>=0.21; extra == 'signing'
+Description-Content-Type: text/markdown
+
+# worm-sdk
+
+Official Python client for the [Worm](https://worm.wtf) prediction markets API.
+
+[![CI](https://github.com/wormwtf/worm-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/wormwtf/worm-sdk/actions/workflows/ci.yml)
+[![PyPI version](https://badge.fury.io/py/worm-sdk.svg)](https://pypi.org/project/worm-sdk/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+## Features
+
+- Full coverage of the Worm REST API — markets, events, search, spot orders, margin, redeems, and account data
+- Typed responses with [Pydantic](https://docs.pydantic.dev/) models
+- HMAC authentication for private endpoints
+- Optional Solana wallet signing for order, margin, and redeem flows
+- Cursor-based pagination helpers
+- HTTP/2 via [httpx](https://www.python-httpx.org/)
+
+## Requirements
+
+- Python 3.10 or later
+
+## Installation
+
+```bash
+pip install worm-sdk
+```
+
+Install from source:
+
+```bash
+git clone https://github.com/wormwtf/worm-sdk.git
+cd worm-sdk
+pip install -e .
+```
+
+For wallet signing (orders, margin, redeems):
+
+```bash
+pip install "worm-sdk[signing]"
+```
+
+## Quickstart
+
+Fetch public market data — no credentials required:
+
+```python
+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.
+
+```python
+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:
+
+```bash
+export WORM_API_KEY="..."
+export WORM_API_SECRET="..."
+export WORM_PRIVATE_KEY="..."   # only for signing flows
+```
+
+## Usage
+
+`WormClient` exposes namespaced APIs:
+
+| Namespace | Auth | Description |
+|-----------|------|-------------|
+| `client.markets` | — | Market listings, order books, candles, prices, trades |
+| `client.events` | — | Event listings and detail |
+| `client.search` | — | Search markets and events |
+| `client.sports` | — | Sports and league catalog |
+| `client.orders` | ✓ | Spot order lifecycle |
+| `client.trades` | ✓ | Your trade history |
+| `client.account` | ✓ | Profile, portfolio, P&L |
+| `client.margin` | ✓ / — | Margin estimate (public); positions, requests, settlements |
+| `client.redeems` | ✓ | Redeem resolved positions |
+| `client.api_keys` | ✓ | List and revoke API keys |
+
+List endpoints return a `CursorPage[T]` with `items`, `next_cursor`, and `limit`:
+
+```python
+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:
+
+```python
+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/`](examples/) directory for complete scripts covering markets, orders, margin, redeems, and more.
+
+## Error handling
+
+```python
+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
+
+```python
+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
+
+```bash
+pip install -e ".[dev,signing]"
+pytest
+ruff check .
+mypy src
+```
+
+Build locally:
+
+```bash
+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](https://worm.wtf)
+- [API documentation](https://docs.worm.wtf)
+- [Issue tracker](https://github.com/wormwtf/worm-sdk/issues)
+
+## License
+
+MIT — see [LICENSE](LICENSE).

worm_sdk-0.9.0/README.md

@@ -0,0 +1,183 @@
+# worm-sdk
+
+Official Python client for the [Worm](https://worm.wtf) prediction markets API.
+
+[![CI](https://github.com/wormwtf/worm-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/wormwtf/worm-sdk/actions/workflows/ci.yml)
+[![PyPI version](https://badge.fury.io/py/worm-sdk.svg)](https://pypi.org/project/worm-sdk/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+## Features
+
+- Full coverage of the Worm REST API — markets, events, search, spot orders, margin, redeems, and account data
+- Typed responses with [Pydantic](https://docs.pydantic.dev/) models
+- HMAC authentication for private endpoints
+- Optional Solana wallet signing for order, margin, and redeem flows
+- Cursor-based pagination helpers
+- HTTP/2 via [httpx](https://www.python-httpx.org/)
+
+## Requirements
+
+- Python 3.10 or later
+
+## Installation
+
+```bash
+pip install worm-sdk
+```
+
+Install from source:
+
+```bash
+git clone https://github.com/wormwtf/worm-sdk.git
+cd worm-sdk
+pip install -e .
+```
+
+For wallet signing (orders, margin, redeems):
+
+```bash
+pip install "worm-sdk[signing]"
+```
+
+## Quickstart
+
+Fetch public market data — no credentials required:
+
+```python
+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.
+
+```python
+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:
+
+```bash
+export WORM_API_KEY="..."
+export WORM_API_SECRET="..."
+export WORM_PRIVATE_KEY="..."   # only for signing flows
+```
+
+## Usage
+
+`WormClient` exposes namespaced APIs:
+
+| Namespace | Auth | Description |
+|-----------|------|-------------|
+| `client.markets` | — | Market listings, order books, candles, prices, trades |
+| `client.events` | — | Event listings and detail |
+| `client.search` | — | Search markets and events |
+| `client.sports` | — | Sports and league catalog |
+| `client.orders` | ✓ | Spot order lifecycle |
+| `client.trades` | ✓ | Your trade history |
+| `client.account` | ✓ | Profile, portfolio, P&L |
+| `client.margin` | ✓ / — | Margin estimate (public); positions, requests, settlements |
+| `client.redeems` | ✓ | Redeem resolved positions |
+| `client.api_keys` | ✓ | List and revoke API keys |
+
+List endpoints return a `CursorPage[T]` with `items`, `next_cursor`, and `limit`:
+
+```python
+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:
+
+```python
+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/`](examples/) directory for complete scripts covering markets, orders, margin, redeems, and more.
+
+## Error handling
+
+```python
+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
+
+```python
+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
+
+```bash
+pip install -e ".[dev,signing]"
+pytest
+ruff check .
+mypy src
+```
+
+Build locally:
+
+```bash
+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](https://worm.wtf)
+- [API documentation](https://docs.worm.wtf)
+- [Issue tracker](https://github.com/wormwtf/worm-sdk/issues)
+
+## License
+
+MIT — see [LICENSE](LICENSE).

worm_sdk-0.9.0/examples/account.py

@@ -0,0 +1,36 @@
+"""View account summary, assets, and P&L."""
+
+import os
+
+from worm_sdk import WormClient
+
+API_KEY = os.getenv("WORM_API_KEY")
+API_SECRET = os.getenv("WORM_API_SECRET")
+
+client = WormClient(api_key=API_KEY, api_secret=API_SECRET)
+
+# --- Account summary ---
+summary = client.account.get_summary()
+print(f"Username: {summary.username}")
+print(f"Twitter: {summary.twitter_username}")
+print(f"Joined at: {summary.joined_at}")
+
+# --- Market share balances ---
+assets = client.account.get_assets(limit=10)
+for a in assets.items:
+    print(
+        f"  {a.position.outcome_text} ({a.token.symbol}) "
+        f"total={a.amounts.total} available={a.amounts.available} "
+        f"value_usdt={a.value.usdt}"
+    )
+
+# --- P&L ---
+pnl = client.account.get_pnl()
+print(f"\nMargin settlements P&L: {pnl.margin_position_settlements_pnl}")
+print(f"Margin unrealized P&L: {pnl.margin_positions_unrealized_pnl}")
+print(f"Redeems funds: {pnl.redeems_funds}")
+print(f"Active assets value: {pnl.active_assets_value}")
+print(f"Creator fees: {pnl.creator_fees}")
+print(f"Total P&L: {pnl.total_pnl}")
+
+client.close()

worm_sdk-0.9.0/examples/api_keys.py

@@ -0,0 +1,24 @@
+"""List and revoke API keys for the authenticated account."""
+
+import os
+
+from worm_sdk import WormClient
+
+API_KEY = os.getenv("WORM_API_KEY")
+API_SECRET = os.getenv("WORM_API_SECRET")
+
+client = WormClient(api_key=API_KEY, api_secret=API_SECRET)
+
+# --- List keys (each entry includes an id / key identifier for revocation) ---
+keys = client.api_keys.list()
+for k in keys:
+    print(
+        f"key_id={k.key_id} "
+        f"created={k.created} revoked_at={k.revoked_at}"
+    )
+
+# --- Revoke a key by id (use `key_id` from list(); not the secret) ---
+# KEY_ID_TO_REVOKE = "key-id-from-list-response"
+# client.api_keys.revoke(KEY_ID_TO_REVOKE)
+
+client.close()

worm_sdk-0.9.0/examples/margin.py

@@ -0,0 +1,82 @@
+"""Margin trading: estimate, open positions, set TP/SL, close, and claim."""
+
+import os
+
+from worm_sdk import WormClient
+from worm_sdk.auth import SolanaWalletSigner
+from worm_sdk.types.enums import MarginPositionRequestType
+
+API_KEY = os.getenv("WORM_API_KEY")
+API_SECRET = os.getenv("WORM_API_SECRET")
+PRIVATE_KEY = os.getenv("WORM_PRIVATE_KEY")
+
+signer = SolanaWalletSigner(PRIVATE_KEY)
+client = WormClient(api_key=API_KEY, api_secret=API_SECRET, signer=signer)
+
+MARKET_CONDITION_ID = "your-market-condition-id"
+
+# --- Estimate a position (public, no auth) ---
+estimate = client.margin.estimate(
+    market_condition_id=MARKET_CONDITION_ID,
+    funds="100",
+    leverage="5",
+    is_yes=True,
+)
+print(f"Estimated shares: {estimate}")
+
+# --- Position request lifecycle (same paths as API reference under /margin/positions/requests/) ---
+page = client.margin.list_requests(market_condition_id=MARKET_CONDITION_ID, limit=10)
+print(f"Open requests: {len(page.items)}")
+# draft = client.margin.create_request(...)
+# client.margin.submit_request(draft.pubkey, signature=your_signature)
+# client.margin.cancel_request(draft.pubkey)
+# row = client.margin.get_request("request-pubkey")
+
+# --- Open a market position (funds-based; convenience: create + sign + submit) ---
+market_result = client.margin.open_position(
+    market_condition_id=MARKET_CONDITION_ID,
+    position_request_type=MarginPositionRequestType.MARKET,
+    funds="100",
+    leverage="5",
+    is_yes=True,
+    take_profit_price="0.95",
+    stop_loss_price="0.40",
+)
+print(f"Market position request submitted: {market_result.pubkey}")
+
+# --- Open a limit position (price + shares; resting limit order) ---
+limit_result = client.margin.open_position(
+    market_condition_id=MARKET_CONDITION_ID,
+    position_request_type=MarginPositionRequestType.LIMIT,
+    price="0.55",
+    shares="200",
+    leverage="3",
+    is_yes=True,
+    take_profit_price="0.90",
+    stop_loss_price="0.35",
+)
+print(f"Limit position request submitted: {limit_result.pubkey}")
+
+# --- List positions ---
+positions = client.margin.list_positions(limit=5)
+for p in positions.items:
+    print(f"  Position: {p.pubkey} — closed={p.is_closed}")
+
+pubkey = input("Enter position pubkey to set TP/SL / close: ")
+
+# --- Update TP/SL ---
+if pubkey:
+    tp_sl = client.margin.set_tp_sl(pubkey, take_profit_price="0.90", stop_loss_price="0.35")
+    print(f"TP/SL updated: {tp_sl}")
+
+# --- Close a position ---
+if pubkey:
+    close_result = client.margin.close_position(pubkey)
+    print(f"Close result: {close_result}")
+
+# --- Claim settlement ---
+if pubkey:
+    claim = client.margin.claim_settlement(pubkey)
+    print(f"Settlement claimed: {claim}")
+
+client.close()

worm_sdk-0.9.0/examples/margin_settlements.py

@@ -0,0 +1,49 @@
+"""Margin: inspect a single position and list settlements across positions."""
+
+import os
+
+from worm_sdk import WormClient
+from worm_sdk.auth import SolanaWalletSigner
+
+API_KEY = os.getenv("WORM_API_KEY")
+API_SECRET = os.getenv("WORM_API_SECRET")
+PRIVATE_KEY = os.getenv("WORM_PRIVATE_KEY")
+
+signer = SolanaWalletSigner(PRIVATE_KEY)
+client = WormClient(api_key=API_KEY, api_secret=API_SECRET, signer=signer)
+
+# Set this to a known position pubkey, or leave as placeholder to use the first listed position.
+POSITION_PUBKEY = "your-position-pubkey"
+MARKET_CONDITION_ID = "your-market-condition-id"
+
+positions = client.margin.list_positions(limit=5)
+for p in positions.items:
+    print(f"  {p.pubkey} — closed={p.is_closed}")
+
+pubkey = (
+    POSITION_PUBKEY
+    if POSITION_PUBKEY != "your-position-pubkey"
+    else (positions.items[0].pubkey if positions.items else None)
+)
+
+if pubkey:
+    detail = client.margin.get_position(pubkey)
+    print(f"\nDetail for {pubkey}: {detail}")
+
+# --- Settlements list (cursor pagination) ---
+page = client.margin.list_settlements(limit=20)
+for s in page.items:
+    print(f"  settlement: {s}")
+
+if page.next_cursor:
+    more = client.margin.list_settlements(limit=20, cursor=page.next_cursor)
+    print(f"Next page: {len(more.items)} settlements")
+
+# --- Optional filters ---
+filtered = client.margin.list_settlements(
+    market_condition_id=MARKET_CONDITION_ID,
+    limit=10,
+)
+print(f"Filtered by market: {len(filtered.items)}")
+
+client.close()