✓ Verified 💻 Development ✓ Enhanced Data

Zonein

Track and analyze top traders with >75% win-rate on Hyperliquid and Polymarket via Zonein API.

Rating
4.2 (299 reviews)
Downloads
6,079 downloads
Version
1.0.0

Overview

Track and analyze top traders with >75% win-rate on Hyperliquid and Polymarket via Zonein API.

Complete Documentation

View Source →

Zonein — Smart Money Intelligence

Fetch live trading intelligence from Polymarket and HyperLiquid smart money wallets using the bundled script.

Setup (credentials)

Get Your API Key

  • Go to https://app.zonein.xyz/pm
  • Log in with your account (you need a referral code to register)
  • Click the "Get API Key" button
  • Copy your API key (starts with zn_)

Set API Key in OpenClaw

Option A — Gateway Dashboard (recommended):

  • Open your OpenClaw Gateway Dashboard
  • Go to /skills in the sidebar
  • Find "zonein" in Workspace Skills → click Enable
  • Enter your ZONEIN_API_KEY and save
Option B — Environment variable:
bash
export ZONEIN_API_KEY="zn_your_key_here"

Option C — The script also reads from ~/.openclaw/openclaw.json automatically (skills.entries.zonein.apiKey).

Quick Reference

User asks...Command
"What's happening in the market?"signals --limit 5 + perp-signals --limit 5
"Show me PM signals for politics"signals --categories POLITICS --limit 10
"What are whales doing on crypto?"perp-signals --limit 10
"Top Polymarket traders this week"leaderboard --period WEEK --limit 10
"Which coins are smart money long?"perp-coins
"Best perp traders this month"perp-top --period month --limit 10
"Track wallet 0x..."trader 0x... or perp-trader 0x...
"Where is smart money flowing?"signals --limit 10 + perp-signals --limit 10 + perp-coins
"Create a trading agent"Follow Agent Creation Flow (Step 1–6)
"List my agents"agents
"How is my agent doing?"agent-stats + agent-trades
"Stop my agent"agent-disable
"What agent types are available?"agent-templates
"Check my agent's balance"agent-balance
"What positions does my agent have?"agent-positions
"How do I fund my agent?"agent-deposit then send USDC, then agent-fund to bridge to Hyperliquid
"Open a BTC long for $100"agent-open --coin BTC --direction LONG --size 100
"Close my ETH position"agent-close --coin ETH
"Withdraw my funds"agent-disable then agent-withdraw --to 0x...
"Backtest my agent on BTC"agent-backtest --symbol BTC --days 30
"Show past backtests"agent-backtests

Commands

Presentation Rules:

  • Present results in natural, readable language. Format numbers, tables, and summaries nicely.
  • If the user asks to see raw JSON or the actual command, you may show it.
Read-only commands (safe to run without asking): signals, leaderboard, consensus, trader, perp-signals, perp-traders, perp-top, perp-categories, perp-coins, perp-trader, agents, agent-get, agent-stats, agent-trades, agent-vault, agent-templates, agent-assets, agent-categories, agent-balance, agent-positions, agent-deposit, agent-orders, agent-backtests, status

State-changing commands (ask user before running — no --confirm needed): agent-create, agent-update, agent-disable, agent-pause, agent-delete

Financial commands (require --confirm flag — script refuses without it): agent-fund, agent-open, agent-close, agent-withdraw, agent-enable, agent-deploy, agent-backtest

You MUST ask the user for approval before running any state-changing or financial command. For financial commands, only add --confirm after the user explicitly says yes.

Example — user deposits USDC and asks to check balance:

  • You run: agent-balance (read-only, safe — no --confirm needed)
  • You see: arbitrum_usdc: 200, needs_funding: true
  • You tell the user: "Your vault has 200 USDC on Arbitrum but it hasn't been bridged to Hyperliquid yet. Would you like me to bridge it now so your agent can start trading?"
  • User says yes → you run: agent-fund --confirm
  • Without --confirm, the script will refuse to execute and return an error
All commands use the bundled Python script. Always use these commands — never write inline API calls.

Prefix: python3 skills/zonein/scripts/zonein.py

Polymarket (PM)

signals — PM smart money trading signals

ParamTypeDefaultValuesDescription
--limitint201–100Max signals to return
--categoriesstrallPOLITICS,CRYPTO,SPORTS,CULTURE,ECONOMICS,TECH,FINANCEComma-separated filter
--periodstrWEEKDAY, WEEK, MONTH, ALLLookback period
--min-walletsint3≥1Minimum smart wallets for consensus

leaderboard — PM top traders by PnL

ParamTypeDefaultValuesDescription
--periodstrWEEKDAY, WEEK, MONTH, ALLRanking period
--categorystrOVERALLOVERALL, POLITICS, SPORTS, CRYPTO, CULTURE, ECONOMICS, TECH, FINANCECategory filter
--limitint201–500Max traders to return

consensus — PM positions where smart bettors agree

ParamTypeDefaultDescription
--min-bettorsint3Minimum bettors agreeing on a position

trader — PM trader profile by wallet

ParamTypeRequiredDescription
walletstryesPolymarket wallet address (0x...)
Perpetuals (HyperLiquid)

perp-signals — Perp trading signals (HyperLiquid)

ParamTypeDefaultDescription
--limitint20Max signals to return
--min-walletsint3Minimum wallets for consensus
--min-scorefloat0Minimum trader credibility score (0–100)

perp-traders — Perp smart money traders

ParamTypeDefaultDescription
--limitint20Max traders to return
--min-scorefloat0Minimum trader score (0–100)
--categoriesstrallComma-separated: swing_trading, large_cap_trader, high_win_rate, scalper, etc.

perp-top — Perp top performers by PnL

ParamTypeDefaultValuesDescription
--limitint101–100Max traders
--periodstrmonthday, week, monthPnL ranking period

perp-coins — Coin distribution (long vs short sentiment)

No parameters. Returns all coins with smart money positions.

perp-categories — Perp trader category list

No parameters.

perp-trader — Perp trader details by address

ParamTypeRequiredDescription
addressstryesHyperLiquid wallet address (0x...)
Agent Management

agents — List your trading agents

No parameters.

agent-get — Get full agent config and state

ParamTypeRequiredDescription
agent_idstryesAgent ID (e.g. agent_abc12345)

agent-create — Create a new trading agent

ParamTypeDefaultDescription
--namestrrequiredAgent display name
--typestrcompositecomposite, momentum_hunter, stable_grower, precision_master, whale_follower, scalping_pro, swing_trader
--assetsstrBTC,ETHComma-separated: BTC,ETH,SOL,HYPE
--categoriesstrauto from typeComma-separated smart money categories
--leverageint5Max leverage (1–20)
--descriptionstrautoAgent description
--risk-per-tradefloat1Risk per trade %
--max-daily-lossfloat3Max daily loss %
--risk-rewardstr1:2Risk:reward ratio
--max-trades-per-dayint3Max trades per day
--min-confidencefloat0.8Min LLM confidence (0–1)
--min-consensusfloat0.7Min smart money consensus (0–1)

agent-update — Update agent configuration

ParamTypeDescription
agent_idstrAgent ID (positional)
--namestrNew name
--assetsstrComma-separated assets
--categoriesstrComma-separated categories
--leverageintMax leverage
--methodologystrTrading methodology text
--entry-strategystrEntry strategy text
--exit-frameworkstrExit framework text
--strength-thresholdsjsonEntry/exit thresholds per asset (see Strength Thresholds Guide)
--timeframe-weightsjsonTimeframe weight distribution

agent-deploy — Validate config and enable trading

ParamTypeRequiredDescription
agent_idstryesAgent to deploy

agent-enable / agent-disable / agent-pause — Lifecycle control

ParamTypeRequiredDescription
agent_idstryesAgent ID

agent-delete — Delete agent (soft delete)

ParamTypeRequiredDescription
agent_idstryesAgent ID

agent-stats — Performance statistics (PnL, win rate)

ParamTypeRequiredDescription
agent_idstryesAgent ID

agent-trades — Trade history

ParamTypeDefaultDescription
agent_idstrrequiredAgent ID
--limitint50Max trades to return

agent-vault — Vault (trading wallet) info

ParamTypeRequiredDescription
agent_idstryesAgent ID

agent-balance — Live vault balance from Hyperliquid

ParamTypeRequiredDescription
agent_idstryesAgent ID
Returns: account_value, withdrawable, has_positions, vault_address.

agent-positions — Open positions (live from Hyperliquid)

ParamTypeRequiredDescription
agent_idstryesAgent ID
Returns each position: coin, side (LONG/SHORT), size, entry_price, unrealized_pnl, leverage, notional.

agent-deposit — Get deposit address for funding agent

ParamTypeRequiredDescription
agent_idstryesAgent ID
Returns: deposit_address (send USDC on Arbitrum One to this address).

agent-fund — Bridge USDC from Arbitrum to Hyperliquid

ParamTypeRequiredDescription
agent_idstryesAgent ID
After sending USDC to the vault address on Arbitrum, call this to auto-bridge funds into Hyperliquid. Important: The bridge transaction requires a small amount of ETH on Arbitrum for gas fees (typically ~0.0001–0.0005 ETH). Ask the user to send a small amount of ETH (e.g. 0.001 ETH) to the same vault address on Arbitrum One before running this command. Returns tx_hash and amount bridged.

agent-open — Open a position (manual order via chat)

ParamTypeRequiredDescription
agent_idstryesAgent ID
--coinstryesBTC, ETH, SOL, HYPE
--directionstrno (default LONG)LONG or SHORT
--sizefloatyesPosition size in USD
--leverageintnoLeverage (1–20)

agent-close — Close a position

ParamTypeRequiredDescription
agent_idstryesAgent ID
--coinstryesCoin to close (BTC, ETH, SOL, HYPE)

agent-orders — Manual order history

ParamTypeDefaultDescription
agent_idstrrequiredAgent ID
--limitint20Max orders to return

agent-withdraw — Withdraw funds to your wallet

ParamTypeRequiredDescription
agent_idstryesAgent ID
--tostryesDestination 0x... wallet address on Arbitrum
Agent must be disabled before withdrawing. Flow: Hyperliquid → Arbitrum → your wallet.

agent-backtest — Run backtest simulation

ParamTypeDefaultDescription
agent_idstrrequiredAgent ID
--symbolstrBTCCoin to backtest: BTC, ETH, SOL, HYPE
--daysint30Backtest period (7–90 days)
--initial-balancefloat10000Starting balance in USD
Runs a historical backtest using the agent's config (thresholds, leverage, risk profile) against cached smart money signals and real OHLC prices. Returns performance summary + a dashboard link with interactive charts (equity curve, candlestick with trade markers, daily PnL, trade table).

Requires --confirm (this is a compute-intensive action).

Example output:

json
{
  "backtest_id": "bt_agent123_BTC_20260218_...",
  "dashboard": "https://mcp.zonein.xyz/api/v1/backtest/bt_.../dashboard",
  "pnl": 523.40,
  "total_trades": 12,
  "stats": {"win_rate": 66.67, "sharpe_ratio": 1.42, "max_drawdown": 3.2}
}

agent-backtests — List past backtests

ParamTypeDefaultDescription
agent_idstrrequiredAgent ID
--limitint10Max results
Returns list of previous backtests with summary metrics and dashboard links.

agent-templates — Agent types & default config

No parameters. Returns available agent types with their category presets and default risk/trading config.

agent-assets — Available trading assets

No parameters. Returns: BTC, ETH, SOL, HYPE.

agent-categories — Smart money categories with live stats

No parameters. Returns all categories with description and live trader counts.

Utility

status — Check API key status

No parameters.

Operational Flows

🤖 Agent Creation Flow

When user wants to create a trading agent, follow this conversational flow:

Step 1: Collect Preferences Ask the user about their trading goals:

  • What coins do you want to trade? (BTC, ETH, SOL, HYPE)
  • What's your risk tolerance? (conservative, moderate, aggressive)
  • What trading style? (scalping, swing trading, momentum, balanced)
  • How much leverage? (1x–20x)
  • Max daily loss tolerance? (1%–10%)
Step 2: Show Available Options Run these commands to give user context:
  • agent-templates — show available agent types
  • agent-categories — show smart money categories with stats
  • agent-assets — show available coins
Step 3: Create Agent Based on collected preferences, create the agent:
text
agent-create --name "BTC Swing Trader" --type swing_trader --assets BTC,ETH --leverage 5 --risk-per-trade 1 --max-daily-loss 3 --risk-reward 1:2 --max-trades-per-day 3 --min-confidence 0.8 --min-consensus 0.7

Step 4: Configure Strategy Update the agent with trading strategy prompts:

text
agent-update <agent_id> --methodology "Follow smart money signals..." --entry-strategy "Enter on SM consensus >70%..." --exit-framework "Take profit at +10%, stop loss at -5%..."

Step 5: Review & Deploy

  • agent-get — review full config
  • agent-deploy — validate and enable
Step 6: Fund the Agent The vault (deposit address) is auto-created with the agent. The create response includes it.
  • Show user the deposit address from the create response (or use agent-deposit )
  • Tell user: "Send USDC to this address on Arbitrum One."
  • agent-balance — check arbitrum_usdc field to confirm deposit arrived
  • Tell user: "Also send a small amount of ETH (~0.001 ETH) to the same vault address on Arbitrum One for gas fees."
  • agent-fund --confirm — bridge USDC from Arbitrum into Hyperliquid (requires ETH for gas)
  • agent-balance — confirm Hyperliquid account_value shows the funds
Step 7: Monitor
  • agent-balance — check vault balance
  • agent-positions — view open positions
  • agent-stats — check performance (PnL, win rate)
  • agent-trades — view trade history
  • agent-disable — stop trading if needed

💰 Deposit & Withdraw Flow

Deposit:

  • agent-deposit — get vault address
  • User sends USDC to vault address on Arbitrum One
  • agent-balance — check arbitrum_usdc to verify deposit arrived
  • User also sends a small amount of ETH (~0.001 ETH) to the same vault address for gas fees
  • agent-fund --confirm — bridge USDC from Arbitrum → Hyperliquid (requires ETH for gas)
  • agent-balance — confirm account_value on Hyperliquid
Withdraw:
  • agent-disable — must disable agent first
  • agent-withdraw --to 0xYourWallet... — queue withdrawal
  • System processes: Hyperliquid → Arbitrum → your wallet

📊 Position Management via Chat

When user wants to check positions or trade manually:

Check positions: agent-positions — Present each position: "BTC LONG — $500 at $95,432 entry — PnL: +$23.45 — 5x leverage"

Open a position: agent-open --coin BTC --direction LONG --size 100 --leverage 5 --confirm

Close a position: agent-close --coin BTC --confirm

Check order status: agent-orders

Market Overview

When user asks about market conditions, run these in sequence:

  • signals --limit 5 — top PM signals
  • perp-signals --limit 5 — top perp signals
  • perp-coins — coin long/short sentiment
  • Summarize: which markets have strong agreement, which coins whales are bullish/bearish on

Trading Signals

  • Ask: prediction markets, perp, or both?
  • Run the relevant command(s)
  • Present top signals sorted by consensus strength
  • Explain each signal, e.g.: "5 top-100 traders all say YES on 'Will BTC hit $100k?' — current price 42c"

Track a Wallet

  • trader — Polymarket profile
  • perp-trader
    — HyperLiquid profile
  • Present: performance, open positions, win rate

Strength Thresholds Guide

strength_thresholds and timeframe_weights are auto-generated from agent_type when creating an agent. Override with agent-update if user wants custom values.

What they control

  • min_strength_buy: How strong smart money signal must be to OPEN a position (higher = pickier, fewer trades)
  • min_strength_sell: How strong opposite-direction signal must be to CLOSE a position (lower = exit fast, higher = ride trends)

Auto-generated defaults by agent type

Agent TypeStyleBTC buy/sellETH buy/sellSOL buy/sellOTHERS buy/sellTimeframes 24h/4h/1h
scalping_pro, momentum_hunterScalp65/6570/6578/6578/650.2/0.4/0.4
All others (swing_trader, stable_grower, composite, etc.)Swing75/7078/7082/7082/700.5/0.35/0.15

How to customize based on user preferences

Adjust +/-5 from defaults:

User saysWhat to adjustExample
"I want more trades" / aggressiveLower min_strength_buy (-5 to -10)BTC buy: 78 -> 70
"Only high-quality setups" / conservativeRaise min_strength_buy (+5)BTC buy: 78 -> 83
"Cut losses quickly" / protect capitalLower min_strength_sell (-5)sell: 72 -> 65
"Let winners ride" / trend followingRaise min_strength_sell (+5)sell: 72 -> 77

Validation rules

  • All values >= 55 (hard minimum)
  • OTHERS >= max(BTC, ETH, SOL) altcoins are more volatile, need stronger signals
  • Typical ordering: BTC <= ETH <= SOL <= OTHERS for buy thresholds
  • Set OTHERS = max(BTC, ETH, SOL) + 0-5 buffer
Correct example:
  • BTC buy 70, ETH buy 75, SOL buy 78, OTHERS buy 78 (>= max)
Wrong example:
  • BTC buy 70, OTHERS buy 68 INVALID! OTHERS lower than BTC!

Timeframe weights

Must sum to 1.0. Three timeframes: 24h, 4h, 1h.

User preference24h4h1hWhy
Quick trades / scalping0.20.40.4Focus on short-term signals
Swing / multi-day0.50.350.15Focus on long-term trend
Trend following0.40.40.2Balance trend + momentum
"I follow the daily trend"0.60.30.1Heavy 24h weight

Override command

text
agent-update <agent_id> --strength-thresholds '{"BTC": {"min_strength_buy": 70, "min_strength_sell": 65}, "ETH": {"min_strength_buy": 75, "min_strength_sell": 65}, "SOL": {"min_strength_buy": 80, "min_strength_sell": 65}, "OTHERS": {"min_strength_buy": 80, "min_strength_sell": 65}}' --timeframe-weights '{"24h": 0.5, "4h": 0.35, "1h": 0.15}'

Output Fields

PM Signal

  • direction — YES or NO
  • consensus — 0 to 1 (1 = everyone agrees)
  • total_wallets — how many smart traders hold this
  • best_rank — best leaderboard position
  • cur_yes_price / cur_no_price — current prices

Perp Signal

  • coin — token (BTC, ETH, SOL, HYPE...)
  • direction — LONG or SHORT
  • consensus — agreement ratio (0-1)
  • long_wallets / short_wallets — traders per side
  • long_value / short_value — USD per side
  • best_trader_score — credibility score

Periods & Categories

  • PM Periods: DAY, WEEK, MONTH, ALL
  • PM Categories: OVERALL, POLITICS, SPORTS, CRYPTO, CULTURE, ECONOMICS, TECH, FINANCE
  • Perp Periods: day, week, month

How to Present Results

PM Signal

text
🔮 [market_title]
Smart money says: [YES/NO] | Agreement: [X]%
[N] top traders holding | Best ranked: #[rank]
Current price: YES [price] / NO [price]

Perp Signal

text
📊 $[COIN]
Smart money says: [LONG/SHORT] | Agreement: [X]%
[N] whale traders | Top score: [score]
Long: $[X] | Short: $[X]

Security & Privacy

Disclaimer:

  • Signals show what smart money is doing — not guaranteed outcomes
  • Past performance does not predict future results
  • Never invest more than you can afford to lose
  • Always use the bundled script. Never construct raw API calls with curl or inline Python.
External endpoint: https://mcp.zonein.xyz/api/v1/* — API key (X-API-Key header) + query parameters.

Data & access:

  • Only your API key leaves the machine (sent as X-API-Key header)
  • No personal data is sent beyond the key and query parameters
  • Local files read: ~/.openclaw/openclaw.json (API key fallback only). No other local files are accessed.
  • Local files written: none
  • The scripts connect only to https://mcp.zonein.xyz/api/v1 — no other endpoints, no package installs, no filesystem writes
Confirmation policy: Financial commands (agent-fund, agent-open, agent-close, agent-withdraw, agent-deploy, agent-enable, agent-backtest) are programmatically gated — the script refuses to execute unless --confirm is explicitly passed. The agent must first ask the user for approval, then include --confirm only after the user agrees. This prevents prompt injection from bypassing confirmation.

By using this skill, your API key and query parameters are sent to https://mcp.zonein.xyz. Only install if you trust Zonein.

Links

  • Dashboard: https://app.zonein.xyz/pm/
  • Perp Dashboard: https://app.zonein.xyz/perp/
  • API Docs: https://mcp.zonein.xyz/docs

Installation

Terminal bash

openclaw install zonein
    
Copied!

💻Code Examples

Example output:

example-output.json
{
  "backtest_id": "bt_agent123_BTC_20260218_...",
  "dashboard": "https://mcp.zonein.xyz/api/v1/backtest/bt_.../dashboard",
  "pnl": 523.40,
  "total_trades": 12,
  "stats": {"win_rate": 66.67, "sharpe_ratio": 1.42, "max_drawdown": 3.2}
}

agent-update <agent_id> --strength-thresholds '{"BTC": {"min_strength_buy": 70, "min_strength_sell": 65}, "ETH": {"min_strength_buy": 75, "min_strength_sell": 65}, "SOL": {"min_strength_buy": 80, "min_strength_sell": 65}, "OTHERS": {"min_strength_buy": 80, "min_strength_sell": 65}}' --timeframe-weights '{"24h": 0.5, "4h": 0.35, "1h": 0.15}'

agent-update-agentid---strength-thresholds-btc-minstrengthbuy-70-minstrengthsell-65-eth-minstrengthbuy-75-minstrengthsell-65-sol-minstrengthbuy-80-minstrengthsell-65-others-minstrengthbuy-80-minstrengthsell-65---timeframe-weights-24h-05-4h-035-1h-015.txt
## Output Fields

### PM Signal
- `direction` — YES or NO
- `consensus` — 0 to 1 (1 = everyone agrees)
- `total_wallets` — how many smart traders hold this
- `best_rank` — best leaderboard position
- `cur_yes_price` / `cur_no_price` — current prices

### Perp Signal
- `coin` — token (BTC, ETH, SOL, HYPE...)
- `direction` — LONG or SHORT
- `consensus` — agreement ratio (0-1)
- `long_wallets` / `short_wallets` — traders per side
- `long_value` / `short_value` — USD per side
- `best_trader_score` — credibility score

### Periods & Categories
- **PM Periods:** DAY, WEEK, MONTH, ALL
- **PM Categories:** OVERALL, POLITICS, SPORTS, CRYPTO, CULTURE, ECONOMICS, TECH, FINANCE
- **Perp Periods:** day, week, month

## How to Present Results

### PM Signal
example.txt
🔮 [market_title]
Smart money says: [YES/NO] | Agreement: [X]%
[N] top traders holding | Best ranked: #[rank]
Current price: YES [price] / NO [price]
example.txt
📊 $[COIN]
Smart money says: [LONG/SHORT] | Agreement: [X]%
[N] whale traders | Top score: [score]
Long: $[X] | Short: $[X]

Tags

#productivity_and-tasks #api

Quick Info

Category Development
Model Claude 3.5
Complexity One-Click
Author phutt-bwai
Last Updated 3/10/2026
🚀
Optimized for
Claude 3.5
🧠

Ready to Install?

Get started with this skill in seconds

openclaw install zonein