market-microstructure Checked

# Hourly volume profile
hourly_volume = {}
for trade in trades:
    hour = trade["timestamp"] // 3600 * 3600
    hourly_volume.setdefault(hour, {"buy_vol": 0, "sell_vol": 0})
    if trade["side"] == "buy":
        hourly_volume[hour]["buy_vol"] += trade["volume_usd"]
    else:
        hourly_volume[hour]["sell_vol"] += trade["volume_usd"]

Key metrics from time profiles:

• **Peak hours** — when is the token most actively traded?
• **Volume trend** — is volume increasing, decreasing, or stable?
• **Volume anomalies** — spikes exceeding 3x the rolling average

### Size-Based Profiles

Classify trades into size buckets to separate whale activity from retail:

| Bucket | SOL Range | Typical Actor |

|--------|-----------|---------------|

| Micro | < 0.1 SOL | Dust / test trades |

| Small | 0.1 – 1 SOL | Retail traders |

| Medium | 1 – 10 SOL | Active traders |

| Large | 10 – 50 SOL | Serious positions |

| Whale | 50+ SOL | Whales / institutions |

Buyer/Seller Pressure Metrics

### Core Ratios

def compute_pressure(trades: list[dict], period_seconds: int = 3600) -> dict:
    """Compute buy/sell pressure metrics over a time period."""
    buy_vol = sum(t["volume_usd"] for t in trades if t["side"] == "buy")
    sell_vol = sum(t["volume_usd"] for t in trades if t["side"] == "sell")
    total_vol = buy_vol + sell_vol

    buy_trades = sum(1 for t in trades if t["side"] == "buy")
    sell_trades = sum(1 for t in trades if t["side"] == "sell")
    total_trades = buy_trades + sell_trades

    return {
        "buy_sell_ratio": buy_vol / sell_vol if sell_vol > 0 else float("inf"),
        "buy_volume_pct": buy_vol / total_vol if total_vol > 0 else 0.5,
        "net_flow_usd": buy_vol - sell_vol,
        "trade_count_ratio": buy_trades / total_trades if total_trades > 0 else 0.5,
    }

### Signal Interpretation

| Metric | Bullish | Neutral | Bearish |

|--------|---------|---------|---------|

| Buy Volume % | > 60% | 40–60% | < 40% |

| Net Flow | Positive, increasing | Near zero | Negative, increasing |

| Trade Count Ratio | > 0.55 | 0.45–0.55 | < 0.45 |

| Large Trade Ratio | High buy-side | Balanced | High sell-side |

See references/flow_signals.md for the full signal catalog and composite scoring.

Trade Size Distribution

Analyzing the distribution of trade sizes reveals market structure:

import statistics

def analyze_trade_sizes(trades: list[dict]) -> dict:
    """Analyze trade size distribution."""
    sizes = [t["volume_usd"] for t in trades]
    if not sizes:
        return {}

    return {
        "mean": statistics.mean(sizes),
        "median": statistics.median(sizes),
        "stdev": statistics.stdev(sizes) if len(sizes) > 1 else 0,
        "skew_indicator": statistics.mean(sizes) / statistics.median(sizes),
        "max_trade": max(sizes),
        "whale_pct": sum(s for s in sizes if s > 5000) / sum(sizes),
    }

**Interpreting skew:** A skew_indicator (mean/median) well above 1.0 indicates a

fat-tailed distribution — a few large trades dominate. This is normal for tokens with

whale interest but can also signal manipulation.

Momentum Signals from Trade Flow

### Volume Acceleration

Compare current period volume to the previous period:

acceleration = current_volume / previous_volume if previous_volume > 0 else 0

• **acceleration > 2.0** — volume surge, potential breakout or dump
• **acceleration 0.8–1.2** — stable activity
• **acceleration < 0.5** — dying interest

### Buy Pressure Acceleration

Track how the buy ratio changes over time:

current_buy_ratio = current_buy_vol / current_total_vol
previous_buy_ratio = prev_buy_vol / prev_total_vol
buy_momentum = current_buy_ratio - previous_buy_ratio

Positive buy_momentum with increasing volume is a strong accumulation signal.

Token Velocity

Token velocity measures how frequently tokens change hands:

velocity = daily_volume / circulating_supply

| Velocity | Interpretation |

|----------|---------------|

| < 0.01 | Low activity, illiquid, or strong holders |

| 0.01–0.05 | Normal trading activity |

| 0.05–0.20 | Active trading, possible speculation |

| > 0.20 | Very high turnover, potential wash trading |

High velocity combined with low unique trader count is a wash trading red flag.

Wash Trading Detection

Wash trading inflates volume to make a token appear more active than it truly is.

Key detection signals:

1. **Low unique trader ratio** — unique_wallets / trade_count < 0.3

2. **Volume/TVL anomaly** — daily_volume / tvl > 10 (volume vastly exceeds liquidity)

3. **Uniform trade sizes** — low entropy in trade size distribution

4. **Self-trading** — same wallet on both sides within short windows

5. **Funded-together clusters** — multiple wallets funded from the same source

See references/wash_trading.md for detailed detection methods and scoring.

Data Sources

### Birdeye API

Primary source for trade history on Solana tokens:

• GET /defi/txs/token — recent trades for a token
• GET /defi/ohlcv — candle data with volume
• GET /defi/price/volume — aggregated volume data

Requires API key. See the birdeye-api skill for endpoint details.

### D