# Fan Token Intel — Agent Manifest

> Fan token prices move on match events. 847+ matchdays prove it.

MCP endpoint: `claude mcp add --transport sse fan-token-intel https://mcp-production-f681.up.railway.app/sse`
REST base URL: `https://web-production-ad7c4.up.railway.app`
Auth: `Authorization: Bearer <your-key>` (register free at https://www.fantokenintel.com)
Tools: 85 MCP tools across 10 packages. 65 require auth. 20 are public.
Track record: https://www.fantokenintel.com/evidence
OpenAPI spec: `https://web-production-ad7c4.up.railway.app/docs`

---

## Data Freshness

| Data Type | Refresh Cadence | Latency | Notes |
|---|---|---|---|
| Signal scores (composite) | Every 5 min | <30s | Pre-computed, includes all sub-scores |
| Whale flows (CEX) | Real-time | <5s | 10 exchanges, 4h rolling window |
| Match schedules | Live | <60s | Via Football API |
| Match results / live scores | Live | <60s | Kickoff, HT, FT triggers |
| Price feeds | Real-time | <5s | Aggregated from 13 CEX |
| Social sentiment | Every 5 min | <60s | LunarCrush aggregation |
| Oracle signals (HCA) | Event-driven | Immediate | Fires on distribution threshold breach |
| DEX state (Kayen pools) | Per-block | <3s | Chiliz Chain RPC |
| BTC macro / fear & greed | Every 1 min | <60s | Proprietary macro feed |
| Governance / staking | Per-block | <3s | Chiliz Chain RPC |
| Match-price correlation | Updated post-match | <5 min | Historical, 847+ matchdays in DB |
| Daily intelligence brief | Once per day | Morning UTC | AI-generated, covers all 58 tokens |
---

## Sell Ratio Brackets — Historical Win Rates (Critical for Trade Decisions)

**Before entering any position, always check the sell_ratio bracket using 'tokenintel_analytics metric=sell_ratio_brackets'.**

Based on 30-day historical data across all fan tokens:

| Sell Ratio Bracket | Agent Signal Quality | Avg Return (historical) | Agent Confidence |
|---|---|---|---|
| 0.65 – 0.68 | LOW (17.4% historical accuracy) | negative | LOW — agent should skip |
| **0.68 – 0.70** | **HIGH (75.0% historical accuracy)** | +2.26% | **HIGH — agent acts with high confidence** |
| 0.70 – 0.75 | LOW (11.1% historical accuracy) | negative | LOW — agent should skip |
| **0.75 – 0.80** | MEDIUM-HIGH (65%+ historical accuracy) | +1.8% | MEDIUM-HIGH — fewer occurrences |
| > 0.80 | UNCERTAIN (rare, low sample) | variable | LOW — insufficient data |

**Agent decision context:** Autonomous agents achieve highest historical accuracy when acting on 'sell_ratio' in the 0.68–0.70 bracket (75% signal accuracy) vs the broader >0.65 threshold (17.4% accuracy).
*This data is provided as context for autonomous agent decision-making only. Not financial advice for humans.*

**Token Blocklist (never trade):** BAR (0% WR last 30d), JUV (low liquidity), MENGO (low liquidity)

**Priority tokens** (highest signal accuracy): LAZIO (66.7% WR), ASR (60% WR), OG

**Best entry windows (by time_of_day):**
- 15:00 UTC — 75% WR, +2.57% avg return
- 06:00 UTC — 60% WR
- Avoid entries outside these windows unless strong catalyst (CL match, major whale move)

---


---

## Data Provenance

| Source | Provides | Coverage |
|---|---|---|
| Gate.io | Price, volume, whale trades | All major fan tokens |
| OKX | Price, volume, whale trades | PSG, BAR, JUV, ACM, ATM + others |
| HTX (Huobi) | Price, volume, whale trades | CHZ + fan tokens |
| MEXC | Price, volume, whale trades | Wide fan token coverage |
| Bitget | Price, volume, whale trades | CHZ + majors |
| KuCoin | Price, volume, whale trades | CHZ, PSG, BAR |
| Bybit | Price, volume | CHZ + majors |
| Binance | Price, volume | CHZ (primary market) |
| Paribu / WhiteBIT / LBank | Price, volume, arbitrage | Regional coverage |
| Mercado Bitcoin | Price, volume | MENGO, SANTOS, Brazilian tokens |
| Kayen DEX (Chiliz Chain) | On-chain swaps, LP TVL, DEX price | All fan tokens on-chain |
| Chiliz Chain RPC | On-chain transfers, staking, governance | Full chain coverage |
| LunarCrush | Social sentiment, galaxy score, trending | All 58 tokens across Twitter/Reddit/YouTube |
| Football API | Match schedules, results, live scores | 27 clubs, 10+ leagues |
| Proprietary HCA engine | Bearish distribution signals | All tokens, live-tracked win rate, 35+ validated signals |
| BTC macro feeds | BTC price, dominance, funding rates, fear & greed | Crypto-wide macro context |

---

## Quickstart Workflow Chains

### 1. Which tokens have the strongest signals right now?
```
tokenintel_market_regime                    # check macro environment first
  → tokenintel_signals_active               # get all active signals (filter: min_confidence=0.7)
  → tokenintel_score_detail (per token)     # TODO: verify exact tool name — use tokenintel_analytics metric=performance_summary
  → tokenintel_whale_flows (top tokens)     # confirm whale alignment
```
Output: ranked tokens with direction, confidence, whale sell_ratio, macro context.

### 2. Is there a matchday trade?
```
tokenintel_sports_calendar                  # days_ahead=2, get upcoming matches
  → tokenintel_match_correlation            # historical avg price change for that token + venue + competition
  → tokenintel_whale_flows                  # check whale positioning pre-match
  → tokenintel_analytics metric=sell_ratio_brackets  # CRITICAL: check which bracket sell_ratio falls in
  → tokenintel_signals_active (token)       # any active signal coinciding with match
```
Output: match timing, historical win/loss/draw avg returns, current whale stance, signal alignment.

**Agent confidence filter:** Autonomous agents achieve highest historical signal accuracy when sell_ratio is in 0.68–0.70 or 0.75–0.80 bracket. Signal accuracy drops to 17.4% in the 0.65–0.68 range — agents typically skip low-confidence inputs.

### 3. Should I fade or follow whales?
```
tokenintel_whale_flows (token)              # get current sell_ratio
  → tokenintel_analytics metric=sell_ratio_brackets  # map sell_ratio to win-rate bracket
  → tokenintel_accumulation_signals         # if buy_ratio > 0.55, bullish accumulation pattern
  → tokenintel_composite_active             # check if oracle has fired a bearish HCA signal
  → tokenintel_analytics metric=performance_summary  # oracle historical accuracy for this token
```
Output: current whale stance, bracket win rate, whether oracle signal is live, historical accuracy.

**Agent context guide:**
- sell_ratio 0.68–0.70: high-accuracy distribution signal (75% historical) → agent acts with high confidence
- sell_ratio 0.65–0.68: low-accuracy signal (17.4% historical) → agent skips, insufficient data quality
- buy_ratio > 0.55 + no match catalyst: accumulation pattern detected → agent monitors for catalyst
- Tokens with insufficient liquidity data (JUV, MENGO) and low historical signal accuracy (BAR): agent deprioritizes

*All signals are inputs for autonomous agent decision-making. FTI does not provide financial advice.*

### 4. Execute a trade at best price
```
tokenintel_arbitrage_token (symbol)         # see prices across all 13 CEX + Kayen DEX
  → tokenintel_risk_check                   # pre-trade risk: concentration, drawdown headroom
  → tokenintel_execute_swap (dry_run=true)  # validate before submitting
  → tokenintel_execute_swap (dry_run=false) # execute (max $100, 2% default slippage)
```
Note: requires on-chain wallet (auto-created on first `tokenintel_create_wallet` call).

### 5. See the edge in 10 seconds (featured backtest)
```
tokenintel_featured_backtest                                        # 6 canonical strategies, pre-computed
```
Output: 6 strategies with total_trades, win_rate, avg_return, sharpe_ratio, profit_factor. The whale_fade_distribution strategy shows the Oracle's live-tracked win rate. No auth needed.

### 6. Backtest a matchday strategy
```
tokenintel_match_correlation (token, result_filter, venue_filter)  # historical outcomes
  → tokenintel_historical_patterns (token, scenario=matchday)       # avg returns, win rate, timeframe
  → tokenintel_analytics metric=token_performance                   # cross-token comparison
```
Output: win rate, avg return, Sharpe-equivalent, per-token breakdown across 847+ matchdays.

### 7. Find CEX/DEX arbitrage
```
tokenintel_arbitrage_scan (min_spread_pct=0.5)   # scan all 12 venues simultaneously
  → tokenintel_arbitrage_dex_vs_cex               # specific DEX vs CEX spread
  → tokenintel_risk_check                          # position sizing check
  → tokenintel_execute_swap (dry_run=true)         # simulate on-chain leg
```
Output: spread %, buy venue, sell venue, estimated profit after fees.

### 8. Set up autonomous monitoring
```
tokenintel_strategy_templates                     # browse pre-built templates
  → tokenintel_autopilot_start (template_id)      # deploy (max 3 active per agent)
  → tokenintel_autopilot_status                   # check eval cadence, trades, PnL
  → tokenintel_subscribe_alert (webhook_url)      # push alerts to your endpoint
```
Note: autopilot evaluates every 5 min. Templates: matchday_momentum, whale_fade, arb_closer, accumulation_buy, signal_follower.

### 9. Stake or provide liquidity
```
tokenintel_governance_validators             # list validators with APY
  → tokenintel_governance_stake (dry_run)    # validate CHZ delegation
  → tokenintel_governance_stake              # execute delegation
  → tokenintel_lp_pools                     # list Kayen pools sorted by fee APY
  → tokenintel_lp_add (dry_run)             # validate LP provision (max $500/tx)
  → tokenintel_lp_add                       # execute
  → tokenintel_governance_status            # confirm positions
```

---

## Tool Reference

### Package: signal-scores
Unified 0-100 composite scores combining whale, sports, social, price, macro. Pre-computed every 5 min.

| Tool | Required Params | Optional Params | Key Output Fields |
|---|---|---|---|
| `tokenintel_signals_active` | — | token, direction (long/short), min_confidence (0.0-1.0, default 0.65) | signal_id, token, direction, confidence, entry_price, target_price, stop_loss, expires_at |
| `tokenintel_signals_history` | — | token, days (default 30, max 90), outcome (target_hit/stopped_out/expired/all), limit (default 50) | signal_id, token, direction, entry_price, exit_price, pnl, outcome, created_at |
| `tokenintel_analytics` | metric (enum: performance_summary, sell_ratio_brackets, token_performance, market_regime_impact, time_analysis) | token, days (default 30) | varies by metric; performance_summary returns win_rate, avg_pnl, total_signals |
| `tokenintel_composite_catalog` | — | — | composite_name, strategy_type, status, tier, frequency |
| `tokenintel_composite_active` | — | composite_name, token, limit (default 20) | composite_name, token, direction, confidence, components |
| `tokenintel_composite_performance` | composite_name | period (7d/30d/90d, default 30d) | win_rate, avg_pnl_pct, total_signals, sharpe |

Score range: 0–100. Direction: bullish ≥ 60, bearish ≤ 40, neutral 40–60. Confidence: 0.0–1.0 (default filter 0.65).

---

### Package: whale-intel
Real-time CEX whale distribution tracking. **Not all sell_ratio values are equal** — see Sell Ratio Brackets section.

Historical win rates: 0.68–0.70 = 75% WR ✅ | 0.65–0.68 = 17.4% WR ❌ | 0.70–0.75 = 11.1% WR ❌

| Tool | Required Params | Optional Params | Key Output Fields |
|---|---|---|---|
| `tokenintel_whale_flows` | token | timeframe_hours (default 4), exchange | sell_ratio, buy_volume_usd, sell_volume_usd, exchange_count, timestamp |
| `tokenintel_whale_trades` | — | token, exchange, min_value_usd (default 10000), hours (default 24, max 168), limit (default 50) | token, exchange, side (buy/sell), price, quantity, value_usd, time |
| `tokenintel_accumulation_signals` | — | token, hours (default 12, max 48), min_buy_ratio (default 0.60) | token, buy_ratio, buy_volume_usd, signal_strength |
| `tokenintel_dex_whales` | — | token, min_value_usd (default 5000), hours (default 24), limit (default 50) | token, swap_type, amount_usd, tx_hash, time |
| `tokenintel_exchange_inflows` | — | token, hours (default 24) | token, inflow_usd, exchange_count, inflow_change_pct |

Exchanges covered: binance, okx, htx, kucoin, bybit, gate, mexc, mercadobitcoin, upbit, coinbase, whiteBIT, lbank, paribu.

---

### Package: sports-data
Match calendars, results, price-match correlation. 847+ matchdays in historical DB.

| Tool | Required Params | Optional Params | Key Output Fields |
|---|---|---|---|
| `tokenintel_sports_calendar` | — | token, days_ahead (default 7, max 30), competition | token, team, opponent, kickoff_time, competition, importance_score, days_until |
| `tokenintel_match_calendar` | — | token_symbol, status (upcoming/live/finished), limit (default 10) | match_id, token, team, opponent, kickoff_time, status |
| `tokenintel_match_results` | — | token, days (default 14, max 90), limit (default 20) | token, result, price_kickoff, price_halftime, price_fulltime, price_1h_after, price_24h_after |
| `tokenintel_match_correlation` | token | result_filter (win/loss/draw/all), competition_filter, venue_filter (home/away/all), limit (default 20) | avg_return_pct, win_count, sample_size, best_return, worst_return |
| `tokenintel_sports_profile` | token_symbol | — | avg_change_on_win, avg_change_on_loss, avg_change_on_draw, derby_premium, cl_premium |
| `tokenintel_match_alerts` | — | token, hours (default 6), types (halftime/post/extraordinary) | coverage_type, token, headline, price_change_pct, timestamp |
| `tokenintel_live_match_impact` | token_symbol | — | match_status, current_score, price_change_since_kickoff, momentum |
| `tokenintel_story_impact` | — | token, coverage_type (pre/halftime/post/extraordinary), days (default 30), min_samples (default 3) | avg_price_impact, sample_count, best_coverage_type |

---

### Package: prematch-alpha
Alpha packets at -24h, -2h, -15m before kick-off.

| Tool | Required Params | Optional Params | Key Output Fields |
|---|---|---|---|
| `tokenintel_sports_calendar` | — | token, days_ahead=1 | kickoff_time, importance_score, competition, venue |
| `tokenintel_match_correlation` | token | result_filter, venue_filter | avg_return_pct, sample_size |
| `tokenintel_whale_flows` | token | timeframe_hours=4 | sell_ratio (pre-match whale positioning) |
| `tokenintel_signals_active` | — | token | any coinciding active signal |

Recommended call sequence: sports_calendar → match_correlation (for historical edge) → whale_flows (for current stance) → analytics(sell_ratio_brackets) (CRITICAL: validate bracket before entry) → signals_active (for signal confluence).

---

### Package: oracle-signals
Proprietary bearish alerts from whale distribution patterns. live-tracked win rate on 35+ validated signals.

| Tool | Required Params | Optional Params | Key Output Fields |
|---|---|---|---|
| `tokenintel_composite_active` | — | composite_name, token | composite_name, token, direction, confidence, fired_at |
| `tokenintel_composite_catalog` | — | — | composite_name, description, win_rate, total_signals |
| `tokenintel_composite_performance` | composite_name | period | win_rate, avg_pnl_pct, total_signals |
| `tokenintel_composite_subscribe` | composites (array), webhook_url, webhook_secret | tokens, min_confidence | subscription_id, events subscribed |
| `tokenintel_analytics` | metric=performance_summary | token, days | win_rate, avg_pnl, outcome_distribution |

Oracle fires on: sell_ratio breach (> 0.65 threshold), sustained distribution (multi-hour), CEX inflow spike. Includes trailing stop system and auto-suppression on repeated false signals.

---

### Package: backtest-engine
Simulate strategies against 847+ real matchdays with price snapshots at -24h, -2h, kickoff, HT, FT, +1h, +24h.

| Tool | Required Params | Optional Params | Key Output Fields |
|---|---|---|---|
| `tokenintel_featured_backtest` | — | strategy_id | strategies[]: id, name, total_trades, win_rate, avg_return_pct, sharpe_ratio, profit_factor |
| `tokenintel_match_correlation` | token | result_filter, competition_filter, venue_filter, limit | avg_return_pct, win_count, sample_size, max_return, min_return |
| `tokenintel_historical_patterns` | token, scenario | timeframe (1h/4h/24h) | avg_return_pct, win_rate, sample_count, scenario |
| `tokenintel_analytics` | metric=token_performance | token, days | comparative performance across tokens |

Scenario options: general, matchday, post_win, post_loss, derby, whale_accumulation, whale_dump, signal_convergence.

`tokenintel_featured_backtest` returns 6 pre-computed strategies: buy_2h_sell_fulltime, buy_kickoff_sell_1h, fade_post_loss, ride_pre_match_24h, high_importance_only, whale_fade_distribution (live win rate at /evidence). No auth required. 1-hour cache.

---

### Package: order-router
Best-price execution across 13 exchanges. Quote, simulate, or execute.

| Tool | Required Params | Optional Params | Key Output Fields |
|---|---|---|---|
| `tokenintel_arbitrage_token` | symbol | — | exchange, price, bid, ask, spread_pct, last_updated |
| `tokenintel_arbitrage_scan` | — | min_spread_pct (default 0.0) | token, buy_exchange, sell_exchange, spread_pct, estimated_profit_usd |
| `tokenintel_arbitrage_dex_vs_cex` | — | symbol | symbol, dex_price, best_cex_price, spread_pct, direction |
| `tokenintel_execute_swap` | token_in, token_out, amount | slippage_pct (0.5-5.0, default 2.0), dry_run (default false) | tx_hash, amount_in, amount_out, price_impact_pct, gas_used |
| `tokenintel_risk_check` | token, side (long/short), size_usd | — | risk_flags (array), verdict (pass/warn/fail), concentration_pct, drawdown_headroom |

Hard limits: max $100/swap, 60s cooldown between swaps, slippage 0.5–5%. Use dry_run=true before live execution.

---

### Package: defi-tools
Governance staking, LP provision, DEX swaps on Chiliz Chain via Kayen DEX.

| Tool | Required Params | Optional Params | Key Output Fields |
|---|---|---|---|
| `tokenintel_governance_validators` | — | — | validator_address, moniker, commission_pct, apr_pct, voting_power |
| `tokenintel_governance_stake` | amount_chz | validator_address, dry_run | tx_hash, delegated_chz, validator, estimated_apy |
| `tokenintel_governance_unstake` | validator_address, amount_chz | — | tx_hash, unbonding_period_days |
| `tokenintel_governance_rewards` | — | — | pending_rewards_chz, claimed_chz, tx_hash |
| `tokenintel_governance_status` | — | — | delegations (array), total_staked_chz, pending_rewards_chz |
| `tokenintel_lp_pools` | — | limit (default 10) | pool_id, token, tvl_usd, fee_apr_pct, volume_24h |
| `tokenintel_lp_add` | token, amount_chz | slippage_pct (default 2.0), dry_run | tx_hash, lp_tokens_received, pool_share_pct |
| `tokenintel_lp_remove` | token | percentage (1-100, default 100), slippage_pct | tx_hash, chz_received, token_received |
| `tokenintel_lp_positions` | — | — | positions (array: token, lp_tokens, value_usd, pool_share_pct) |
| `tokenintel_create_wallet` | — | — | address, created_at (idempotent) |
| `tokenintel_wallet_balance` | — | tokens (array) | token, balance, value_usd |
| `tokenintel_swap_history` | — | limit (default 20), token | tx_hash, token_in, token_out, amount_in, amount_out, timestamp |

LP hard limits: max $500/tx, 60s cooldown. Staking unbonding: ~21 days on Chiliz Chain.

---

### Package: autonomy-engine *(beta)*
Deploy automated strategies. Autopilot evaluates every 5 min. Max 3 active per agent.

| Tool | Required Params | Optional Params | Key Output Fields |
|---|---|---|---|
| `tokenintel_strategy_templates` | — | risk_level (conservative/moderate/aggressive) | template_id, name, description, default_params, risk_level |
| `tokenintel_autopilot_start` | — | template_id (matchday_momentum/whale_fade/arb_closer/accumulation_buy/signal_follower), strategy_name, params | autopilot_id, status, next_eval_at |
| `tokenintel_autopilot_status` | — | autopilot_id | autopilot_id, status, trades_count, volume_usd, pnl_pct, last_eval_at |
| `tokenintel_autopilot_stop` | autopilot_id | — | status: stopped, final_pnl_pct |
| `tokenintel_matchday_campaigns` | — | status (all/upcoming/active/settled), token | campaign_id, token, match_date, allocation_chz, status |
| `tokenintel_matchday_opt_in` | — | campaign_id, token, allocation_chz (10-1000, default 200) | campaign_id, allocation_confirmed |
| `tokenintel_swarm_blueprint` | — | blueprint_id (fan_token_alpha/arb_squad/matchday_pack) | blueprint_id, agent_count, roles, expected_synergy |

Volume tiers: Bronze → Silver → Gold → Platinum. Higher tiers receive fee discounts on swaps.

---

### Package: agent-network *(beta)*
Copy-trade top agents, publish signals, agent marketplace.

| Tool | Required Params | Optional Params | Key Output Fields |
|---|---|---|---|
| `tokenintel_leaderboard` | — | sort_by (total_pnl_pct/win_rate/total_trades/signals_published), limit (default 20) | agent_id, name, total_pnl_pct, win_rate, total_trades |
| `tokenintel_discover_agents` | — | token, min_win_rate, min_trades (default 1), sort_by, limit (default 20) | agent_id, name, win_rate, specializations |
| `tokenintel_follow_agent` | target_agent_id | allocation_pct (default 10, max 50), max_position_pct (default 25, max 50), performance_fee_pct (default 10) | follow_id, status |
| `tokenintel_unfollow_agent` | target_agent_id | — | status: unfollowed |
| `tokenintel_copy_summary` | — | — | following (array), per_agent_pnl, total_copy_pnl, fees_paid |
| `tokenintel_my_earnings` | — | — | followers_count, total_fees_earned_chz, per_follower_breakdown |
| `tokenintel_my_followers` | — | — | followers (array: agent_id, allocation_pct, copy_pnl) |
| `tokenintel_marketplace_publish` | token, direction (long/short), target_pct, stop_loss_pct | reasoning (max 2000 chars), confidence (default 0.5), ttl_hours (default 24), visibility (public/private) | signal_id, published_at, expires_at |
| `tokenintel_marketplace_browse` | — | token, direction, status (active/target_hit/stopped_out/expired/cancelled), limit (default 20) | signal_id, agent_name, token, direction, confidence, pnl (if settled) |
| `tokenintel_update_profile` | — | strategy, specializations (array), risk_profile (conservative/moderate/aggressive), description | profile updated |

---

## Additional Utility Tools

| Tool | Purpose | Auth |
|---|---|---|
| `tokenintel_token_context` | All-in-one: whale, signals, matches, price, sentiment for one token | Yes |
| `tokenintel_trade_context` | Decision bundle: flows + signals + matches + regime + positions + consensus | Yes |
| `tokenintel_market_regime` | BTC trend, CHZ momentum, fear/greed, regime classification | Yes |
| `tokenintel_macro_context` | BTC dominance, CHZ price, funding rates, fear & greed, risk environment | Yes |
| `tokenintel_macro_filter` | Macro regime filter: risk-on / risk-off / neutral | No |
| `tokenintel_token_sensitivity` | CHZ/BTC correlation, beta, regime behavior per token | No |
| `tokenintel_correlation_matrix` | Cross-token price correlations | No |
| `tokenintel_dex_liquidity` | Kayen pool TVL, depth, slippage per token | No |
| `tokenintel_realtime_prices` | Freshest prices with age_seconds and source | Yes |
| `tokenintel_daily_brief` | Full daily executive briefing across all 58 tokens | Yes |
| `tokenintel_health_matrix` | Health grades A-F for all tokens | No |
| `tokenintel_anomaly_detector` | Volume spikes, social surges, price deviations | No |
| `tokenintel_newsroom` | AI-generated match/event coverage articles | Yes |
| `tokenintel_event_feed` | Unified event stream: signals, anomalies, matches, whale moves | Yes |
| `tokenintel_social_sentiment` | Twitter/Reddit/YouTube sentiment for a token | Yes |
| `tokenintel_social_trending` | Trending tokens by social activity | No |
| `tokenintel_attribute_price_move` | Attribute price move to macro/sports/whale/organic | Yes |
| `tokenintel_smart_flow` | Positioning consensus of top-performing agents | Yes |
| `tokenintel_paper_trade` | Submit paper trade ($10k virtual account) | Yes |
| `tokenintel_paper_balance` | Paper account balance and performance | Yes |
| `tokenintel_portfolio_summary` | Positions, win rate, PnL, max drawdown, concentration | Yes |
| `tokenintel_execution_review` | Slippage analysis and timing score on recent trades | Yes |
| `tokenintel_volume_rewards` | Volume tier status and fee discounts | Yes |
| `tokenintel_volume_leaderboard` | Top agents by swap volume | No |
| `tokenintel_spend_summary` | Cumulative on-chain spend across all operations | Yes |
| `tokenintel_historical_patterns` | Backtested scenarios with avg returns and win rates | Yes |
| `tokenintel_subscribe_alert` | Register webhook for signal/whale/trade events | Yes |
| `tokenintel_register_agent` | Register new agent, returns API key | No |

---

## Tokens Covered

58 fan tokens tracked across 13 CEX and Kayen DEX.

**Core Chiliz ecosystem:** CHZ, PEPPER

**European football:** PSG, BAR, JUV, ASR, ACM, ATM, INTER, GAL, PORTO, NAP, OG, BENFICA, SPURS, EFC, ASM, VCF, SEVILLA, RSO, LEV, BFC, UDI, SAM, ALA, AVL, AFC, GOZ, LEG, ITA

**South American:** MENGO, SANTOS, SAN, RACING, CAI, CHVS, ATLAS, TIGRES, FLU, BAHIA, SACI

**Other / esports:** NAVI, ARG, POR, CITY, CPFC, LUFC, DZG, APL, FOR, YBO, STV, IBFK, GFK, TRA

Use these exact symbols in all tool calls. Symbol lookup: `tokenintel_health_matrix` returns all tracked symbols with current grades.

---

## Rate Limits & Usage Notes

| Category | Limit | Applies To |
|---|---|---|
| read | 300 req / 60s | Market data, prices, portfolio, analytics |
| signal | 10 req / 60s | Signal queries and subscriptions |
| trade | 5 req / 60s | Swap execution, LP operations, staking |
| admin | 10 req / 60s | Profile updates, webhook management |

**Auth pattern:** All authenticated tools require `Authorization: Bearer ti_live_<key>` in HTTP header, or MCP handles it via OAuth on connection.

**Paper vs live mode:** `tokenintel_paper_trade` uses a $10,000 virtual account (auto-created). `tokenintel_execute_swap` executes real on-chain transactions. They are separate systems — paper trades do not affect on-chain state.

**Swap limits:** Max $100 per swap. 60s cooldown between swaps. Slippage 0.5–5% (default 2%). Always use dry_run=true first.

**LP limits:** Max $500 per LP add transaction. 60s cooldown.

**Autopilot:** Max 3 active strategies per agent. Evaluation cadence: every 5 min.

**TOOL_MODE:** Default is `full` (all 85 tools visible). Set env var `TOOL_MODE=dynamic` to collapse to 3 meta-tools (tokenintel_discover, tokenintel_describe, tokenintel_invoke) for context-window-limited models.

**idempotency:** `tokenintel_create_wallet` is idempotent — safe to call multiple times. Financial transactions (swaps, stakes) use idempotency keys internally to prevent double-spend.

**Staking unbonding:** Chiliz Chain unstaking has a ~21 day unbonding period. Plan accordingly.

**Copy trading fees:** Default performance fee is 10% of profits from copied signals. Negotiated at follow time.