---

name: zonein version: 2.0.0 description: | Track and analyze top traders with >75% win-rate on Hyperliquid and Polymarket via Zonein API. Create Hyperliquid & Polymarket trading agents with ease. Automated trading process with human-in-the-loop. homepage: https://zonein.xyz metadata: {"clawdbot":{"emoji":"🧠","requires":{"bins":["python3"],"env":["ZONEIN_API_KEY"]},"primaryEnv":"ZONEIN_API_KEY","files":["scripts/*"],"installer":{"instructions":"1. Go to https://app.zonein.xyz/pm\n2. Log in with your refcode\n3. Click 'Get API Key' button\n4. Copy the key and paste it below"}}}

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

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

Set API Key in OpenClaw

Option A — Gateway Dashboard (recommended):

1. Open your OpenClaw Gateway Dashboard
2. Go to /skills in the sidebar
3. Find "zonein" in Workspace Skills → click Enable
4. Enter your ZONEIN_API_KEY and save

Option B — Environment variable:

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

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 <id> (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 <id> --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

leaderboard — PM top traders by PnL

consensus — PM positions where smart bettors agree

trader — PM trader profile by wallet

Perpetuals (HyperLiquid)

perp-signals — Perp trading signals (HyperLiquid)

perp-traders — Perp smart money traders

perp-top — Perp top performers by PnL

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

Agent Management

agents — List your trading agents

No parameters.

agent-get — Get full agent config and state

agent-create — Create a new trading agent

agent-update — Update agent configuration

agent-deploy — Validate config and enable trading

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

agent-delete — Delete agent (soft delete)

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

agent-trades — Trade history

agent-vault — Vault (trading wallet) info

agent-balance — Live vault balance from Hyperliquid

Returns: account_value, withdrawable, has_positions, vault_address.

agent-positions — Open positions (live from Hyperliquid)

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

agent-deposit — Get deposit address for funding agent

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

agent-fund — Bridge USDC from Arbitrum to Hyperliquid

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)

agent-close — Close a position

agent-orders — Manual order history

agent-withdraw — Withdraw funds to your wallet

Agent must be disabled before withdrawing. Flow: Hyperliquid → Arbitrum → your wallet.

agent-backtest — Run backtest simulation

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:

{
  "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

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:

1. agent-templates — show available agent types
2. agent-categories — show smart money categories with stats
3. agent-assets — show available coins

Step 3: Create Agent Based on collected preferences, create the agent:

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:

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

1. agent-get <agent_id> — review full config
2. agent-deploy <agent_id> — validate and enable

Step 6: Fund the Agent The vault (deposit address) is auto-created with the agent. The create response includes it.

1. Show user the deposit address from the create response (or use agent-deposit <agent_id>)
2. Tell user: "Send USDC to this address on Arbitrum One."
3. agent-balance <agent_id> — check arbitrum_usdc field to confirm deposit arrived
4. Tell user: "Also send a small amount of ETH (~0.001 ETH) to the same vault address on Arbitrum One for gas fees."
5. agent-fund <agent_id> --confirm — bridge USDC from Arbitrum into Hyperliquid (requires ETH for gas)
6. agent-balance <agent_id> — confirm Hyperliquid account_value shows the funds

Step 7: Monitor

• agent-balance <agent_id> — check vault balance
• agent-positions <agent_id> — view open positions
• agent-stats <agent_id> — check performance (PnL, win rate)
• agent-trades <agent_id> — view trade history
• agent-disable <agent_id> — stop trading if needed

💰 Deposit & Withdraw Flow

Deposit:

1. agent-deposit <agent_id> — get vault address
2. User sends USDC to vault address on Arbitrum One
3. agent-balance <agent_id> — check arbitrum_usdc to verify deposit arrived
4. User also sends a small amount of ETH (~0.001 ETH) to the same vault address for gas fees
5. agent-fund <agent_id> --confirm — bridge USDC from Arbitrum → Hyperliquid (requires ETH for gas)
6. agent-balance <agent_id> — confirm account_value on Hyperliquid

Withdraw:

1. agent-disable <agent_id> — must disable agent first
2. agent-withdraw <agent_id> --to 0xYourWallet... — queue withdrawal
3. System processes: Hyperliquid → Arbitrum → your wallet

📊 Position Management via Chat

When user wants to check positions or trade manually:

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

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

Close a position: agent-close <agent_id> --coin BTC --confirm

Check order status: agent-orders <agent_id>

Market Overview

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

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

Trading Signals

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

Track a Wallet

1. trader <wallet> — Polymarket profile
2. perp-trader <address> — HyperLiquid profile
3. 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

How to customize based on user preferences

Adjust +/-5 from defaults:

Validation rules

1. All values >= 55 (hard minimum)
2. OTHERS >= max(BTC, ETH, SOL) altcoins are more volatile, need stronger signals
3. Typical ordering: BTC <= ETH <= SOL <= OTHERS for buy thresholds
4. 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.

Override command

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

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

Perp Signal

📊 $[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