Portfolio / API Ensemble

Portfolio / API ensemble strategies let you run custom logic on your own server — Python, Node, a VPS, or any stack that can send HTTP requests — and route signals into BB TraderX for execution on Hyperliquid. Unlike TradingView webhook bots, your backend controls timing, sizing, and when each symbol trades.

Each portfolio bot has a dedicated sandbox where you generate API keys, copy integration snippets, and watch test signals arrive in a live feed before switching to production.

Start from My Strategies (/signal-bots) — the Hyperliquid bot page where your signal and portfolio strategies are listed.

1. 1

   Open Create Strategy

   Click Create Strategy on My Strategies. Sign in first if prompted.

2. 2

   Choose Portfolio / API ensemble

   On the strategy type step, select Portfolio / API ensemble instead of a single-symbol TradingView webhook bot. This type skips Pine Script alerts — your code sends JSON orders directly.

3. 3

   Select wallet and symbol universe

   Pick the wallet that will execute trades — Demo Account for paper trading, or a BBTraderX / Hyperliquid wallet for live funds — then choose every coin your backend is allowed to trade. Only symbols in this universe are accepted by the API.

4. 4

   Create and open Sandbox

   After you create the strategy, BB TraderX redirects you to /signal-bots/{id}/sandbox — the integration workspace for that bot.

The sandbox page is split into two panels: configuration on the left and a live signal feed on the right.

• Symbol universe — the exact Hyperliquid tickers whitelisted for this bot. Orders for any other asset return HTTP 422.
• API keys — sandbox (bbtx_test_…) and live (bbtx_live_…) keys are created automatically. Copy each key once when shown; regenerate if lost.
• Copy-ready script — Python, JavaScript, PowerShell, Rust, Go, or cURL snippets with your universe, endpoint URL, and sizing mode baked in.
• AI integration prompt — a long-form prompt you can paste into Claude, ChatGPT, or Codex alongside the script to wire your backend faster.
• Live feed — real-time sandbox runs and events as your server posts test orders.

1. Open your bot's Sandbox page from My Strategies → select the bot → Sandbox (or go directly after creation).
2. Sandbox and live keys are minted on first visit. Reveal and copy each secret — it may not be shown again.
3. Store keys in environment variables on your server. Never commit them to git.
4. Use Regenerate in the panel if a key is compromised.
5. Optional: generate a bbtx_read_* monitor key to poll positions/trades/PnL from an external platform.

Poll DB-backed positions, trades, realized PnL, and run logs for the bot bound to your key. No Hyperliquid clearinghouse calls on these routes — poll at most once every 15 seconds (rate limit: 60 requests/minute).

curl -s "https://apiv2.bbtraderx.com/api/v1/monitor/summary" \
  -H "x-bot-api-key: bbtx_read_…"

Send one JSON order per signal. The bot is identified from your API key — no botCode field is required in the body.

{
  "asset": "BTC",
  "side": "LONG",
  "action": "ENTER",
  "size": 10,
  "sizeType": "percent",
  "leverage": 3,
  "takeProfitPercent": 2,
  "stopLossPercent": 1,
  "sandbox": true
}

Common signal mapping: enter long → action ENTER, side LONG. Enter short → ENTER + SHORT. Full close long → EXIT + LONG with size 100 and sizeType percent. Full close short → EXIT + SHORT with size 100 and sizeType percent. Do not send size 0 on EXIT (HTTP 400). When flipping long to short on the same asset, send two requests: EXIT then ENTER.

{
  "asset": "BTC",
  "side": "LONG",
  "action": "EXIT",
  "size": 100,
  "sizeType": "percent",
  "sandbox": true
}

1. Copy the script snippet from the sandbox sidebar in your preferred language.
2. Paste the AI integration prompt into your coding assistant for a fuller reference implementation.
3. Set EXECUTE_URL and API_KEY from the sandbox panel in your server's environment.
4. Restrict asset to your UNIVERSE list before every POST.
5. Loop over each symbol in your universe, run your strategy logic, and post one order per signal.
6. Start with sandbox: true and confirm events in the live feed.
7. Switch to your bbtx_live_* key and sandbox: false when ready for production.

1. 1

   Validate in sandbox

   Post test orders with your bbtx_test_* key. Confirm each signal appears in the sandbox live feed with the expected asset, side, and action.

2. 2

   Switch API key and flag

   Update your server to use the bbtx_live_* key and set sandbox: false on every request.

3. 3

   Monitor production logs

   From the sandbox page, open Production logs (/signal-bots/{id}/logs) to review filled orders and errors after going live.

You can return to the sandbox at any time to regenerate keys, copy updated snippets, or test changes before redeploying your backend.