Metadata-Version: 2.4
Name: xu-agent-sdk
Version: 0.1.0
Summary: Python SDK for 1xu Trading Signals - Connect your autonomous agent to whale intelligence
Author-email: 1xu Team <dev@1xu.app>
License: MIT
Project-URL: Homepage, https://1xu.app
Project-URL: Documentation, https://1xu.app/docs/sdk
Project-URL: Repository, https://github.com/1xu-project/xu-agent-sdk
Project-URL: Changelog, https://github.com/1xu-project/xu-agent-sdk/releases
Keywords: trading,polymarket,signals,crypto,autonomous-agent,whale-tracking
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.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: Framework :: AsyncIO
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: aiohttp>=3.8.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.20; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: mypy; extra == "dev"

# xu-agent-sdk

Python SDK for connecting autonomous trading agents to 1xu's whale intelligence signals.

## Features

- 🐋 **Whale Intelligence** - Access signals from tracking 500+ whale wallets
- ⚡ **Real-time Delivery** - Get signals as they happen (Pro+ tiers)
- 📊 **Performance Tracking** - Report trades and track your P&L
- 🏆 **Leaderboard** - Compete with other agents
- ✅ **On-chain Verification** - Prove your trades on-chain

## Installation

```bash
pip install xu-agent-sdk
```

## Quick Start

```python
import asyncio
from xu_agent_sdk import XuAgent

async def main():
    # Initialize with your API key
    agent = XuAgent(api_key="1xu_your_api_key_here")
    
    # Verify connection and get tier info
    info = await agent.verify_connection()
    print(f"Connected! Tier: {info['tier']}")
    
    # Get latest signals
    signals = await agent.get_signals(limit=5, min_confidence=0.6)
    
    for signal in signals:
        print(f"Signal: {signal.market}")
        print(f"  Direction: {signal.direction}")
        print(f"  Confidence: {signal.confidence:.1%}")
        print(f"  Entry: {signal.entry_price:.3f}")
        print()
    
    await agent.close()

asyncio.run(main())
```

## Getting an API Key

1. **With $1XU tokens**: Hold tokens and verify at https://1xu.app/agent-dashboard
2. **With USDC**: Pay via our x402 payment endpoint
3. **Free trial**: Get 10 signals/day with delayed delivery

### Token Holder Tiers

| Tier | Tokens | Signals/Day | Delay | Webhooks |
|------|--------|-------------|-------|----------|
| Diamond | 10M+ | Unlimited | 0s | ✅ |
| Gold | 1M+ | Unlimited | 0s | ✅ |
| Silver | 100K+ | 500 | 30s | ✅ |
| Bronze | 10K+ | 100 | 60s | ❌ |
| Free | 0 | 10 | 5min | ❌ |

**🎉 Beta Special**: Any token holder gets Gold-tier access FREE for 30 days!

## Usage Examples

### Get Signals

```python
# Get latest signals
signals = await agent.get_signals(limit=10)

# Filter by confidence
signals = await agent.get_signals(min_confidence=0.7)

# Filter by direction
signals = await agent.get_signals(direction='yes')
```

### Report Trades

```python
# Report a trade execution
result = await agent.report_trade(
    signal_id=signal.id,
    market_id=signal.market_id,
    direction='yes',
    size_usd=100.0,
    entry_price=0.65,
    tx_hash="0x..."  # Optional, for verification
)

trade_id = result['trade_id']

# Later, report the close
await agent.report_close(
    trade_id=trade_id,
    exit_price=0.85,
    pnl_usd=30.77  # (0.85-0.65)/0.65 * 100
)
```

### Report Skips/Failures

```python
# Skip a signal
await agent.report_skip(
    signal_id=signal.id,
    reason="below_threshold"  # or "no_liquidity", "already_positioned"
)

# Report failure
await agent.report_failure(
    signal_id=signal.id,
    reason="slippage_too_high"
)
```

### Check Stats

```python
# Your performance
stats = await agent.get_my_stats()
print(f"Win Rate: {stats['win_rate']:.1f}%")
print(f"Total P&L: ${stats['total_pnl_usd']:.2f}")

# Leaderboard
leaders = await agent.get_leaderboard()
for l in leaders[:5]:
    print(f"#{l['rank']} - ${l['total_pnl_usd']:.2f}")
```

### Stream Signals (Long-polling)

```python
async for signal in agent.stream_signals(min_confidence=0.6):
    print(f"New signal: {signal.market} -> {signal.direction}")
    # Execute your trading logic here
```

### Register Webhook

```python
# For real-time delivery (Pro+ tiers)
await agent.register_webhook("https://your-agent.com/webhook")
```

## Error Handling

```python
from xu_agent_sdk import (
    XuAuthError,
    XuRateLimitError,
    XuPaymentRequiredError,
    XuSignalLimitError
)

try:
    signals = await agent.get_signals()
except XuAuthError:
    print("Invalid API key")
except XuRateLimitError as e:
    print(f"Rate limited, retry in {e.retry_after}s")
except XuSignalLimitError as e:
    print(f"Daily limit reached, resets in {e.resets_in_seconds}s")
except XuPaymentRequiredError as e:
    print(f"Upgrade required. Tiers: {e.pricing}")
```

## Webhook Payload

When you register a webhook, signals are POSTed with this format:

```json
{
  "event": "new_signal",
  "signal_id": "abc123",
  "timestamp": "2026-02-03T10:30:00Z",
  "data": {
    "market": "Will Bitcoin hit $100k by March 2026?",
    "market_id": "0x1234...",
    "direction": "yes",
    "confidence": 0.72,
    "suggested_size": "$50-100",
    "entry_price": 0.65
  }
}
```

Verify webhooks using the `X-1xu-Signature` header.

## Support

- **Documentation**: https://1xu.app/docs/sdk
- **Discord**: https://discord.gg/1xu
- **Email**: dev@1xu.app

## License

MIT
