xu-agent-sdk 0.1.0__py3-none-any.whl

xu_agent_sdk/__init__.py

@@ -0,0 +1,47 @@
+"""
+xu-agent-sdk: Python SDK for 1xu Trading Signals
+=================================================
+Connect your autonomous agent to 1xu's whale intelligence signals.
+
+Installation:
+    pip install xu-agent-sdk
+
+Quick Start:
+    from xu_agent_sdk import XuAgent
+
+    agent = XuAgent(api_key="1xu_your_key_here")
+    
+    # Get signals
+    signals = await agent.get_signals(limit=10)
+    
+    # Report trade
+    await agent.report_trade(
+        signal_id=signals[0]['id'],
+        market_id=signals[0]['market_id'],
+        direction='yes',
+        size_usd=100,
+        entry_price=0.65
+    )
+
+Documentation: https://1xu.app/docs/sdk
+"""
+
+__version__ = "0.1.0"
+__author__ = "1xu Team"
+
+from .client import XuAgent, XuSignal
+from .exceptions import (
+    XuError,
+    XuAuthError,
+    XuRateLimitError,
+    XuPaymentRequiredError,
+)
+
+__all__ = [
+    "XuAgent",
+    "XuSignal",
+    "XuError",
+    "XuAuthError", 
+    "XuRateLimitError",
+    "XuPaymentRequiredError",
+]

xu_agent_sdk/client.py

@@ -0,0 +1,593 @@
+"""
+xu-agent-sdk Client
+===================
+Main client for interacting with 1xu Trading Signals API.
+"""
+
+import asyncio
+import aiohttp
+import logging
+from datetime import datetime, timezone
+from typing import Optional, Dict, Any, List, Callable, Awaitable
+from dataclasses import dataclass
+from enum import Enum
+
+from .exceptions import (
+    XuError,
+    XuAuthError,
+    XuRateLimitError,
+    XuPaymentRequiredError,
+    XuSignalLimitError,
+    XuConnectionError,
+    XuValidationError,
+)
+
+logger = logging.getLogger(__name__)
+
+
+# =============================================================================
+# Data Models
+# =============================================================================
+
+@dataclass
+class XuSignal:
+    """Represents a trading signal from 1xu"""
+    id: str
+    market_id: str
+    market: str  # Human readable market name
+    direction: str  # 'yes' or 'no'
+    confidence: float  # 0-1
+    entry_price: float
+    suggested_size: str  # e.g., "$50-100"
+    whale_score: float
+    timestamp: datetime
+    expires_at: Optional[datetime] = None
+    
+    # Additional context
+    whale_activity: Optional[Dict] = None
+    market_stats: Optional[Dict] = None
+    
+    @classmethod
+    def from_dict(cls, data: Dict) -> 'XuSignal':
+        return cls(
+            id=data.get('id', data.get('_id', data.get('signal_id', ''))),
+            market_id=data.get('market_id', data.get('condition_id', '')),
+            market=data.get('market', data.get('question', '')),
+            direction=data.get('direction', data.get('action', 'yes')),
+            confidence=float(data.get('confidence', data.get('whale_score', 0.5))),
+            entry_price=float(data.get('entry_price', data.get('price', 0))),
+            suggested_size=data.get('suggested_size', '$50-100'),
+            whale_score=float(data.get('whale_score', 0.5)),
+            timestamp=datetime.fromisoformat(data['timestamp'].replace('Z', '+00:00')) if data.get('timestamp') else datetime.now(timezone.utc),
+            expires_at=datetime.fromisoformat(data['expires_at'].replace('Z', '+00:00')) if data.get('expires_at') else None,
+            whale_activity=data.get('whale_activity'),
+            market_stats=data.get('market_stats')
+        )
+    
+    def to_dict(self) -> Dict:
+        return {
+            'id': self.id,
+            'market_id': self.market_id,
+            'market': self.market,
+            'direction': self.direction,
+            'confidence': self.confidence,
+            'entry_price': self.entry_price,
+            'suggested_size': self.suggested_size,
+            'whale_score': self.whale_score,
+            'timestamp': self.timestamp.isoformat(),
+            'expires_at': self.expires_at.isoformat() if self.expires_at else None
+        }
+
+
+class TradeStatus(Enum):
+    SKIPPED = 'skipped'
+    EXECUTED = 'executed'
+    FAILED = 'failed'
+    CLOSED = 'closed'
+
+
+# =============================================================================
+# Main Client
+# =============================================================================
+
+class XuAgent:
+    """
+    Client for 1xu Trading Signals API.
+    
+    Example:
+        agent = XuAgent(api_key="1xu_your_key")
+        
+        # Get latest signals
+        signals = await agent.get_signals(limit=10)
+        
+        # Stream signals in real-time
+        async for signal in agent.stream_signals():
+            print(f"New signal: {signal.market} -> {signal.direction}")
+    """
+    
+    BASE_URL = "https://1xu.app"
+    
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = None,
+        timeout: int = 30,
+        auto_ack: bool = True,
+    ):
+        """
+        Initialize the 1xu Agent client.
+        
+        Args:
+            api_key: Your 1xu API key (get one at https://1xu.app/agent-dashboard)
+            base_url: Override the base URL (for testing)
+            timeout: Request timeout in seconds
+            auto_ack: Automatically acknowledge signals when received
+        """
+        if not api_key or not api_key.startswith('1xu_'):
+            raise XuValidationError("Invalid API key format. Expected '1xu_...'")
+        
+        self.api_key = api_key
+        self.base_url = (base_url or self.BASE_URL).rstrip('/')
+        self.timeout = timeout
+        self.auto_ack = auto_ack
+        
+        self._session: Optional[aiohttp.ClientSession] = None
+        self._agent_id: Optional[str] = None
+        self._tier: Optional[str] = None
+        
+        # Callbacks
+        self._on_signal: Optional[Callable[[XuSignal], Awaitable[None]]] = None
+        self._on_error: Optional[Callable[[Exception], Awaitable[None]]] = None
+    
+    async def _get_session(self) -> aiohttp.ClientSession:
+        """Get or create HTTP session"""
+        if self._session is None or self._session.closed:
+            self._session = aiohttp.ClientSession(
+                timeout=aiohttp.ClientTimeout(total=self.timeout),
+                headers={
+                    'X-API-Key': self.api_key,
+                    'User-Agent': f'xu-agent-sdk/0.1.0',
+                    'Content-Type': 'application/json'
+                }
+            )
+        return self._session
+    
+    async def close(self):
+        """Close the client session"""
+        if self._session and not self._session.closed:
+            await self._session.close()
+    
+    async def __aenter__(self):
+        return self
+    
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        await self.close()
+    
+    # ============ CORE API METHODS ============
+    
+    async def _request(self, method: str, endpoint: str, 
+                       data: Dict = None, params: Dict = None) -> Dict:
+        """Make an API request"""
+        session = await self._get_session()
+        url = f"{self.base_url}{endpoint}"
+        
+        try:
+            async with session.request(method, url, json=data, params=params) as resp:
+                result = await resp.json()
+                
+                # Handle errors
+                if resp.status == 401:
+                    raise XuAuthError(
+                        result.get('error', 'Authentication failed'),
+                        status_code=401,
+                        response=result
+                    )
+                elif resp.status == 402:
+                    raise XuPaymentRequiredError(
+                        result.get('error', 'Payment required'),
+                        pricing=result.get('pricing'),
+                        status_code=402,
+                        response=result
+                    )
+                elif resp.status == 429:
+                    raise XuRateLimitError(
+                        result.get('error', 'Rate limit exceeded'),
+                        retry_after=int(result.get('retry_after', 60)),
+                        status_code=429,
+                        response=result
+                    )
+                elif resp.status >= 400:
+                    # Check if it's a daily limit error
+                    if 'limit' in result.get('error', '').lower():
+                        raise XuSignalLimitError(
+                            result.get('error'),
+                            resets_in_seconds=result.get('resets_in_seconds', 0),
+                            status_code=resp.status,
+                            response=result
+                        )
+                    raise XuError(
+                        result.get('error', f'Request failed with status {resp.status}'),
+                        status_code=resp.status,
+                        response=result
+                    )
+                
+                return result
+                
+        except aiohttp.ClientError as e:
+            raise XuConnectionError(f"Connection error: {e}")
+    
+    # ============ AUTHENTICATION ============
+    
+    async def verify_connection(self) -> Dict:
+        """
+        Verify API key and get account information.
+        
+        Returns:
+            Dict with wallet, tier, features, and limits
+        """
+        result = await self._request('GET', '/api/a2a/access', params={'api_key': self.api_key})
+        
+        self._agent_id = result.get('wallet')
+        self._tier = result.get('tier')
+        
+        return result
+    
+    async def refresh_balance(self) -> Dict:
+        """
+        Refresh token balance and update tier if changed.
+        
+        Returns:
+            Dict with updated tier information
+        """
+        return await self._request('POST', '/api/a2a/refresh-balance', params={'api_key': self.api_key})
+    
+    @property
+    def agent_id(self) -> Optional[str]:
+        """Get the agent ID (wallet address)"""
+        return self._agent_id
+    
+    @property
+    def tier(self) -> Optional[str]:
+        """Get the current tier"""
+        return self._tier
+    
+    # ============ SIGNALS ============
+    
+    async def get_signals(
+        self,
+        limit: int = 10,
+        min_confidence: float = 0.5,
+        direction: str = None,
+    ) -> List[XuSignal]:
+        """
+        Get latest trading signals.
+        
+        Args:
+            limit: Maximum number of signals to return
+            min_confidence: Minimum confidence score (0-1)
+            direction: Filter by direction ('yes' or 'no')
+        
+        Returns:
+            List of XuSignal objects
+        """
+        params = {
+            'api_key': self.api_key,
+            'limit': limit,
+            'min_confidence': min_confidence,
+        }
+        if direction:
+            params['direction'] = direction
+        
+        result = await self._request('GET', '/api/v1/signals', params=params)
+        
+        signals = []
+        for s in result.get('signals', []):
+            signal = XuSignal.from_dict(s)
+            signals.append(signal)
+            
+            # Auto acknowledge
+            if self.auto_ack and self._agent_id:
+                try:
+                    await self.acknowledge_signal(signal.id, s.get('broadcast_time'))
+                except Exception as e:
+                    logger.warning(f"Failed to ack signal {signal.id}: {e}")
+        
+        return signals
+    
+    async def get_trial_signals(self) -> List[XuSignal]:
+        """
+        Get free trial signals (limited, delayed).
+        
+        Returns:
+            List of XuSignal objects
+        """
+        result = await self._request('GET', '/api/v1/signals/trial')
+        return [XuSignal.from_dict(s) for s in result.get('signals', [])]
+    
+    async def stream_signals(
+        self,
+        callback: Callable[[XuSignal], Awaitable[None]] = None,
+        min_confidence: float = 0.5,
+    ):
+        """
+        Stream signals in real-time (for Pro+ tiers with webhooks).
+        
+        This is a long-polling implementation. For true real-time,
+        register a webhook endpoint.
+        
+        Args:
+            callback: Async function to call for each signal
+            min_confidence: Minimum confidence filter
+        
+        Yields:
+            XuSignal objects as they arrive
+        """
+        last_signal_id = None
+        
+        while True:
+            try:
+                signals = await self.get_signals(limit=5, min_confidence=min_confidence)
+                
+                for signal in signals:
+                    if last_signal_id and signal.id == last_signal_id:
+                        break
+                    
+                    if callback:
+                        await callback(signal)
+                    else:
+                        yield signal
+                
+                if signals:
+                    last_signal_id = signals[0].id
+                
+                await asyncio.sleep(10)  # Poll every 10 seconds
+                
+            except XuRateLimitError as e:
+                await asyncio.sleep(e.retry_after)
+            except Exception as e:
+                if self._on_error:
+                    await self._on_error(e)
+                else:
+                    logger.error(f"Stream error: {e}")
+                await asyncio.sleep(30)
+    
+    # ============ TRADE REPORTING ============
+    
+    async def acknowledge_signal(
+        self,
+        signal_id: str,
+        broadcast_time: str = None
+    ) -> Dict:
+        """
+        Acknowledge receipt of a signal.
+        
+        Args:
+            signal_id: The signal ID
+            broadcast_time: When the signal was broadcast (ISO format)
+        
+        Returns:
+            Dict with latency information
+        """
+        return await self._request('POST', '/api/a2a/report/ack', data={
+            'agent_id': self._agent_id or self.api_key,
+            'signal_id': signal_id,
+            'broadcast_time': broadcast_time
+        })
+    
+    async def report_skip(
+        self,
+        signal_id: str,
+        reason: str,
+        market_id: str = None
+    ) -> Dict:
+        """
+        Report that a signal was intentionally skipped.
+        
+        Args:
+            signal_id: The signal ID
+            reason: Why you skipped (e.g., "below_threshold", "no_liquidity")
+            market_id: The market ID (optional)
+        
+        Returns:
+            Dict with success status
+        """
+        return await self._request('POST', '/api/a2a/report/skip', data={
+            'agent_id': self._agent_id or self.api_key,
+            'signal_id': signal_id,
+            'reason': reason,
+            'market_id': market_id
+        })
+    
+    async def report_failure(
+        self,
+        signal_id: str,
+        reason: str,
+        market_id: str = None
+    ) -> Dict:
+        """
+        Report that trade execution failed.
+        
+        Args:
+            signal_id: The signal ID
+            reason: Failure reason (e.g., "insufficient_funds", "slippage")
+            market_id: The market ID (optional)
+        
+        Returns:
+            Dict with success status
+        """
+        return await self._request('POST', '/api/a2a/report/failure', data={
+            'agent_id': self._agent_id or self.api_key,
+            'signal_id': signal_id,
+            'reason': reason,
+            'market_id': market_id
+        })
+    
+    async def report_trade(
+        self,
+        signal_id: str,
+        market_id: str,
+        direction: str,
+        size_usd: float,
+        entry_price: float,
+        tx_hash: str = None,
+        executed_at: datetime = None
+    ) -> Dict:
+        """
+        Report a successful trade execution.
+        
+        Args:
+            signal_id: The signal ID that triggered this trade
+            market_id: The Polymarket condition ID
+            direction: 'yes' or 'no'
+            size_usd: Position size in USD
+            entry_price: Entry price (0-1)
+            tx_hash: Transaction hash for on-chain verification (optional)
+            executed_at: Execution timestamp (optional)
+        
+        Returns:
+            Dict with trade_id and verification status
+        """
+        data = {
+            'agent_id': self._agent_id or self.api_key,
+            'signal_id': signal_id,
+            'market_id': market_id,
+            'direction': direction,
+            'size_usd': size_usd,
+            'entry_price': entry_price,
+        }
+        
+        if tx_hash:
+            data['tx_hash'] = tx_hash
+        if executed_at:
+            data['executed_at'] = executed_at.isoformat()
+        
+        return await self._request('POST', '/api/a2a/report/trade', data=data)
+    
+    async def report_close(
+        self,
+        trade_id: str,
+        exit_price: float,
+        pnl_usd: float,
+        tx_hash: str = None
+    ) -> Dict:
+        """
+        Report closing a position.
+        
+        Args:
+            trade_id: The trade ID from report_trade response
+            exit_price: Exit price (0-1)
+            pnl_usd: Realized profit/loss in USD
+            tx_hash: Close transaction hash (optional)
+        
+        Returns:
+            Dict with success status and is_winner flag
+        """
+        return await self._request('POST', '/api/a2a/report/close', data={
+            'agent_id': self._agent_id or self.api_key,
+            'trade_id': trade_id,
+            'exit_price': exit_price,
+            'pnl_usd': pnl_usd,
+            'tx_hash': tx_hash
+        })
+    
+    # ============ STATS ============
+    
+    async def get_my_stats(self) -> Dict:
+        """
+        Get your agent's performance statistics.
+        
+        Returns:
+            Dict with win_rate, total_pnl, trade counts, etc.
+        """
+        agent_id = self._agent_id or self.api_key
+        return await self._request('GET', f'/api/a2a/stats/{agent_id}')
+    
+    async def get_my_trades(self, limit: int = 50, status: str = None) -> List[Dict]:
+        """
+        Get your trade history.
+        
+        Args:
+            limit: Maximum number of trades
+            status: Filter by status ('executed', 'closed', 'skipped', 'failed')
+        
+        Returns:
+            List of trade records
+        """
+        agent_id = self._agent_id or self.api_key
+        params = {'limit': limit}
+        if status:
+            params['status'] = status
+        
+        result = await self._request('GET', f'/api/a2a/trades/{agent_id}', params=params)
+        return result.get('trades', [])
+    
+    async def get_leaderboard(self, metric: str = 'total_pnl_usd', limit: int = 20) -> List[Dict]:
+        """
+        Get the agent leaderboard.
+        
+        Args:
+            metric: Ranking metric ('total_pnl_usd', 'win_rate', 'verification_rate')
+            limit: Number of entries
+        
+        Returns:
+            List of leaderboard entries with rank
+        """
+        result = await self._request('GET', '/api/a2a/leaderboard', params={
+            'metric': metric,
+            'limit': limit
+        })
+        return result.get('leaderboard', [])
+    
+    # ============ USAGE ============
+    
+    async def get_usage(self) -> Dict:
+        """
+        Get current API usage and limits.
+        
+        Returns:
+            Dict with signals_used, remaining, rate_limits, etc.
+        """
+        return await self._request('GET', '/api/v1/usage', params={'api_key': self.api_key})
+    
+    async def get_pricing(self) -> Dict:
+        """
+        Get current pricing tiers and token requirements.
+        
+        Returns:
+            Dict with tiers, thresholds, and beta information
+        """
+        return await self._request('GET', '/api/a2a/tiers')
+    
+    # ============ WEBHOOKS ============
+    
+    async def register_webhook(self, url: str) -> Dict:
+        """
+        Register a webhook URL for real-time signal delivery.
+        
+        Args:
+            url: Your webhook endpoint URL
+        
+        Returns:
+            Dict with success status
+        """
+        return await self._request('POST', '/api/v1/webhook', data={
+            'api_key': self.api_key,
+            'url': url
+        })
+
+
+# =============================================================================
+# Convenience Functions
+# =============================================================================
+
+async def quick_start(api_key: str) -> XuAgent:
+    """
+    Quick start helper - creates and verifies an agent.
+    
+    Example:
+        agent = await quick_start("1xu_your_key")
+        signals = await agent.get_signals()
+    """
+    agent = XuAgent(api_key)
+    await agent.verify_connection()
+    return agent

xu_agent_sdk/exceptions.py

@@ -0,0 +1,48 @@
+"""
+xu-agent-sdk Exceptions
+"""
+
+
+class XuError(Exception):
+    """Base exception for xu-agent-sdk"""
+    def __init__(self, message: str, status_code: int = None, response: dict = None):
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.response = response or {}
+
+
+class XuAuthError(XuError):
+    """Authentication failed - invalid or missing API key"""
+    pass
+
+
+class XuRateLimitError(XuError):
+    """Rate limit exceeded - too many requests"""
+    def __init__(self, message: str, retry_after: int = 60, **kwargs):
+        super().__init__(message, **kwargs)
+        self.retry_after = retry_after
+
+
+class XuPaymentRequiredError(XuError):
+    """Payment required - need to upgrade tier or add funds"""
+    def __init__(self, message: str, pricing: dict = None, **kwargs):
+        super().__init__(message, **kwargs)
+        self.pricing = pricing or {}
+
+
+class XuSignalLimitError(XuError):
+    """Daily signal limit exceeded"""
+    def __init__(self, message: str, resets_in_seconds: int = 0, **kwargs):
+        super().__init__(message, **kwargs)
+        self.resets_in_seconds = resets_in_seconds
+
+
+class XuConnectionError(XuError):
+    """Network connection error"""
+    pass
+
+
+class XuValidationError(XuError):
+    """Invalid input parameters"""
+    pass

xu_agent_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,231 @@
+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

xu_agent_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+xu_agent_sdk/__init__.py,sha256=CWqEVKpiLez3f1K7uvj2cxNi37sxoWd8kliV2FMqJo8,971
+xu_agent_sdk/client.py,sha256=P-MsEmloNV1ucQSV-OBtvFqlgAsTH6okU2AT5Jluh1Q,19403
+xu_agent_sdk/exceptions.py,sha256=hf91w1CnOfbigbDtDLyvEbdafY_uBe_oUmM99VGjVsA,1331
+xu_agent_sdk-0.1.0.dist-info/METADATA,sha256=B6QfIsS3t_eMLVkGXECU8YFY-ORtGkX7BePLogpAo2E,5890
+xu_agent_sdk-0.1.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+xu_agent_sdk-0.1.0.dist-info/top_level.txt,sha256=QrlVZNXMuzTpGApQF3lMk2JgGdio-7SIE7pqRz6ad6k,13
+xu_agent_sdk-0.1.0.dist-info/RECORD,,

xu_agent_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

xu_agent_sdk-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+xu_agent_sdk