chainstream-sdk 0.1.0__py3-none-any.whl

chainstream/stream/fields.py

@@ -0,0 +1,284 @@
+"""CEL field mappings for stream filter expressions."""
+
+import re
+from typing import Dict, List
+
+# CEL field mappings organized by subscription method
+CEL_FIELD_MAPPINGS: Dict[str, Dict[str, str]] = {
+    # Wallet balance subscription fields
+    "subscribe_wallet_balance": {
+        "wallet_address": "a",
+        "token_address": "ta",
+        "token_price_in_usd": "tpiu",
+        "balance": "b",
+        "timestamp": "t",
+    },
+    # Token candle subscription fields
+    "subscribe_token_candles": {
+        "open": "o",
+        "close": "c",
+        "high": "h",
+        "low": "l",
+        "volume": "v",
+        "resolution": "r",
+        "time": "t",
+        "number": "n",
+    },
+    # Token stats subscription fields
+    "subscribe_token_stats": {
+        "address": "a",
+        "timestamp": "t",
+        "buys_1m": "b1m",
+        "sells_1m": "s1m",
+        "buyers_1m": "be1m",
+        "sellers_1m": "se1m",
+        "buy_volume_in_usd_1m": "bviu1m",
+        "sell_volume_in_usd_1m": "sviu1m",
+        "price_1m": "p1m",
+        "open_in_usd_1m": "oiu1m",
+        "close_in_usd_1m": "ciu1m",
+        "buys_5m": "b5m",
+        "sells_5m": "s5m",
+        "buyers_5m": "be5m",
+        "sellers_5m": "se5m",
+        "buy_volume_in_usd_5m": "bviu5m",
+        "sell_volume_in_usd_5m": "sviu5m",
+        "price_5m": "p5m",
+        "open_in_usd_5m": "oiu5m",
+        "close_in_usd_5m": "ciu5m",
+        "buys_15m": "b15m",
+        "sells_15m": "s15m",
+        "buyers_15m": "be15m",
+        "sellers_15m": "se15m",
+        "buy_volume_in_usd_15m": "bviu15m",
+        "sell_volume_in_usd_15m": "sviu15m",
+        "price_15m": "p15m",
+        "open_in_usd_15m": "oiu15m",
+        "close_in_usd_15m": "ciu15m",
+        "buys_30m": "b30m",
+        "sells_30m": "s30m",
+        "buyers_30m": "be30m",
+        "sellers_30m": "se30m",
+        "buy_volume_in_usd_30m": "bviu30m",
+        "sell_volume_in_usd_30m": "sviu30m",
+        "price_30m": "p30m",
+        "open_in_usd_30m": "oiu30m",
+        "close_in_usd_30m": "ciu30m",
+        "buys_1h": "b1h",
+        "sells_1h": "s1h",
+        "buyers_1h": "be1h",
+        "sellers_1h": "se1h",
+        "buy_volume_in_usd_1h": "bviu1h",
+        "sell_volume_in_usd_1h": "sviu1h",
+        "price_1h": "p1h",
+        "open_in_usd_1h": "oiu1h",
+        "close_in_usd_1h": "ciu1h",
+        "buys_4h": "b4h",
+        "sells_4h": "s4h",
+        "buyers_4h": "be4h",
+        "sellers_4h": "se4h",
+        "buy_volume_in_usd_4h": "bviu4h",
+        "sell_volume_in_usd_4h": "sviu4h",
+        "price_4h": "p4h",
+        "open_in_usd_4h": "oiu4h",
+        "close_in_usd_4h": "ciu4h",
+        "buys_24h": "b24h",
+        "sells_24h": "s24h",
+        "buyers_24h": "be24h",
+        "sellers_24h": "se24h",
+        "buy_volume_in_usd_24h": "bviu24h",
+        "sell_volume_in_usd_24h": "sviu24h",
+        "price_24h": "p24h",
+        "price": "p",
+        "open_in_usd_24h": "oiu24h",
+        "close_in_usd_24h": "ciu24h",
+    },
+    # Token holder subscription fields
+    "subscribe_token_holders": {
+        "token_address": "a",
+        "holders": "h",
+        "top100_amount": "t100a",
+        "top10_amount": "t10a",
+        "top100_holders": "t100h",
+        "top10_holders": "t10h",
+        "top100_ratio": "t100r",
+        "top10_ratio": "t10r",
+        "timestamp": "ts",
+    },
+    # New token subscription fields
+    "subscribe_new_token": {
+        "token_address": "a",
+        "name": "n",
+        "symbol": "s",
+        "created_at_ms": "cts",
+    },
+    # Token supply subscription fields
+    "subscribe_token_supply": {
+        "token_address": "a",
+        "supply": "s",
+        "timestamp": "ts",
+    },
+    # DEX pool balance subscription fields
+    "subscribe_dex_pool_balance": {
+        "pool_address": "a",
+        "token_a_address": "taa",
+        "token_a_liquidity_in_usd": "taliu",
+        "token_b_address": "tba",
+        "token_b_liquidity_in_usd": "tbliu",
+    },
+    # Token liquidity subscription fields
+    "subscribe_token_liquidity": {
+        "token_address": "a",
+        "metric_type": "t",
+        "value": "v",
+        "timestamp": "ts",
+    },
+    # New token metadata subscription fields
+    "subscribe_new_tokens_metadata": {
+        "token_address": "a",
+        "name": "n",
+        "symbol": "s",
+        "image_url": "iu",
+        "description": "de",
+        "social_media": "sm",
+        "created_at_ms": "cts",
+    },
+    # Token trade subscription fields
+    "subscribe_token_trades": {
+        "token_address": "a",
+        "timestamp": "t",
+        "kind": "k",
+        "buy_amount": "ba",
+        "buy_amount_in_usd": "baiu",
+        "buy_token_address": "btma",
+        "buy_token_name": "btn",
+        "buy_token_symbol": "bts",
+        "buy_wallet_address": "bwa",
+        "sell_amount": "sa",
+        "sell_amount_in_usd": "saiu",
+        "sell_token_address": "stma",
+        "sell_token_name": "stn",
+        "sell_token_symbol": "sts",
+        "sell_wallet_address": "swa",
+        "tx_hash": "h",
+    },
+    # Wallet token PnL subscription fields
+    "subscribe_wallet_pnl": {
+        "wallet_address": "a",
+        "token_address": "ta",
+        "token_price_in_usd": "tpiu",
+        "timestamp": "t",
+        "open_time": "ot",
+        "last_time": "lt",
+        "close_time": "ct",
+        "buy_amount": "ba",
+        "buy_amount_in_usd": "baiu",
+        "buy_count": "bs",
+        "buy_count_30d": "bs30d",
+        "buy_count_7d": "bs7d",
+        "sell_amount": "sa",
+        "sell_amount_in_usd": "saiu",
+        "sell_count": "ss",
+        "sell_count_30d": "ss30d",
+        "sell_count_7d": "ss7d",
+        "held_duration_timestamp": "hdts",
+        "average_buy_price_in_usd": "abpiu",
+        "average_sell_price_in_usd": "aspiu",
+        "unrealized_profit_in_usd": "upiu",
+        "unrealized_profit_ratio": "upr",
+        "realized_profit_in_usd": "rpiu",
+        "realized_profit_ratio": "rpr",
+        "total_realized_profit_in_usd": "trpiu",
+        "total_realized_profit_ratio": "trr",
+    },
+    # Wallet trade subscription fields
+    "subscribe_wallet_trade": {
+        "token_address": "a",
+        "timestamp": "t",
+        "kind": "k",
+        "buy_amount": "ba",
+        "buy_amount_in_usd": "baiu",
+        "buy_token_address": "btma",
+        "buy_token_name": "btn",
+        "buy_token_symbol": "bts",
+        "buy_wallet_address": "bwa",
+        "sell_amount": "sa",
+        "sell_amount_in_usd": "saiu",
+        "sell_token_address": "stma",
+        "sell_token_name": "stn",
+        "sell_token_symbol": "sts",
+        "sell_wallet_address": "swa",
+        "tx_hash": "h",
+    },
+    # Token max liquidity subscription fields
+    "subscribe_token_max_liquidity": {
+        "token_address": "a",
+        "pool_address": "p",
+        "liquidity_in_usd": "liu",
+        "liquidity_in_native": "lin",
+        "timestamp": "ts",
+    },
+    # Token total liquidity subscription fields
+    "subscribe_token_total_liquidity": {
+        "token_address": "a",
+        "liquidity_in_usd": "liu",
+        "liquidity_in_native": "lin",
+        "pool_count": "pc",
+        "timestamp": "ts",
+    },
+}
+
+
+def get_field_mappings(method_name: str) -> Dict[str, str]:
+    """Get field mappings for a specific subscription method.
+
+    Args:
+        method_name: The subscription method name.
+
+    Returns:
+        A dictionary mapping long field names to short field names.
+    """
+    return CEL_FIELD_MAPPINGS.get(method_name, {})
+
+
+def replace_filter_fields(filter_expr: str, method_name: str) -> str:
+    """Replace long field names with short field names in filter expressions.
+
+    Automatically adds meta. prefix if not present.
+
+    Args:
+        filter_expr: The filter expression to process.
+        method_name: The subscription method name.
+
+    Returns:
+        The processed filter expression with short field names.
+    """
+    if not filter_expr:
+        return filter_expr
+
+    field_mappings = get_field_mappings(method_name)
+    result = filter_expr
+
+    # Replace all long field names with short field names
+    for long_field, short_field in field_mappings.items():
+        # Pattern 1: fieldName (without meta. prefix)
+        pattern1 = rf"\b{re.escape(long_field)}\b"
+        # Pattern 2: meta.fieldName (with meta. prefix)
+        pattern2 = rf"\bmeta\.{re.escape(long_field)}\b"
+
+        result = re.sub(pattern1, f"meta.{short_field}", result)
+        result = re.sub(pattern2, f"meta.{short_field}", result)
+
+    return result
+
+
+def get_available_fields(method_name: str) -> List[str]:
+    """Get available field names for a specific subscription method.
+
+    Args:
+        method_name: The subscription method name.
+
+    Returns:
+        A list of available field names.
+    """
+    return list(get_field_mappings(method_name).keys())

chainstream/stream/models.py

@@ -0,0 +1,415 @@
+"""Data models for the ChainStream WebSocket Stream API."""
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Optional
+
+
+class TokenActivityType(str, Enum):
+    """Token activity type."""
+
+    SELL = "sell"
+    BUY = "buy"
+    ADD_LIQUIDITY = "add_liquidity"
+    REMOVE_LIQUIDITY = "remove_liquidity"
+
+
+class ChannelType(str, Enum):
+    """Channel type for subscriptions."""
+
+    NEW = "new"
+    HOT = "trending"
+    US_STOCKS = "us_stocks"
+    COMPLETED = "completed"
+    GRADUATED = "graduated"
+
+
+class MetricType(str, Enum):
+    """Metric type for measurements."""
+
+    LIQUIDITY_IN_USD = "liquidity_in_usd"
+    MIGRATED_RATIO = "migrated_ratio"
+
+
+class RankingType(str, Enum):
+    """Ranking type for token rankings."""
+
+    NEW = "new"
+    HOT = "trending"
+    STOCKS = "stocks"
+    FINAL_STRETCH = "completed"
+    MIGRATED = "graduated"
+
+
+class Dex(str, Enum):
+    """DEX (Decentralized Exchange) type."""
+
+    PUMP_FUN = "pump_fun"
+    RAYDIUM_LAUNCHPAD = "raydium_launchpad"
+    METEORA_DYNAMIC_BOUNDING_CURVE = "meteora_dynamic_bounding_curve"
+    BONK_FUN = "bonk_fun"
+    BOOP_FUN = "boop_fun"
+    MOONIT_FUN = "moonit_fun"
+
+
+class Resolution(str, Enum):
+    """Candle resolution for time-based data."""
+
+    S1 = "1s"
+    S15 = "15s"
+    S30 = "30s"
+    M1 = "1m"
+    M5 = "5m"
+    M15 = "15m"
+    H1 = "1h"
+    H4 = "4h"
+    H12 = "12h"
+    D1 = "1d"
+
+
+@dataclass
+class TokenActivity:
+    """Token activity data."""
+
+    address: str
+    price_usd: str
+    amount: str
+    activity_type: TokenActivityType
+    tx_hash: str
+    timestamp: int
+
+
+@dataclass
+class TokenStat:
+    """Token statistics with multi-timeframe data."""
+
+    address: str
+    timestamp: int
+
+    # 1-minute data
+    buys_1m: Optional[int] = None
+    sells_1m: Optional[int] = None
+    buyers_1m: Optional[int] = None
+    sellers_1m: Optional[int] = None
+    buy_volume_in_usd_1m: Optional[str] = None
+    sell_volume_in_usd_1m: Optional[str] = None
+    price_1m: Optional[str] = None
+    open_in_usd_1m: Optional[str] = None
+    close_in_usd_1m: Optional[str] = None
+
+    # 5-minute data
+    buys_5m: Optional[int] = None
+    sells_5m: Optional[int] = None
+    buyers_5m: Optional[int] = None
+    sellers_5m: Optional[int] = None
+    buy_volume_in_usd_5m: Optional[str] = None
+    sell_volume_in_usd_5m: Optional[str] = None
+    price_5m: Optional[str] = None
+    open_in_usd_5m: Optional[str] = None
+    close_in_usd_5m: Optional[str] = None
+
+    # 15-minute data
+    buys_15m: Optional[int] = None
+    sells_15m: Optional[int] = None
+    buyers_15m: Optional[int] = None
+    sellers_15m: Optional[int] = None
+    buy_volume_in_usd_15m: Optional[str] = None
+    sell_volume_in_usd_15m: Optional[str] = None
+    price_15m: Optional[str] = None
+    open_in_usd_15m: Optional[str] = None
+    close_in_usd_15m: Optional[str] = None
+
+    # 30-minute data
+    buys_30m: Optional[int] = None
+    sells_30m: Optional[int] = None
+    buyers_30m: Optional[int] = None
+    sellers_30m: Optional[int] = None
+    buy_volume_in_usd_30m: Optional[str] = None
+    sell_volume_in_usd_30m: Optional[str] = None
+    price_30m: Optional[str] = None
+    open_in_usd_30m: Optional[str] = None
+    close_in_usd_30m: Optional[str] = None
+
+    # 1-hour data
+    buys_1h: Optional[int] = None
+    sells_1h: Optional[int] = None
+    buyers_1h: Optional[int] = None
+    sellers_1h: Optional[int] = None
+    buy_volume_in_usd_1h: Optional[str] = None
+    sell_volume_in_usd_1h: Optional[str] = None
+    price_1h: Optional[str] = None
+    open_in_usd_1h: Optional[str] = None
+    close_in_usd_1h: Optional[str] = None
+
+    # 4-hour data
+    buys_4h: Optional[int] = None
+    sells_4h: Optional[int] = None
+    buyers_4h: Optional[int] = None
+    sellers_4h: Optional[int] = None
+    buy_volume_in_usd_4h: Optional[str] = None
+    sell_volume_in_usd_4h: Optional[str] = None
+    price_4h: Optional[str] = None
+    open_in_usd_4h: Optional[str] = None
+    close_in_usd_4h: Optional[str] = None
+
+    # 24-hour data
+    buys_24h: Optional[int] = None
+    sells_24h: Optional[int] = None
+    buyers_24h: Optional[int] = None
+    sellers_24h: Optional[int] = None
+    buy_volume_in_usd_24h: Optional[str] = None
+    sell_volume_in_usd_24h: Optional[str] = None
+    price_24h: Optional[str] = None
+    open_in_usd_24h: Optional[str] = None
+    close_in_usd_24h: Optional[str] = None
+
+    # Current price
+    price: Optional[str] = None
+
+
+@dataclass
+class TokenHolder:
+    """Token holder information."""
+
+    token_address: str
+    timestamp: int
+    holders: Optional[int] = None
+    top100_amount: Optional[str] = None
+    top10_amount: Optional[str] = None
+    top100_holders: Optional[int] = None
+    top10_holders: Optional[int] = None
+    top100_ratio: Optional[str] = None
+    top10_ratio: Optional[str] = None
+    creators_holders: Optional[int] = None
+    creators_amount: Optional[str] = None
+    creators_ratio: Optional[str] = None
+
+
+@dataclass
+class WalletBalance:
+    """Wallet balance data."""
+
+    wallet_address: str
+    token_address: str
+    token_price_in_usd: str
+    balance: str
+    timestamp: int
+
+
+@dataclass
+class WalletPnl:
+    """Wallet profit and loss data."""
+
+    wallet_address: str
+    buys: int
+    buy_amount: str
+    buy_amount_in_usd: str
+    average_buy_price_in_usd: str
+    sell_amount: str
+    sell_amount_in_usd: str
+    sells: int
+    wins: int
+    win_ratio: str
+    pnl_in_usd: str
+    average_pnl_in_usd: str
+    pnl_ratio: str
+    profitable_days: int
+    losing_days: int
+    tokens: int
+    resolution: str
+
+
+@dataclass
+class DexProtocol:
+    """DEX protocol information."""
+
+    program_address: Optional[str] = None
+    protocol_family: Optional[str] = None
+    protocol_name: Optional[str] = None
+
+
+@dataclass
+class NewToken:
+    """New token data."""
+
+    token_address: str
+    name: str
+    symbol: str
+    created_at_ms: int
+    decimals: Optional[int] = None
+    launch_from: Optional[DexProtocol] = None
+
+
+@dataclass
+class TokenSupply:
+    """Token supply data."""
+
+    token_address: str
+    timestamp: int
+    supply: Optional[str] = None
+    market_cap_in_usd: Optional[str] = None
+
+
+@dataclass
+class DexPoolBalance:
+    """DEX pool balance data."""
+
+    pool_address: str
+    token_a_address: str
+    token_a_liquidity_in_usd: str
+    token_b_address: str
+    token_b_liquidity_in_usd: str
+
+
+@dataclass
+class TokenLiquidity:
+    """Token liquidity data."""
+
+    token_address: str
+    metric_type: MetricType
+    value: str
+    timestamp: int
+
+
+@dataclass
+class TokenMaxLiquidity:
+    """Token max liquidity data (max liquidity in a single pool)."""
+
+    token_address: str
+    pool_address: str
+    liquidity_in_usd: str
+    liquidity_in_native: str
+    timestamp: int
+
+
+@dataclass
+class TokenTotalLiquidity:
+    """Token total liquidity data (total liquidity across all pools)."""
+
+    token_address: str
+    liquidity_in_usd: str
+    liquidity_in_native: str
+    pool_count: int
+    timestamp: int
+
+
+@dataclass
+class TokenBondingCurve:
+    """Token bonding curve data."""
+
+    token_address: Optional[str] = None
+    progress_ratio: Optional[str] = None
+
+
+@dataclass
+class SocialMedia:
+    """Social media links."""
+
+    twitter: Optional[str] = None
+    telegram: Optional[str] = None
+    website: Optional[str] = None
+    tiktok: Optional[str] = None
+    discord: Optional[str] = None
+    facebook: Optional[str] = None
+    github: Optional[str] = None
+    instagram: Optional[str] = None
+    linkedin: Optional[str] = None
+    medium: Optional[str] = None
+    reddit: Optional[str] = None
+    youtube: Optional[str] = None
+    bitbucket: Optional[str] = None
+
+
+@dataclass
+class TokenMetadata:
+    """Token metadata."""
+
+    token_address: str
+    name: Optional[str] = None
+    decimals: Optional[int] = None
+    symbol: Optional[str] = None
+    image_url: Optional[str] = None
+    description: Optional[str] = None
+    social_media: Optional[SocialMedia] = None
+    created_at_ms: Optional[int] = None
+    launch_from: Optional[DexProtocol] = None
+    migrated_to: Optional[DexProtocol] = None
+
+
+@dataclass
+class TokenCandle:
+    """Token candlestick data."""
+
+    open: str
+    close: str
+    high: str
+    low: str
+    volume: str
+    resolution: str
+    time: int
+    number: int
+
+
+@dataclass
+class TradeActivity:
+    """Trade activity data."""
+
+    token_address: str
+    timestamp: int
+    kind: str
+    buy_amount: str
+    buy_amount_in_usd: str
+    buy_token_address: str
+    buy_token_name: str
+    buy_token_symbol: str
+    buy_wallet_address: str
+    sell_amount: str
+    sell_amount_in_usd: str
+    sell_token_address: str
+    sell_token_name: str
+    sell_token_symbol: str
+    sell_wallet_address: str
+    tx_hash: str
+
+
+@dataclass
+class WalletTokenPnl:
+    """Wallet token profit and loss data."""
+
+    wallet_address: str
+    token_address: str
+    token_price_in_usd: str
+    timestamp: int
+    open_time: int
+    last_time: int
+    close_time: int
+    buy_amount: str
+    buy_amount_in_usd: str
+    buy_count: int
+    buy_count_30d: int
+    buy_count_7d: int
+    sell_amount: str
+    sell_amount_in_usd: str
+    sell_count: int
+    sell_count_30d: int
+    sell_count_7d: int
+    held_duration_timestamp: int
+    average_buy_price_in_usd: str
+    average_sell_price_in_usd: str
+    unrealized_profit_in_usd: str
+    unrealized_profit_ratio: str
+    realized_profit_in_usd: str
+    realized_profit_ratio: str
+    total_realized_profit_in_usd: str
+    total_realized_profit_ratio: str
+
+
+@dataclass
+class RankingTokenList:
+    """Ranking token list data."""
+
+    metadata: Optional[TokenMetadata] = None
+    holder: Optional[TokenHolder] = None
+    supply: Optional[TokenSupply] = None
+    stat: Optional[TokenStat] = None
+    bonding_curve: Optional[TokenBondingCurve] = None