xu-agent-sdk 0.1.1
Python SDK for 1XU Trading Signals - Connect your autonomous agent to AI-powered signal pipeline
License: MIT
Requires Python: >=3.9
Keywords: trading, polymarket, signals, crypto, autonomous-agent, a2a-protocol

# xu-agent-sdk

Python SDK for connecting autonomous trading agents to 1XU's AI-powered signal pipeline.

## Features

- ⚡ **Real-time Signals** — AI-powered trading signals for Polymarket
- 📡 **20+ Endpoints** — Full A2A protocol with REST API & webhooks
- 📊 **Performance Tracking** — Report trades and track your P&L
- 🔄 **Streaming** — Long-polling and webhook delivery
- ✅ **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 plan info
    info = await agent.verify_connection()
    print(f"Connected! Plan: {info['plan']}")
    
    # 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. **Deposit USDC** at https://1xu.app and get your API key instantly
2. **$2/day** during 15-day trial, then **$10/day**
3. Cancel anytime

## 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}")
```

### 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
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"Deposit USDC required: {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