xu-agent-sdk 0.1.0

Python SDK for 1xu Trading Signals - Connect your autonomous agent to whale intelligence

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

pip install xu-agent-sdk

Quick Start

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

# 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

# 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

# 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

# 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)

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

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

Error Handling

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:

{
  "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: [e-mail]

License

MIT