Skip to content

Getting Started with Katbot Trading

This guide will walk you through installing and setting up the Katbot Trading Skill in OpenClaw to start getting AI-powered trade recommendations and executing trades on Hyperliquid.

What is Katbot Trading?

Katbot Trading is an OpenClaw skill that gives your AI agent the ability to:

  • 📊 Analyze markets — Check BTC Momentum Index (BMI) and token momentum
  • 🎯 Select tokens — Pick the best trading candidates based on market direction
  • 🤖 Get recommendations — Request AI-powered trade setups (entry, TP, SL, leverage)
  • ⚡ Execute trades — Live trading on Hyperliquid with your approval
  • 📈 Track positions — Monitor open trades, profit/loss, and portfolio health
  • 💬 Chat analysis — Ask your agent anything about your portfolio

Prerequisites

Before you start, make sure you have:

Requirement Get it here
OpenClaw docs.openclaw.ai
MetaMask wallet with ETH on Arbitrum metamask.io
Katbot account katbot.ai (Early Access - whitelisted)
Hyperliquid account app.hyperliquid.xyz

Installation (5 minutes)

Step 1: Install the Skill in OpenClaw

  1. In OpenClaw, go to Skills → Add Skill
  2. Search for "katbot-trading" by claytantor
  3. Click Install (or direct link)

The skill installs to ~/.openclaw/workspace/katbot-trading/.

Step 2: Install Dependencies

Run the environment checker to install Python dependencies:

bash ~/.openclaw/workspace/katbot-trading/tools/ensure_env.sh ~/.openclaw/workspace/katbot-trading

This happens automatically, but you can run it manually after upgrading.

First-Time Onboarding (10 minutes)

Step 1: Authenticate with Your Wallet

Run the onboarding wizard:

python3 ~/.openclaw/workspace/katbot-trading/tools/katbot_onboard.py

The wizard will:

  1. Ask for your MetaMask private key (hidden input, never stored)
  2. Your wallet is your identity — Katbot uses Sign-In With Ethereum (SIWE)
  3. This key is used only to sign the login message, then discarded

  4. ⚠️ Never export this to your shell or commit to git

  5. Authenticate with api.katbot.ai

  6. Signs your wallet locally and sends only the signature

  7. Saves access + refresh tokens to ~/.openclaw/workspace/katbot-identity/

  8. Create or select a Hyperliquid portfolio

  9. If this is your first time: creates a new portfolio
  10. If you have existing portfolios: lets you pick one
  11. Katbot generates a unique agent wallet for trading

  12. After creating your portfolio, assign your Katbot Agent to it: Portfolio Settings → Assigned Agents → select your agent → "Assign Primary"

  13. Save your credentials securely

  14. ~/.openclaw/workspace/katbot-identity/katbot_config.json — config (readable)
  15. ~/.openclaw/workspace/katbot-identity/katbot_token.json — session token (600 mode)
  16. ~/.openclaw/workspace/katbot-identity/katbot_secrets.json — agent key (600 mode)

Step 1b: Create Your Katbot Agent

Before creating a portfolio, you need an agent — your AI trading assistant.

  1. On the Dashboard, scroll to the "Agents" section
  2. Click "Create Agent"
  3. Enter a name (lowercase letters, numbers, hyphens — e.g., my-trader)
  4. Click Create — your agent appears with an auto-generated avatar
  5. Optionally click the agent card to customize its system prompt before assigning it to a portfolio

Create Agent

Step 2: Authorize the Agent on Hyperliquid

Katbot creates a separate wallet (the "agent wallet") to execute trades. You must approve it on Hyperliquid:

  1. Copy the agent wallet address from the onboarding output
  2. Go to app.hyperliquid.xyz → Settings → API
  3. Add a new API Wallet with the agent address
  4. Enable Trading permission
  5. Set expiration to 180 days
  6. Confirm the MetaMask transaction

See Hyperliquid Integration Guide for screenshots.

✅ You're ready! Your agent now has permission to trade on your behalf.

Daily Usage

Start OpenClaw and Ask Your Agent

You: "What's the market looking like today?"

Agent: I'll analyze the BTC Momentum Index and check your top performing tokens...
[Fetches BMI, selects tokens, checks portfolio]

You: "Should I trade anything?"

Agent: Based on current market conditions, I'm recommending a LONG on SOL...
[Shows recommendation with entry, TP, SL, leverage]

You: "Execute it"

Agent: ⚠️ This will send $2,000 to buy SOL at $195.50 with 3x leverage.
Stop loss at $180.25, take profit at $210.75. Confirm? (yes/no)

You: "yes"

Agent: ✅ Trade executed! Order ID: 0x12ab3c...

Common Commands to Use

Talk naturally to your agent and try phrases like:

  • Portfolio questions:
  • "What's my current P&L?"
  • "Show me open positions"

  • "How much cash do I have?"

  • Market analysis:

  • "Check the momentum index"
  • "What tokens are trending today?"

  • "Is the market bullish or bearish?"

  • Trading:

  • "Give me a recommendation"
  • "Execute the recommendation"

  • "Close my ETH position"

  • General help:

  • "What can you do?"
  • "Explain my portfolio"

Security (Important!)

Private Keys

The skill handles credentials securely:

Key Storage Used for When
MetaMask private key Your input only (not stored) SIWE login First-time setup only
Agent private key katbot_secrets.json (mode 600) Hyperliquid trades Always (automatic)
Session tokens katbot_token.json (mode 600) API authentication Always (automatic refresh)

Golden rules:

✅ DO: - Let ensure_env.sh manage dependencies - Store KATBOT_IDENTITY_DIR safely (it's outside your project) - Let katbot_client.py handle token refresh automatically - Provide your MetaMask key only when the onboarding wizard asks

❌ DON'T: - Store private keys in .env files - Export WALLET_PRIVATE_KEY to your shell profile - Commit the identity directory to git - Manually manage tokens - Log or display token values

Credential Transmission

⚠️ Understand what gets sent remotely:

When you execute a trade, the agent private key is transmitted to api.katbot.ai in: - The X-Agent-Private-Key header - The JSON request body

This is required so Katbot can sign and submit trades to Hyperliquid on your behalf.

If you don't trust api.katbot.ai with your agent private key, do not use this skill.

The good news: the agent key is limited to the specific Hyperliquid agent wallet you created. It can't access your main MetaMask wallet or any other assets.

Troubleshooting

"Module not found" error

Solution: Reinstall dependencies

bash ~/.openclaw/workspace/katbot-trading/tools/ensure_env.sh ~/.openclaw/workspace/katbot-trading

"401 Unauthorized" when trading

Solution: Session expired, need to re-authenticate

python3 ~/.openclaw/workspace/katbot-trading/tools/katbot_onboard.py

The wizard will refresh your tokens.

"Trade won't execute"

Common causes:

  • Testnet orderbook is thin — try a major pair (BTC, ETH)
  • Agent not authorized — verify agent wallet in Hyperliquid Settings → API
  • Insufficient balance — check portfolio state for available cash
  • Leverage constraints — Hyperliquid has max leverage + maintenance ratio rules

"How do I get a Katbot account?"

Katbot is currently in Early Access (whitelisted users). By joining, you'll help shape the product while gaining an edge before launch. Check: - katbot.ai for access form - Discord community for updates

What Happens Behind the Scenes

Authentication Flow

  1. First time: You provide MetaMask key → SIWE login → gets access token + refresh token
  2. Tokens saved: Stored in ~/.openclaw/workspace/katbot-identity/
  3. Auto-refresh: Every API call checks if token is expiring soon and refreshes if needed
  4. Re-authentication: Only needed if refresh token expires (7 days inactive)

Recommendation Workflow

When you ask for a trade recommendation:

  1. Check BMI — Bitcoin Momentum Index via CoinGecko
  2. Select tokens — Pick best/worst performers based on market direction
  3. Analyze — Katbot's AI analyzes price history, volatility, technicals
  4. Generate — Creates entry, stop-loss, take-profit, leverage
  5. Save — Recommendation stored in database for tracking
  6. Present — Agent shows you the trade with full details
  7. Execute — Only after your explicit approval

Trade Execution

When you approve a trade:

  1. Send agent key → API uses it to sign transaction
  2. Submit to chain → Hyperliquid processes the order
  3. Confirm → You get order ID and position details
  4. Monitor → Agent tracks position, P&L, triggers TP/SL

Next Steps

Learn More

Join the Community

Try It Out

  1. Set up a testnet portfolio first (risk-free practice)
  2. Get a few recommendations without executing
  3. Review the recommendations carefully
  4. Execute small trades to build confidence
  5. Scale up once you're comfortable

FAQ

Q: Can I use this on mainnet?
A: Yes, but start on testnet. Real money = real consequences.

Q: What happens if the agent crashes during a trade?
A: The trade is already submitted to Hyperliquid and will execute regardless. The agent will sync state on restart.

Q: Can I trade multiple portfolios?
A: Yes. You can create multiple Hyperliquid portfolios in Katbot and switch between them.

Q: Is my MetaMask wallet at risk?
A: No. Only the agent wallet (which has its own separate wallet address) can execute trades. Your MetaMask key is used once to log in, then never needed again (unless session fully expires after 7 days).

Q: How much leverage can I use?
A: Up to 20x on Hyperliquid, but Katbot enforces Kelly Criterion sizing — never more than 2% portfolio risk per trade.

Q: Can I copy-trade other users?
A: Not yet, but it's in the roadmap.

Getting Help