# ZenOTC Python SDK

Official Python SDK for the ZenOTC OTC Trading Platform. Build and deploy algorithmic trading strategies with a clean, production-ready interface.

[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/zen-otc/otc-sdk/blob/main/notebooks/zenotc_rest_api.ipynb)

**Try the API interactively** - Open the notebook in Google Colab to test REST API calls without any local setup.

## Installation

```bash
pip install zenotc
```

## Quick Start

```python
from zenotc import ZenOTCClient

# Initialize the client
client = ZenOTCClient(
    api_key="your_api_key",
    api_secret="your_api_secret",
    environment="production"  # or "sandbox"
)

# Create an order
order = await client.execution.create_order(
    side="buy",
    asset="BTC",
    quantity=1.0,
    price=50000.00,
    order_type="limit"
)

print(f"Order created: {order.id}")

# Check order status
status = await client.execution.get_status(order.id)
print(f"Order status: {status.state}")
```

## Features

### ExecutionClient
Execute and manage orders.

```python
# Create order
order = await client.execution.create_order(
    side="buy",
    asset="BTC",
    quantity=1.0,
    price=50000.00
)

# Cancel order
await client.execution.cancel_order(order.id)

# Get execution status
status = await client.execution.get_status(order.id)

# Batch orders
orders = await client.execution.create_batch([
    {"side": "buy", "asset": "BTC", "quantity": 0.5, "price": 49000},
    {"side": "buy", "asset": "ETH", "quantity": 5.0, "price": 3000},
])
```

### MarketMakingClient
Submit and manage quotes for market makers.

```python
# Submit a two-way quote
quote = await client.market_making.submit_quote(
    asset="BTC",
    bid_price=49900.00,
    ask_price=50100.00,
    bid_size=5.0,
    ask_size=5.0,
    valid_for_seconds=30
)

# Update quote
await client.market_making.update_quote(
    quote_id=quote.id,
    bid_price=49950.00,
    ask_price=50050.00
)

# Cancel quote
await client.market_making.cancel_quote(quote.id)

# Get active quotes
quotes = await client.market_making.get_active_quotes()
```

### MarketDataClient
Access market data and real-time prices.

```python
# Get current prices
prices = await client.market_data.get_prices(["BTC", "ETH"])

# Get order book
orderbook = await client.market_data.get_orderbook("BTC", depth=10)

# Subscribe to real-time prices (async)
async def on_price_update(price):
    print(f"{price.asset}: bid={price.bid}, ask={price.ask}")

await client.market_data.subscribe_prices(["BTC", "ETH"], on_price_update)
```

### PortfolioClient
Track balances, positions, and exposure.

```python
# Get all balances
balances = await client.portfolio.get_balances()

# Get specific asset balance
btc_balance = await client.portfolio.get_balance("BTC")

# Get positions
positions = await client.portfolio.get_positions()

# Get exposure summary
exposure = await client.portfolio.get_exposure()

# Get portfolio summary
summary = await client.portfolio.get_summary()
```

### RiskClient
Pre-trade checks and risk management.

```python
# Get current risk limits
limits = await client.risk.get_limits()

# Pre-trade risk check
check = await client.risk.pre_trade_check(
    side="buy",
    asset="BTC",
    quantity=10.0,
    price=50000.00
)

if check.approved:
    order = await client.execution.create_order(...)
else:
    print(f"Rejected: {check.reason}")
    print(f"Available: {check.available_quantity}")

# Get current exposure
exposure = await client.risk.get_exposure()
```

## Configuration

### Environment Variables

```bash
ZENOTC_API_KEY=your_api_key
ZENOTC_API_SECRET=your_api_secret
ZENOTC_ENVIRONMENT=production  # or sandbox
ZENOTC_BASE_URL=https://api.zenotc.com  # optional override
```

### Client Configuration

```python
from zenotc import ZenOTCClient, Config

config = Config(
    api_key="your_api_key",
    api_secret="your_api_secret",
    environment="production",
    timeout=30.0,
    max_retries=3,
    rate_limit_per_second=10,
)

client = ZenOTCClient(config=config)
```

## Error Handling

```python
from zenotc.exceptions import (
    ZenOTCError,
    AuthenticationError,
    RateLimitError,
    ValidationError,
    InsufficientFundsError,
    OrderNotFoundError,
)

try:
    order = await client.execution.create_order(...)
except AuthenticationError:
    print("Invalid API credentials")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after} seconds")
except InsufficientFundsError as e:
    print(f"Insufficient funds. Available: {e.available}")
except ValidationError as e:
    print(f"Invalid request: {e.details}")
except ZenOTCError as e:
    print(f"API error: {e}")
```

## Async Support

All clients support async operations:

```python
import asyncio
from zenotc import AsyncZenOTCClient

async def main():
    client = AsyncZenOTCClient(
        api_key="your_api_key",
        api_secret="your_api_secret"
    )

    # Async order creation
    order = await client.execution.create_order(
        side="buy",
        asset="BTC",
        quantity=1.0,
        price=50000.00
    )

    # Async market data
    prices = await client.market_data.get_prices(["BTC", "ETH"])

    await client.close()

asyncio.run(main())
```

## Development

```bash
# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest

# Type checking
mypy src

# Linting
ruff check .
```

## License

Proprietary - ZenOTC
