Metadata-Version: 2.4
Name: pax-api
Version: 2.1.0
Summary: Official Python SDK for the PredictAsiaX Trader Track API — Web3-native prediction markets
Author-email: PredictAsiaX <support@predictasiax.com>
License: MIT
Project-URL: Homepage, https://predictasiax.com/developer
Project-URL: Documentation, https://docs.predictasiax.com
Project-URL: Repository, https://github.com/predictasiax/pax-python-sdk
Project-URL: Issues, https://github.com/predictasiax/pax-python-sdk/issues
Project-URL: Changelog, https://docs.predictasiax.com/changelog
Keywords: predictasiax,pax,prediction-market,trading-api,web3,hmac,polymarket-compatible
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28
Requires-Dist: websocket-client>=1.5
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: pytest-cov>=4; extra == "dev"
Requires-Dist: responses>=0.23; extra == "dev"
Requires-Dist: ruff>=0.1; extra == "dev"
Requires-Dist: mypy>=1; extra == "dev"
Requires-Dist: build>=1; extra == "dev"
Requires-Dist: twine>=4; extra == "dev"
Dynamic: license-file

# pax-api — Official Python SDK for PredictAsiaX

Web3-native prediction market REST + WebSocket API client. Polymarket-compatible HMAC signing pattern.

**Version 1.0.0** · MIT license · Python 3.8+

- **Docs**: https://docs.predictasiax.com
- **Developer landing**: https://predictasiax.com/developer
- **Get API key**: https://predictasiax.com/settings/api-keys
- **Support**: support@predictasiax.com

## Install

```bash
# Direct install from PredictAsiaX-hosted wheel
pip install https://docs.predictasiax.com/downloads/sdk/python/pax_api-1.0.0-py3-none-any.whl

# Or download tarball + install locally
curl -O https://docs.predictasiax.com/downloads/sdk/python/pax_api-1.0.0.tar.gz
pip install pax_api-1.0.0.tar.gz
```

(PyPI publish coming soon — install methods above work today.)

## Quickstart (sandbox — no real money)

```python
from pax_api import PaxClient

with PaxClient(api_key="sk_test_YOUR_KEY", env="sandbox") as pax:
    faucet = pax.faucet()                          # get 10k test USDT
    print(faucet["data"]["balance_free"])           # → "10000.000000"

    templates = pax.list_templates()
    markets   = pax.list_markets(category="crypto", limit=10)

    market = pax.create_market(
        template_id="crypto_price_binary_60s",
        params={"asset": "BTC"},
    )
    print(market["data"]["market"]["market_id"])    # → "m_..."
```

## HMAC-signed requests (production)

Machine-to-machine trading bots should use HMAC signing (Polymarket-compatible 5-header pattern).

```python
from pax_api import PaxClient

pax = PaxClient(
    api_key="sk_live_YOUR_KEY",
    secret="<64-hex secret>",
    passphrase="<passphrase>",
    env="production",
)

pax.place_order(
    market_id="m_...",
    outcome_id="yes",
    side="buy",
    order_type="limit",
    size="100",
    price="0.55",
    client_order_id="unique-per-intent-id",  # retry-safe within 24h
)
```

## WebSocket streams

```python
from pax_api import PaxWSClient

ws = PaxWSClient(
    api_key="sk_test_...",
    env="sandbox",
    subscribe_on_connect=["fast_tick", "trade_executed", "account"],
)
ws.on("fast_tick",      lambda e: print("tick:", e))
ws.on("trade_executed", lambda e: print("trade:", e))
ws.on("account",        lambda e: print("balance:", e.get("balance_free")))
ws.run_forever()                                    # blocks; Ctrl+C to exit
```

Auto-reconnect + exponential backoff built-in. All 4 client methods supported:
`subscribe`, `unsubscribe`, `auth`, `set_locale`.

## Error handling

Every response error becomes a typed exception. Catch the specific type
you want to handle:

```python
from pax_api import (
    PaxClient,
    PaxRateLimitError,
    PaxReadOnlyModeError,
    PaxValidationError,
    PaxWrongEnvKeyError,
    PaxError,           # base class — catch-all
)

try:
    pax.place_order(...)
except PaxRateLimitError as e:
    time.sleep(e.retry_after or 5)
    # then retry
except PaxValidationError as e:
    print(f"Bad request: {e.details}")             # {'field': 'size', ...}
except PaxReadOnlyModeError:
    print("Trading paused by ops")
except PaxWrongEnvKeyError:
    print("Wrong environment key")
except PaxError as e:
    print(f"[{e.code}] {e.message} (request_id={e.request_id})")
```

## Automatic retry

Built-in exponential backoff on `429`, `500`, `502`, `504` responses. `Retry-After`
header respected on rate limits. Non-idempotent creates are safe when you send
`client_order_id`.

```python
pax = PaxClient(api_key="sk_test_...", env="sandbox", max_retries=5)
# max_retries=0 disables retries entirely
```

## Environments

| Env | Base URL | Keys |
|---|---|---|
| `production` | `https://api.predictasiax.com/v1` | `sk_live_*` |
| `sandbox`    | `https://api.predictasiax.com/v1` | `sk_test_*` |

`sk_test_*` on production returns `401 WRONG_ENV_KEY`. Same the other way. See
[docs auth guide](https://docs.predictasiax.com/auth#env-separation).

## Custom base URL

```python
pax = PaxClient(api_key="...", base_url="https://your-mirror/api")
```

## Development

```bash
# Get source (tarball)
curl -O https://docs.predictasiax.com/downloads/sdk/python/pax_api-1.0.0.tar.gz
tar -xzf pax_api-1.0.0.tar.gz && cd pax_api-1.0.0
pip install -e ".[dev]"
pytest                                              # run all tests
ruff check src tests                                # lint
mypy src                                            # type-check
```

## Links

- [OpenAPI spec](https://docs.predictasiax.com/openapi)
- [AsyncAPI (WebSocket) spec](https://docs.predictasiax.com/asyncapi)
- [Auth guide](https://docs.predictasiax.com/auth)
- [Error codes](https://docs.predictasiax.com/errors)
- [Rate limits](https://docs.predictasiax.com/rate-limits)
- [FAQ](https://docs.predictasiax.com/faq)
- [API Terms](https://docs.predictasiax.com/api-terms)

## License

MIT — see [LICENSE](LICENSE).
