# STRIGIVAL Python SDK

Official Python SDK for the STRIGIVAL Trading Strategies Marketplace.

## Installation

```bash
pip install strigival
```

## Quick Start

```python
from strigival import StrigivalClient, Protocol, TradeAction

# Initialize client
client = StrigivalClient(
    api_url="https://api.strigival.com",
    private_key="0x..."  # Your private key
)

# List available strategies
strategies = client.list_strategies(sort_by="sharpe", limit=10)
for strategy in strategies:
    print(f"{strategy['name']}: Sharpe {strategy['sharpe_ratio']}")

# Get a quote for a swap
quote = client.get_quote(
    vault_address="0x...",
    token_in="0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",  # USDC
    token_out="0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2",  # WETH
    amount=1000_000000,  # 1000 USDC (6 decimals)
    protocol=Protocol.UNISWAP_V3,
    slippage_bps=50,  # 0.5%
)

print(f"Quote: {quote.amount_out} WETH")
print(f"Price impact: {quote.price_impact_bps} bps")
print(f"Gas cost: ${quote.gas_cost_usd}")

# Execute the trade
trade = client.execute_trade(quote, vault_address="0x...")
print(f"Trade executed: {trade.tx_hash}")
```

## Features

- **Authentication**: Web3 signature-based authentication
- **Quotes**: Get real-time quotes from multiple protocols
- **Trading**: Execute trades via your vault
- **Analytics**: Access institutional-grade KPIs
- **History**: Query trade history and performance

## API Reference

### StrigivalClient

```python
client = StrigivalClient(
    api_url: str,           # API base URL
    private_key: str,       # Ethereum private key
    timeout: float = 30.0,  # Request timeout
)
```

### Methods

#### Quotes

```python
# Get a quote
quote = client.get_quote(
    vault_address: str,
    token_in: str,
    token_out: str,
    amount: int,
    protocol: Protocol = Protocol.UNISWAP_V3,
    action: TradeAction = TradeAction.SWAP,
    slippage_bps: int = 50,
)

# List supported protocols
protocols = client.get_protocols()
```

#### Trading

```python
# Execute a trade
trade = client.execute_trade(quote, vault_address)

# Get trade history
history = client.get_trade_history(vault_address, limit=50)

# Get trade details
trade = client.get_trade(vault_address, tx_hash)
```

#### Vault

```python
# Get vault status
status = client.get_vault_status(vault_address)

# Get authorized tokens
tokens = client.get_authorized_tokens(vault_address)
```

#### Analytics

```python
# Get all KPIs
kpis = client.get_kpis(vault_address)
print(f"Sharpe: {kpis.sharpe_ratio}")
print(f"Max DD: {kpis.drawdown.max_drawdown}")

# Get Sharpe ratio
sharpe = client.get_sharpe_ratio(vault_address, period_days=365)
```

## Types

### Quote

```python
@dataclass
class Quote:
    quote_id: str
    expires_at: datetime
    amount_in: int
    amount_out: int
    amount_out_min: int
    price: float
    price_impact_bps: int
    estimated_gas: int
    gas_price_gwei: float
    gas_cost_usd: float
    protocol: str
    route: List[str]
```

### Trade

```python
@dataclass
class Trade:
    tx_hash: str
    success: bool
    gas_used: Optional[int]
    amount_in: Optional[int]
    amount_out: Optional[int]
    slippage_actual_bps: Optional[int]
    error: Optional[str]
```

### KPIs

```python
@dataclass
class KPIs:
    sharpe_ratio: float
    sortino_ratio: float
    calmar_ratio: float
    volatility_annual: float
    drawdown: DrawdownInfo
    win_rate: WinRateInfo
    alpha: float
    beta: float
```

## Error Handling

```python
from strigival import (
    StrigivalError,
    AuthenticationError,
    QuoteError,
    TradeError,
    RateLimitError,
)

try:
    quote = client.get_quote(...)
except RateLimitError as e:
    print(f"Rate limited, retry after {e.retry_after}s")
except QuoteError as e:
    print(f"Quote failed: {e.message}")
except StrigivalError as e:
    print(f"Error [{e.code}]: {e.message}")
```

## License

Proprietary License - see LICENSE file for details.
