Metadata-Version: 2.4
Name: the0-sdk
Version: 0.2.0
Summary: SDK for building trading bots on the0 platform
Author-email: alexanderwanyoike <hello@the0.dev>
License: Apache-2.0
Project-URL: Homepage, https://the0.dev
Project-URL: Documentation, https://docs.the0.dev
Project-URL: Repository, https://github.com/alexanderwanyoike/the0
Project-URL: Source Code, https://github.com/alexanderwanyoike/the0/tree/main/sdk/python
Keywords: trading,bots,algorithmic-trading,the0,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# the0-sdk (Python)

SDK for building trading bots on the0 platform.

## Installation

```bash
pip install the0-sdk
```

Or copy the `the0/` directory to your project.

## Quick Start

```python
from the0 import parse, success, error, metric, log

# Parse bot configuration from environment
bot_id, config = parse()

log(f"Bot {bot_id} starting...")

# Access configuration
symbol = config.get("symbol", "BTC/USDT")
amount = config.get("amount", 100.0)

try:
    # Your trading logic here
    log(f"Trading {symbol} with amount {amount}")

    # Emit metrics for the dashboard
    metric("price", {
        "symbol": symbol,
        "value": 45000.50,
        "change_pct": 2.5
    })

    # Signal success
    success("Trade executed", {
        "symbol": symbol,
        "amount": amount
    })

except Exception as e:
    error(f"Trade failed: {e}")
```

## API Reference

### `parse() -> Tuple[str, Dict]`

Parse bot configuration from environment variables.

```python
bot_id, config = parse()
# bot_id: Value of BOT_ID env var
# config: Parsed JSON from BOT_CONFIG env var
```

### `success(message: str, data: dict = None)`

Output a success result.

```python
success("Trade completed")
success("Trade completed", {"trade_id": "12345"})
```

### `error(message: str, data: dict = None)`

Output an error result and exit with code 1.

```python
if amount <= 0:
    error("Amount must be positive")
    # Program exits here
```

### `result(data: dict)`

Output a custom JSON result.

```python
result({
    "status": "success",
    "trade_id": "abc123",
    "filled_amount": 0.5,
    "average_price": 45123.50
})
```

### `metric(type: str, data: dict)`

Emit a metric for the platform dashboard.

```python
# Price metric
metric("price", {"symbol": "BTC/USD", "value": 45000})

# Trading signal
metric("signal", {"symbol": "ETH/USD", "direction": "long", "confidence": 0.85})

# Alert
metric("alert", {"type": "price_spike", "severity": "high"})
```

### `log(message: str, data: dict = None)`

Log a message to the bot's logs.

```python
log("Starting trade...")
log("Order placed", {"order_id": "12345"})
```

### `sleep(seconds: float)`

Sleep utility.

```python
sleep(5)  # Wait 5 seconds
```

## Publishing (Maintainers)

This package is published to PyPI.

### Prerequisites

1. Install build tools:
   ```bash
   pip install build twine
   ```

2. Create a PyPI API token at https://pypi.org/manage/account/token/

### Publish

```bash
# Build the package
python -m build

# Upload to PyPI
twine upload dist/*
```

### Version Bump

Update the version in `pyproject.toml`:

```toml
version = "0.2.0"
```

Then rebuild and publish.

## License

Apache-2.0
