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).
