VTX Macro
06:59:42

Help Center

Contents

Questions while getting set up?

Join the VTX Macro Telegram group for community help and setup discussion.

Join Telegram

Getting Started with VTX Macro

⚠️ EXPERIMENTAL SOFTWARE & RISK WARNING

VTX Macro is an experimental AI trading tool in active development. AI models can hallucinate, misunderstand market conditions, and make unpredictable trades leading to rapid financial loss.

By using this software, you acknowledge:

  • The AI can and will make mistakes.
  • You should only trade with money you can afford to lose. Do not use rent money, savings, or crucial funds.
  • You are entirely responsible for your trades. The developers of VTX Macro are not liable for any losses incurred. Set strict conservative limits before enabling automated trading.

Welcome to VTX Macro, your advanced AI-powered trading platform. This platform is designed to help you automate your trading strategies using cutting-edge AI models and real-time market analysis. Whether you are looking to automate trades or get intelligent market insights, VTX Macro provides the tools you need.

How It Works

VTX Macro connects to your Hyperliquid account to execute trades on your behalf. Our AI engine analyzes market data, identifies trends, and executes strategies based on your configuration. The system operates in real-time, ensuring that you never miss a trading opportunity.

  • Real-time Analysis: Continuous monitoring of market conditions.
  • AI Execution: Automated trade execution based on AI signals.
  • Risk Management: Built-in safeguards to protect your capital.

Account Sign-In Options

You can sign in with email/password, passkeys and two-factor authentication, or Google when Google sign-in is available.

Google sign-in is used only to verify control of your email address and sign you in to VTX Macro. VTX does not request, store, display, or depend on your Google profile name, profile photo, contacts, Gmail, Drive, Calendar, files, or any non-auth Google scope.

Optional: Free Google AI Studio BYOK Setup

If you want a low-cost starting model, you can use Google AI Studio's free Gemini API tier with Gemma 4 31B (gemma-4-31b-it) as your VTX Macro BYOK model. Google makes Gemma 4 available in Google AI Studio and through the Gemini API, and its pricing page currently lists Gemma 4 input and output tokens as free on the free tier.

Important: do NOT add a credit card or enable billing for this setup. Keep each Google AI Studio project on the free tier. Adding billing moves the project into a paid tier, which changes the token/request limits and can make usage billable under Google's current rules. If you want a paid Google setup later, create a separate paid project so your free-tier bot projects stay isolated.

Create the Google AI Studio key

  1. Sign in to Google AI Studio with the Google account you want to use.
  2. Open API Keys.
  3. Create a new project or use the default project AI Studio creates for new users.
  4. Create an API key for that project and copy it once.
  5. Do not click billing, upgrade, Google Cloud free trial, or credit-card prompts for this free-tier project.

Google AI Studio rate limits are project-scoped, not key-scoped. Creating more keys inside the same project does not create more free capacity. For VTX Macro, use one Google AI Studio project per bot so each bot has its own project quota.

Add it to VTX Macro

  1. Go to the System page.
  2. Open Bring Your Own Key (BYOK).
  3. Find Google Gemini and paste the AI Studio key into Key 1.
  4. Save the System page.
  5. Go to the AI page.
  6. Set the preferred model to Gemma 4 31B / gemma-4-31b-it with source Google Gemini.
  7. Start with one bot, watch for rate-limit warnings, and keep the Review Model off or on a separate provider/project while testing because reviewer calls consume additional provider quota.

With one free Google AI Studio account, users can potentially run up to 5 VTX Macro bots by creating up to 5 separate Google AI Studio projects and using one project/API key per bot. Treat this as practical free-tier guidance, not a guarantee: Google can change available models, token limits, request limits, and abuse controls at any time, so always check Google AI Studio -> Rate limits for each project before leaving bots running.

Setting Up Hyperliquid

To use VTX Macro, you need to connect your Hyperliquid account. Follow these steps carefully to ensure correct configuration:

Before You Connect

You need a crypto wallet that can connect to Hyperliquid, such as Trust Wallet, Rabby, MetaMask, or another wallet you trust. This will be your main wallet: it holds your funds, connects to Hyperliquid, and authorizes the trading-only API wallet you later add to VTX Macro.

Before opening Hyperliquid:

  1. Create or open your wallet and make sure you control the recovery phrase.
  2. Send USDC to that wallet on the Arbitrum network. For example, you might start with 100 USDC if that is the amount you are comfortable testing with.
  3. Send a small amount of ETH to the same wallet on the Arbitrum network for gas. For example, about $0.25 of ETH on Arbitrum is enough for typical setup transactions, though gas needs can change.
  4. Go to Hyperliquid and connect that wallet.

Double-check the network before sending funds. USDC and ETH must arrive on Arbitrum, not Ethereum mainnet or another chain, for this setup flow.

IMPORTANT: Account Type Requirement VTX Macro only supports Manual account mode on Hyperliquid. This is the required setup because perp collateral, account equity, drawdown, and strategy history are easier to reconcile consistently.

  • Manual account mode (required): You explicitly deposit USDC into the matching Hyperliquid Perps balance before trading.
  • Why Manual: Hyperliquid's own account-mode guidance recommends this account setup for market makers, high-volume automated users, and builders. VTX follows that automation-oriented guidance instead of trying to run bots through account modes whose balances and cross-margin behavior are harder to reconcile safely.
  • Unified Account, Portfolio Margin, and HIP-3 DEX Abstraction (not supported): VTX Macro does not support running bots through these Hyperliquid account modes. The System and Trade surfaces reject unsupported account modes instead of silently treating them as normal perps accounts.
  • HIP-3 perp DEX markets: Some Hyperliquid perp markets are builder-deployed DEX markets. VTX shows clean labels such as GOLD-USDC or USA500-USDC with a small DEX pill such as xyz or cash; technical/API/debug symbols may still appear as xyz:GOLD or cash:USA500.
  • One wallet per exchange/DEX: Use a separate main wallet and API wallet for each venue you trade with VTX Macro, such as default Hyperliquid Perps (hl), xyz, cash, or any other HIP-3 perp DEX. Do not mix default Perps and multiple DEX venues on one VTX wallet. Keeping them separate makes balances, positions, PnL, history, and risk controls much easier to reconcile.

Current Unified Account Scope:

  • Existing profiles are not automatically changed or removed.
  • Some compatibility behavior may still appear in the app, but official support is paused because Hyperliquid's current Unified Account API behavior is not reliable enough for supported bot operation.
  • To use VTX Macro, switch the wallet to Manual account mode, disable HIP-3 DEX Abstraction, and keep USDC in the specific Perps balance for the market you trade.

How to Switch Between Account Types: If you want to switch from Unified Account mode to the supported Manual account mode:

  1. Go to the Hyperliquid App.
  2. Open Portfolio.
  3. Click Account Type in the Portfolio action bar.
  4. Choose Manual. If Hyperliquid documentation or older UI copy uses names like Standard or Classic, use the current app's Manual account type for VTX Macro.
  5. To use the supported Manual setup, make sure Unified Account, Portfolio Margin, and HIP-3 DEX Abstraction are not selected. Manually transfer USDC in Hyperliquid to the correct destination: Perps for default markets, or the matching Perps (xyz) / Perps (cash) style balance for a HIP-3 DEX market. VTX Macro does not move collateral between Spot, native Perps, and HIP-3 DEX balances for you.
  1. Connect to Hyperliquid: Go to Hyperliquid and connect your main trading wallet (e.g., via RabbitX or direct connection). This is the wallet that holds your funds.
    • Strongly recommended: Use a separate Hyperliquid wallet for VTX Macro only, and dedicate that wallet to one exchange/DEX venue. For example, do not use the same VTX wallet for default Hyperliquid Perps (hl) and xyz or cash markets. For the best experience, do not manually trade on the same wallet while VTX Macro is using it. Outside activity on the same wallet can make the app's wallet balance, PnL, and trade history appear incorrect.
  2. Generate API Wallet: Navigate to the API section in the Hyperliquid dashboard. Click to generate a new API Wallet.
    • This will provide you with an API Wallet Address and a Private Key.
    • Copy the Private Key immediately, as it may not be shown again.
  3. Configure VTX Macro: Go to the System page on VTX Macro.
  4. Enter Credentials:
    • Wallet Address: Enter your MAIN Wallet Address (the one with the funds), NOT the API wallet address.
    • Private Key: Enter the API Wallet Private Key you just generated.

CRITICAL: The "Wallet Address" field must be your Main Wallet Address (where your funds are). The "Private Key" is the signer key from the API wallet. If you enter the API wallet address as the main address, the system will not be able to find your funds or execute trades correctly.

Verification & Requirements

To ensure security and proper configuration, the system performs a read-only credential check.

  • No Test Order: Verification does not place or cancel an order.
  • Authorization: Hyperliquid confirms that the signing key belongs to the wallet or is an authorized agent for it.
  • Account Read: VTX Macro reads the selected account state to confirm the wallet is available.
  • Purpose: This prevents a signing key for one wallet from being used with a different profile wallet.

Security & Fund Custody

Agent Tokens

Agent tokens let CLI and MCP agents act as your authenticated user with only the scopes you grant. The easiest setup is vtx auth login, which opens a browser approval page and saves the approved token locally for the CLI and MCP server.

  • Browser login stores the approved token in the local CLI token file.
  • Use the smallest scope set that fits the job. For example, a status-only agent usually needs read access, while a trading agent needs explicit trading or bot-control scopes.
  • Use vtx auth logout --revoke on that machine when you want to remove its CLI/MCP access.
  • Revoking a token removes future access and stops any headless Client Mode runtime lease tied to that token.
  • Client Mode agents use your own compute, provider access, and exchange access and do not add a VTX platform fee. Server Mode bots started by agents use VTX infrastructure and normal Server Mode fees.

Using The CLI

The VTX CLI is for users who want to manage profiles, check bot status, run a headless Client Mode runtime, or connect VTX Macro to local automation.

Install the VTX CLI on the machine that will run the agent:

npm install -g @vtxmacro/cli
  1. Choose scopes for the job:
    • Read-only/status: read
    • Create or revoke tokens: token:write
    • Edit profiles or bot settings: profile:write
    • Start or stop bots/runtimes: bot:control
    • Place or cancel orders: trading:execute
    • Write provider or exchange credentials: secrets:write
    • Run headless Client Mode with local secret hydration: secrets:hydrate
  2. In a terminal on the machine that will run the agent, set the API URL and profile if needed:
export VTX_API_URL="https://api.vtxmacro.com"
export VTX_PROFILE_ID="<profile-id>"
  1. Log in:
vtx auth login --scopes read,bot:control,trading:execute,secrets:hydrate

The CLI prints an approval link and opens your browser. Sign in to VTX Macro if needed, approve access, then return to the terminal.

  1. Verify access:
vtx --json auth whoami
vtx --json bots status

Common CLI commands:

# Read status and recent bot logs
vtx --json bots status
vtx --json bots logs

# Configure and start a Server Mode bot
vtx --profile <profile-id> bots configure --symbol BTC --timeframe 15m --size 100
vtx --profile <profile-id> bots start

# Run headless Client Mode locally
vtx --profile <profile-id> runtime run --follow

# Run one local Client Mode cycle, useful for testing
vtx --profile <profile-id> runtime run --once

# Stop the local runtime lease
vtx --profile <profile-id> runtime stop

Headless Client Mode runs on your machine. Your machine must stay online, and any local AI server or provider access used by that runtime must also be reachable from that machine.

Using MCP

MCP lets compatible agent apps call VTX tools directly instead of shelling out to individual CLI commands.

  1. Make sure the VTX MCP command is installed on the same machine as your agent app.
  2. Log in once with the CLI on that machine:
vtx auth login --scopes read,bot:control,trading:execute,secrets:hydrate
  1. Configure your MCP-compatible agent app to start this command:
vtx-mcp

The MCP server reads the same saved token and environment settings as the CLI. If your agent app lets you set environment variables for an MCP server, set VTX_API_URL and VTX_PROFILE_ID there too.

MCP tools follow the same permissions as the CLI. Examples include vtx_whoami, vtx_profiles_list, vtx_bots_status, vtx_bots_start, vtx_runtime_events, vtx_trade_market_order, vtx_secrets_status, and vtx_ai_config. If a tool fails with a permission error, run vtx auth login --scopes ... again with the missing scope or revoke the old token and start over with a narrower, correct scope set.

Keep Agent Tokens private. Anyone with the token can use the scopes you granted until the token expires or you revoke it.

Is my money safe? Can VTX Macro withdraw my funds?

Yes, your money is safe, and no, VTX Macro cannot withdraw your funds. The platform is strictly non-custodial, meaning your capital remains securely protected by Hyperliquid's native cryptographic boundaries.

When you configure the platform, you provide an API Wallet (Agent Key), not your main wallet's private key. Hyperliquid's protocol enforces strict, mathematical limitations on what an Agent Key can do:

  • What it CAN do: Place orders, cancel orders, and adjust leverage (known as L1 trading actions).
  • What it CANNOT do: Withdraw funds, transfer USDC, or move assets to another account.

Withdrawals and transfers are "User-Signed Actions" that can only be authorized by your Main Wallet (e.g., your MetaMask or Rabby extension).

Because of this architectural design, even in the absolute worst-case scenario—if your VTX Macro account or the platform itself were fully compromised—your funds mathematically cannot be withdrawn or stolen. The maximum risk exposure from a leaked API key is strictly limited to unauthorized trading activity within the exchange.

System Settings

The System page is the central configuration hub for your VTX Macro environment. From here, you can manage your trading profiles, connect your exchange accounts, configure AI providers (BYOK), and personalize your user settings.

Note on Defaults: Looking for the default AI parameters (Timeout, Tokens, etc.)? These are listed in Global Platform Defaults, not on the System page.

Trading Profiles

Profiles allow you to create isolated environments for different trading strategies or purposes. Each profile maintains its own:

  • Exchange Connection (Wallet Address)
  • AI Preferences (Risk tolerance, active models)
  • Trade History & Performance Metrics

Managing Profiles

  • Create: Click the + button to create a new profile. Each account can have up to 100 profiles total.
  • Switch: Click on any profile card to make it active. The entire application (Trading, Analysis, Settings) will context-switch to this profile.
  • Handle: Each public profile handle is 3-20 letters, numbers, underscores, or hyphens. The leading @ is displayed by the app and does not count toward that limit.
  • Delete: Remove unused profiles to keep your workspace clean. Note: Trading history for deleted profiles may be archived.
  • Execution Mode: Any profile can use Client Mode or Server Mode. The account's 100-profile total limit is the only profile-count limit; execution mode does not reduce that allowance.
  • Profile Start and Stop: In Server Mode, the profile controls start or stop the VTX-hosted runtime. In Client Mode, those same controls save what the profile should do without making the System page the runtime owner. If no eligible app currently owns the profile, a VTX toast explains that the request is waiting for Trade to establish ownership. Stop remains authoritative even when a different window owns the runtime: after Stop succeeds, System clears the matching saved recovery intent in that browser, and browser or desktop recovery cannot restart that profile until you send a new Start request.

Exchange Connection (Hyperliquid)

Connect your Hyperliquid account to enable live trading. See Getting Started for the full step-by-step guide on generating these credentials.

  • Wallet Address: Your primary Hyperliquid address (e.g., 0x...). This is used for monitoring balances and positions.
  • Private Key: The API Wallet Private Key generated from the Hyperliquid settings page.
    • Note: Do not use your main wallet's private key. Always use an API Wallet key, which is restricted to trading only and cannot withdraw funds.

VTX uses the profile's public wallet address for read-only balance, position, and risk-monitoring account reads. The API wallet private key stays encrypted in that profile and is available only to profile-scoped exchange operations; it is not copied into or sourced from platform environment configuration.

Stop the profile runtime before replacing or removing its wallet address or API wallet private key. VTX rejects credential changes while the profile is running so an in-flight Client or Server action cannot cross from one wallet or signer to another. Save the new connection, then start the profile again.

Strongly recommended: Use a dedicated Hyperliquid wallet for VTX Macro only, and dedicate each wallet to one exchange/DEX venue. For example, use one wallet for default Hyperliquid Perps (hl) and separate wallets for xyz, cash, or other HIP-3 perp DEX markets. Avoid manually trading on that wallet or using it for separate strategies while VTX Macro is running. Outside activity or mixed venue activity on the same wallet can make the app's wallet balance, PnL, and trade history appear incorrect.

Unsupported Hyperliquid account modes: If the connected wallet is detected in Unified Account mode, the System page shows a red warning. VTX trading support is for Hyperliquid Manual account mode only. Hyperliquid's own account-mode guidance recommends this setup for market makers, high-volume automated users, and builders, and VTX follows that automation-oriented guidance for bot safety and reconciliation. Portfolio Margin and HIP-3 DEX Abstraction are also unsupported. Disable those modes in Hyperliquid before running bots.

HIP-3 DEX collateral: HIP-3 perp DEX markets can use separate balances such as Perps (xyz) instead of the default Perps balance. VTX can show and route the selected market identity, but it does not transfer funds between Spot, default Perps, and DEX-specific Perps balances. Move collateral in the Hyperliquid interface before trading that market, and keep each VTX wallet dedicated to one of those venues.

Bring Your Own Key (BYOK)

VTX Macro is Bring Your Own Key (BYOK) only. To run the bot or use any AI generation feature, connect API keys from the providers you want to use. There is no platform-key mode or account-level BYOK switch. If the active profile does not have a key for the selected provider, VTX stops the request and asks you to add one instead of using a VTX-owned provider key.

VTX Macro handles the trading workflow, runtime controls, model selection, analysis history, and safety layer around those provider accounts. Provider-managed usage, rate limits, model access, and provider bills remain in your provider account.

Each profile can store up to five keys for the same BYOK provider. The System page shows configured provider keys as Key 1, Key 2, and so on. VTX tries the keys in the visible order for the selected provider and model before moving to the configured fallback model chain. A fallback provider must also have its own key on the profile; VTX never reuses one provider's key for another provider. Keys stay masked after saving, and clearing a key removes it from that provider's order.

Supported Providers

VTX Macro groups cloud AI connections under one BYOK provider experience while keeping each provider's API key and model routing separate. The app currently tracks 16 BYOK providers and a synced catalog of 967 available AI models:

  • Providers: Alibaba Cloud Model Studio, Amazon Bedrock, Anthropic, Cerebras, DeepSeek, Fireworks AI, Google Gemini, Groq, Lightning AI, Mistral, Moonshot/Kimi, OpenAI, OpenRouter, Together AI, Venice AI, and xAI.
  • Google keys: Google Gemini keys can be limited to different Google API surfaces. Some keys call the Gemini / Generative Language API, while Vertex AI Express keys call Vertex's aiplatform.googleapis.com API. Prefixes such as AIza and AQ. are useful hints, but the exact API restrictions attached to the key are what determine where it works.
    • VTX Macro routes Gemma 4 models through the Gemini / Generative Language API because Vertex AI Express does not currently expose the Gemma 4 publisher-model endpoint for normal API-key calls. Use a Google key that is allowed to call the Gemini API for Gemma 4.
    • Google AI Studio, Gemini API, and Vertex AI can price or limit the same Google model differently. Treat displayed prices as guidance and confirm the Google pricing and rate-limit page for the API surface your key is allowed to use.
    • For the free Google AI Studio Gemma 4 setup, do not add a credit card or enable billing on that project. Billing changes the project's tier, limits, and billing behavior. Keep paid Google experiments in a separate project from free-tier bot projects.

This list highlights current featured models only. You can access additional models dynamically synced via your configured API keys.

What BYOK gives you:

  • Provider choice: Use the providers, model families, and account tiers you already trust.
  • Your own provider limits: Requests use your provider account, so available throughput, model access, and rate limits come from your provider plan.
  • Execution-mode privacy: In Server Mode, prompts go from VTX Macro servers to the provider. In Client Mode, prompts go directly from your browser or desktop app to the provider while VTX Macro keeps status, history, and settings in sync.
  • Predictable VTX billing boundary: You pay the provider directly for provider-side API usage. In Server Mode, qualifying trader calls are billed with the flat VTX Macro platform fee of $0.0025 per AI trader call, but prompt/run cost displays stay raw and do not include that flat fee. In Client Mode, VTX Macro is free forever and does not add a platform fee because your browser/device runtime sends the model request. Insights and Trade Analysis calls are exempt from the trader-call fee. You must maintain a positive VTX Macro credit balance for billable server-side activity.

Execution Mode

Each trading profile runs in one of two execution modes. Your choice determines where the AI runs, how your API keys are stored, and uptime guarantees.

How to Select Execution Mode

On the System page:

  1. Select or create a trading profile.
  2. Look for the Execution Mode control in the profile card (typically near the top or profile settings).
  3. Click the mode selector to toggle between Server (Purple badge) and Client (Blue badge).
  4. The selection is saved automatically per profile.

Indicator: A colored status badge shows the current mode:

  • Purple badge = Server Mode
  • Blue badge = Client Mode

Profile Selector and Runtime Pulse

On profile-scoped pages, the top navigation bar includes a compact profile selector. Open it to switch between your profiles without leaving the current workflow.

The selector can also show a small runtime pulse next to a profile handle:

  • A visible pulse means that profile has a live AI Assistant or AI Trader runtime signal.
  • The pulse follows the profile, not only the page you are viewing. If a bot is running for @Example, the indicator can still appear when you are switching from another profile.
  • The menu is intentionally compact on desktop and mobile; long handles are clipped instead of stretching the whole menu.

Security Page

The Security page is where you manage sign-in safety for your account.

  • Authenticator: Set up or remove app-based two-factor authentication.
  • Email 2FA: Use your account email as a second sign-in factor.
  • Passkeys: Add, rename, or remove passkeys for faster secure sign-in.
  • Sessions: Review signed-in browser and desktop sessions, including the device, IP address, start time, expiration time, and any active Client Mode profile labels tied to that session.
  • Revoke: Remove one session if you do not recognize it. Revoking a session also stops Client Mode bots tied to that session.
  • Terminate All Sessions: Sign out everywhere and stop Client Mode bots tied to those sessions. Use this if a device is lost, shared, or no longer trusted.

CLI and MCP Access

VTX Macro can be controlled from automation tools such as Codex, Claude Code, and other MCP-capable clients through the VTX CLI and vtx-mcp server. This uses your normal VTX account permissions: agent tools do not get extra hidden access, and profile-scoped actions still need the selected profile ID.

What Agents Can Do

With the right token scopes, an agent can:

  • List, create, rename, or delete your profiles.
  • Switch a profile between Client Mode and Server Mode.
  • Configure AI Trader settings such as symbol, timeframe, size, leverage, and loop interval.
  • Start, stop, check status, and read logs for Server Mode AI Trader bots.
  • Read Client Mode runtime status and runtime events.
  • Add or rotate runtime secrets such as provider API keys or Hyperliquid API-wallet keys. Secret responses stay masked.
  • Place or cancel manual trade orders only when you explicitly grant trade execution access.

Setup Flow

  1. Install the VTX CLI package on the machine where your agent runs.
  2. Run vtx auth login --scopes read,bot:control for a read-and-control setup, or add only the extra scopes you actually need.
  3. Approve the browser login prompt while signed in to VTX Macro.
  4. Verify the connection with vtx --json auth whoami.
  5. Point your MCP client at the vtx-mcp command. Set VTX_API_URL for the target VTX API, and set VTX_PROFILE_ID when you want tools to default to one profile.
  6. Ask your MCP client to list tools. You should see VTX tools such as vtx_profiles_list, vtx_bots_configure, vtx_bots_start, vtx_bots_stop, vtx_runtime_status, and vtx_trade_market_order.

Scope Guide

  • read: profile lists, runtime status, events, billing visibility, AI config, and history reads.
  • profile:write: profile changes, preference changes, and execution-mode changes.
  • bot:control: start or stop Server Mode bots and start Client Mode runtime sessions.
  • secrets:write: write or rotate runtime secrets.
  • secrets:hydrate: allow a leased Client Mode runtime to hydrate the secrets it needs locally.
  • trading:execute: place or cancel orders through the same Trade page safety checks, risk rules, rate limits, and duplicate-order protections.

Start with the smallest scope set that matches the task. For example, a status-only setup needs read; a user managing a Server Mode bot usually needs read,bot:control,profile:write; direct order placement requires trading:execute.

Server Mode vs. Client Mode From Agents

MCP tools can configure profiles and start or stop Server Mode AI Trader bots. Server Mode runs on VTX Macro servers and uses normal Server Mode billing and limits.

For Client Mode, the headless runtime is launched with the CLI command vtx --profile <id> runtime run --once or vtx --profile <id> runtime run --follow. The runtime acquires a lease, runs provider and exchange work locally on that machine, reports decisions and executions back to VTX Macro, and stops cleanly if it loses ownership. MCP can read Client Mode runtime status/events, while the actual long-running local runtime should be started with the CLI.

Safety Notes

  • Agent tokens authenticate as you. Treat them like account credentials.
  • Raw tokens are shown only once during creation or login approval. Store them in the CLI token file, not in chat prompts or MCP config text.
  • Use vtx auth logout --revoke when you no longer want that machine or agent to have access.
  • If you grant trading:execute, the agent can submit real orders within normal VTX and exchange constraints.

Desktop App Settings

When you are using VTX Macro Desktop, the System page includes a Desktop App card. These controls affect only the desktop app on the current device:

  • Start at login: Launch VTX Macro Desktop after you sign in to this computer.
  • Start minimized: Open the app in the background after startup.
  • Close to tray: Hide the desktop window instead of fully exiting when you close it.

These controls are hidden in a normal browser tab. The desktop app uses the same VTX Macro pages and profile settings as the browser, so you do not need to configure separate trading or AI settings for desktop.

Mode Comparison

AspectServer ModeClient Mode
Runtime LocationRuns on VTX Macro serversRuns in your browser or desktop app
API Key StorageEncrypted in VTX MacroStored only in browser (never sent to VTX servers)
Uptime24/7 continuous (even with browser or desktop app closed)Only while the browser or desktop app session stays open
Key PrivacyKeys stay encrypted with VTX MacroKeys stay on your device
VTX CostPremium paid mode using VTX creditsFree forever from VTX
Best For24/7 trading, always-on monitoringPrivacy-first users, testing, limited sessions
Resume After CloseN/A (always running)Best-effort auto-resume if intent was active

When to Use Each Mode

Choose Server Mode if:

  • You want your AI Trader running 24/7 without needing to keep a browser tab open.
  • You prefer VTX Macro to securely manage your API keys.
  • You need guaranteed uptime for continuous market monitoring.
  • You are comfortable using VTX credits for premium server-side automation.

Choose Client Mode if:

  • You prioritize keeping API keys on your local device (maximum privacy).
  • You're testing strategies for short sessions.
  • You want to connect a local LLM (Ollama, LM Studio) for offline inference.
  • You prefer browser-based execution for compliance or security reasons.
  • You want the VTX runtime to be free forever and can keep your browser or desktop app open while it runs.

Multiple Client Mode Profiles in One Browser

Client Mode ownership is tracked per profile. In one browser window, you can start a Client Mode AI runtime for one profile, switch to another profile, and start another Client Mode runtime there. Each profile keeps its own runtime state and status pulse.

This does not make Client Mode a background server:

  • The browser window or desktop app still needs to stay open and connected.
  • Each profile still has one active owner at a time.
  • Opening the same profile in another window or on another device can take over that profile's runtime.
  • Taking over one profile does not automatically stop unrelated profile runtimes that the original window still owns.

The System page can request Client Mode Assistant or Trader Start/Stop for any profile, but it does not silently move ownership into the System window. Open that profile on Trade to establish ownership or use Trade's existing Take Over action when another window owns it. A Start-request toast means the intent was saved; the existing runtime status indicator shows when the bot is actually running.

If Stop is requested while an order, cancel, or leverage update is already being confirmed, the bot is marked stopped immediately but ownership can remain briefly reserved until the exchange action settles. VTX blocks new work and sensitive mode, wallet/key, profile, or takeover changes during that safety window. If the browser loses the response, VTX keeps the profile protected through the signed expiry and releases the fence only after a new exchange check started after expiry confirms that no effect was observed.

Keep Your Device Awake for Client Mode

Client Mode runs from the browser window or desktop app that owns the profile. If the operating system sleeps, hibernates, suspends network access, or aggressively pauses the app, the local runtime can miss cycles until the device wakes and reconnects. Before relying on Client Mode for an active session, keep the device powered and configure sleep settings for the machine that owns the runtime.

Windows:

  • Open Settings > System > Power & battery.
  • Under Screen and sleep, set When plugged in, put my device to sleep after to Never while Client Mode is running.
  • If you run on battery, choose a longer battery sleep timeout or keep the laptop plugged in.
  • In Control Panel > Power Options > Choose what closing the lid does, make sure closing the lid does not put the computer to sleep if you expect the bot to keep running.
  • Optional command-line setup: open PowerShell as Administrator and run powercfg /change standby-timeout-ac 0 to disable plugged-in sleep.

macOS:

  • Open System Settings > Battery.
  • On desktops, open Energy Saver if it appears; on laptops, review Options and Power Adapter settings.
  • Enable Prevent automatic sleeping when the display is off when available.
  • Set display and sleep-related power adapter settings so the Mac stays awake while plugged in.
  • Keep the lid open, or use an external display, keyboard, mouse, and power adapter if you run a Mac laptop in clamshell mode.

Linux:

  • In GNOME, open Settings > Power and set Automatic Suspend to Off for plugged-in sessions.
  • In KDE Plasma, open System Settings > Power Management and disable sleep/suspend for AC power.
  • If your distribution uses systemd sleep controls, advanced users can review systemctl status sleep.target suspend.target hibernate.target hybrid-sleep.target before changing system policy.
  • Make sure laptop lid-close behavior does not suspend the machine if the runtime must continue.

Also check browser-level energy features if you run Client Mode in a browser tab. Chrome, Edge, Safari, and Firefox can reduce background activity under battery saver or memory saver modes. Keep the VTX Macro tab open, avoid force-quitting the browser, and disable browser energy saver for long Client Mode sessions when needed. VTX Macro Desktop startup and tray settings can help reopen the app after login, but they do not override operating-system sleep.

Local AI & Client Mode

Local AI models (Ollama, LM Studio, etc.) require Client Mode because they run on your machine via loopback. See Local AI below for setup instructions.

Local AI (Ollama, LM Studio, llmster)

The Local AI card on the System page lets you connect a browser-owned OpenAI-compatible endpoint such as Ollama, LM Studio, or llmster.

The Use Ollama native API toggle controls which protocol VTX Macro uses for that Local AI connection:

  • Off: Treat the server as a generic OpenAI-compatible local endpoint.
    • Best for LM Studio, llmster, Qwen Studio, and similar local servers.
    • Model discovery uses /v1/models.
    • Runtime requests use /v1/chat/completions.
  • On: Treat the server as native Ollama.
    • Model discovery uses /api/tags.
    • Runtime requests use /api/chat.
    • Reasoning controls are sent using Ollama's native think behavior instead of OpenAI-compatible reasoning fields.

The toggle does not change the selected model by itself. It only changes how VTX Macro talks to the configured Local AI server.

Important rules:

  • Local AI requires Client Mode for the active profile.
  • The recommended Base URL is always loopback on the same device as the browser.
  • Common defaults:
    • LM Studio / llmster: http://127.0.0.1:1234/v1
    • Ollama: http://127.0.0.1:11434/v1
  • Use Test & Refresh to read the model list for the selected protocol:
    • OpenAI-compatible mode: GET /v1/models
    • Native Ollama mode: GET /api/tags
  • For Ollama, keep the full returned tag when present, for example my-local-model:latest.
  • Test & Refresh loads the returned models for the active endpoint so they appear on the AI page.
  • Apply saves endpoint access only. Choose the active main and review models on the AI page.

Quick start

  1. Install and start your local server.
  2. Use the matching loopback URL in VTX Macro.
  3. Set Use Ollama native API:
  • Leave it off for LM Studio / llmster / Qwen Studio / other OpenAI-compatible servers.
  • Turn it on for native Ollama.
  1. Run Test & Refresh so the returned models appear on the AI page.
  2. Click Apply to save the endpoint, then choose the Local AI model on the AI page.

Examples:

  • LM Studio: http://127.0.0.1:1234/v1
  • llmster: http://127.0.0.1:1234/v1
  • Ollama: http://127.0.0.1:11434/v1

For llmster in browser Client Mode, a working startup command is:

lms server start --bind 127.0.0.1 --port 1234 --cors

For Ollama, a practical flow is:

ollama pull qwen3:8b
curl http://127.0.0.1:11434/v1/models

If you already have a GGUF file and want Ollama to serve that exact model, create a Modelfile:

FROM C:\path\to\your-model.gguf

Then import it:

ollama create my-local-model -f Modelfile

Ollama normally exposes browser-usable loopback CORS headers already, so it does not usually need an LM Studio-style --cors startup flag.

Loopback Forwarding for Another LAN Machine

Keep VTX Macro pointed at localhost / 127.0.0.1 on the browser device and run a local TCP forwarder on that same device. The browser should not depend on arbitrary LAN IP targets directly.

This means:

  • The remote machine runs Ollama, LM Studio, or llmster.
  • VTX Macro still uses loopback locally.
  • The user's device forwards the local port to the LAN machine.

Why VTX Macro still uses loopback

VTX Macro's hosted app runs in a secure browser context over HTTPS. Modern browsers treat direct requests from an HTTPS page to a private LAN HTTP address such as http://192.168.x.x:1234 as restricted mixed-content / private-network traffic. Depending on the browser, that can be blocked outright or require extra CORS and private-network headers that many local model servers do not provide.

Loopback addresses such as 127.0.0.1 and localhost are treated specially by browsers and are the most reliable way to connect Local AI from Client Mode. This is a browser security boundary, not an app setting that VTX Macro can disable.

Example topology

  • Browser / VTX device: your main desktop or laptop running the VTX Macro tab.
  • Model server device: another PC on your LAN running LM Studio, Ollama, or llmster.
  • Remote model server example: <remote-lan-ip>:1234
  • Local loopback forward example: 127.0.0.1:1235 -> <remote-lan-ip>:1234
  • VTX Base URL: http://127.0.0.1:1235/v1

You can keep port 1234 on the remote machine. If 1234 is already used on the browser device, choose another local port such as 1235 for the forwarder.

Windows loopback setup

Windows has a built-in TCP forwarder:

netsh interface portproxy add v4tov4 listenaddress=127.0.0.1 listenport=1235 connectaddress=<remote-lan-ip> connectport=1234

Check the rule:

netsh interface portproxy show all

Test it:

curl http://127.0.0.1:1235/v1/models

Remove it later if needed:

netsh interface portproxy delete v4tov4 listenaddress=127.0.0.1 listenport=1235

macOS loopback setup

Install socat if it is not already available, then forward a local loopback port to the LAN machine:

brew install socat
socat TCP-LISTEN:1235,bind=127.0.0.1,fork TCP:<remote-lan-ip>:1234

Test it:

curl http://127.0.0.1:1235/v1/models

Keep the socat terminal running while you use VTX Macro.

Linux loopback setup

Most Linux distributions can use socat as well:

socat TCP-LISTEN:1235,bind=127.0.0.1,fork TCP:<remote-lan-ip>:1234

Test it:

curl http://127.0.0.1:1235/v1/models

Keep the socat process running while you use VTX Macro. If your distro does not include socat, install it from your package manager first.

What to enter in VTX Macro

After the forwarder is working, keep the Local AI card pointed at the local loopback URL on the browser device:

  • http://127.0.0.1:1235/v1 for the forwarded remote machine example above
  • http://127.0.0.1:1234/v1 if the model server is running on the same device as the browser

WebGPU

The WebGPU card on the System page lets you configure a browser-native local model that runs directly on your device's GPU.

  • Client Mode only: WebGPU is available only when the active profile uses Client Mode.
  • No API key required: Inference runs inside your browser tab instead of calling a cloud provider.
  • Model selection: Choose a WebGPU-compatible model from the synced catalog or provide a supported custom model link when needed. The picker animates when it opens or closes, and its visible model rows move smoothly when you search, filter downloaded models, or change the sort order.
  • Apply behavior: Apply saves the selected WebGPU model and switches the active AI page model to that WebGPU choice.
  • Device limits apply: Browser VRAM and tab memory limits are stricter than native runtimes, so larger models and long prompts can fail even if they work in Ollama or LM Studio.
  • Catalog floor: The synced WebGPU catalog excludes models below 4000 tokens of inferred context window.

Use WebGPU when you want the simplest private local setup with no separate server process. If you need larger context windows, heavier models, or more stable long-running inference, use Local AI instead.

For model recommendations and deeper sizing guidance, see AI Configuration.

User Profile

Manage your public identity on the platform.

  • Handle: Your unique @username (e.g., @trader-alpha). This is visible on public leaderboards and public Trade Analysis links. You can change this periodically.
  • Identity: Displays your registered email and account role.

Regional Settings

  • Timezone: Configure the display timezone for all charts, logs, and timestamps.
    • Auto: Detects your browser's timezone.
    • Manual: Force a specific timezone (e.g., UTC) for consistent reporting.

Trading Interface & AI

The Trade Dashboard

The Trade page is your command center for both manual execution and AI supervision. It combines professional-grade charting with direct exchange execution and AI controls.

1. Market Overview & Charting

  • Asset Selector: Use the dropdown in the top-left to switch between markets (e.g., BTC, ETH, SOL). HIP-3 Hyperliquid perp DEX markets use the same clean pair labels, such as GOLD-USDC, with a small DEX pill such as xyz; technical/debug contexts may still show canonical symbols such as xyz:GOLD.
  • Advanced Chart: A fully interactive candlestick chart with adjustable timeframes (1m to 1w) and drawing tools. Your chart settings and drawings are saved automatically per profile.
  • Customizable Layout: You can resize the Chart, Order Entry, and Bottom Panel sections to suit your workflow.
  • Profile Selector: Use the profile selector in the top navigation bar to switch the Trade page between profiles. The selector can show a small runtime pulse beside profiles with a live AI Assistant or AI Trader signal, so you can see which profile is active even before opening that profile.
  • All Profiles View: If your account has more than one profile, the Trade page shows an All toggle beside the profile selector. Turn it on to view profile-owned positions, orders, history, AI activity, account equity, perps overview, and AI controls for every profile on the same page.
  • Runtime Ownership: Client Mode bots are owned per profile. If a profile is already running in another browser, desktop app, or headless runtime, the Trade page shows the current ownership state and lets you take over when that is safe.
  • Start requests from other pages: System can save a Client Mode Start request, but it does not take ownership. Trade remains the place where your app establishes ownership or explicitly takes it over. A saved request can wait until an eligible owner is available, and the normal runtime indicator confirms when execution actually starts.
  • In-flight exchange actions: Client Mode orders, cancels, and leverage updates are registered before they are sent. While Hyperliquid is still confirming one of these actions, VTX can temporarily block Take Over, mode, wallet/key, or profile changes. If confirmation is uncertain, do not retry the trade blindly; VTX keeps it fenced until fresh exchange evidence confirms the result or, after the signed request expires, a new exchange check confirms that no effect was observed.

2. Manual Order Entry

The right-hand panel allows for precise manual execution:

  • Order Types:
    • Market: Execute immediately at the best available price.
    • Limit: Set a specific limit price. Supports TIF (Time in Force) options like GTC, IOC, and ALO (Post-Only).
    • Pro: Access advanced algorithmic orders including Scale (laddering), TWAP (Time-Weighted Average Price), Stop-Limit, and Stop-Market.
  • Client Mode action scope: Manual Client Mode orders, cancels, leverage changes, and position closes require that profile to be selected. Select a profile before acting on its rows in All view. Scale, TWAP cancellation, and Close All are unavailable in Client Mode for now; place individual supported orders, cancel supported orders, or close positions individually instead.
  • Leverage: specific leverage slider. Note: This leverage setting applies to both manual trades AND AI trades for this symbol.
  • Size Inputs: Enter trade size in either Coin (e.g., 0.5 BTC) or USDC (e.g., $5,000).
  • Collateral scope: Default Hyperliquid perp markets use the default Perps balance. HIP-3 DEX markets can require funds in the matching DEX-specific balance, such as Perps (xyz). VTX does not move funds between Spot, default Perps, and DEX-specific Perps balances. Use a dedicated wallet per exchange/DEX venue, such as one for default Hyperliquid Perps (hl) and separate wallets for xyz or cash, rather than mixing venues on one VTX wallet.
  • Risk Tools:
    • Reduce Only: Ensures the order will only reduce or close an open position, never increase it.
    • TP/SL: specific Take Profit and Stop Loss triggers before placing the entry.

3. Position Management

The bottom panel gives you full visibility into your account state:

  • Positions Tab: View all active open positions, including Entry Price, Mark Price, Unrealized PnL, and Liquidation Price.
    • Actions: "Close Market" (instant exit), "Close Limit" (queued exit), "Edit Leverage", and "Edit TP/SL".
  • Open Orders: View and cancel working limit orders.
  • Trade History: A log of your recent fills and executions.
  • Funding: Track funding fee payments and receipts.

4. All Profiles View

The All toggle is a view mode, not a new profile. Your selected profile remains the chart and order-entry context, while the data panels expand to show every profile you own.

What changes in All view:

  • A Profile column appears on profile-owned rows so you can see which profile owns each position, open order, TWAP order, trade, funding entry, or order-history row.
  • Profile handles such as @Example are clickable. Clicking one opens that profile's normal Trade view.
  • Duplicate symbols stay separate when they belong to different profiles. VTX Macro does not merge or summarize them.
  • In Server Mode, row actions act on the row's profile. Client Mode keeps All view read-capable but requires selecting the row's profile before an exchange action, so another profile's local signer or durable action authority is never used implicitly.
  • The right rail shows per-profile account equity, perps overview, and AI Assistant / AI Trader controls.
  • AI messages can appear together in the normal AI panel with profile labels, so you can compare what different profiles are doing without losing ownership context.
  • Copy Trading messages also appear in the normal AI panel. CT rows show the copied trade result, while CR rows show the Review Model's approval or block using the same result-and-reasoning format as normal Trader review rows.
  • If Copy Trading remains active while the Main Model is disabled, the AI panel stays live for copied trades but does not show a countdown for a Main Model analysis that will not run. This is the same in Server and Client modes. An active AI Assistant keeps its own countdown.
  • Positions and the matching unrealized PnL come from the same profile snapshot, so a completed close clears both together instead of leaving an old PnL value behind.
  • When a fill opens, reduces, or closes a position, the visible Trade History tab refreshes automatically. If a live update is missed during a reconnect, the page continues checking while the tab is visible, so you do not need to reload the page or switch profiles to see the fill.

The chart and order-entry form stay tied to the selected profile. Selecting a symbol from another profile can update the chart symbol, but it does not silently switch which profile manual orders would use.

AI Assistant

The AI Assistant acts as a "dry run" for the AI Trader. It runs the same analysis logic as the automated trader but does not execute any trades.

Execution mode matters: In Server Mode, the AI Assistant analyzes the market securely on VTX servers and can continue running in the background after you close the browser or desktop app. Server Mode is the premium paid runtime, and qualifying server-mode trader calls may be billed with a VTX Macro platform fee. In Client Mode, your browser or desktop app owns the analysis logic entirely on your device, meaning the Assistant only runs while that active app session keeps control. Client Mode is free forever from VTX and never charges a VTX Macro platform fee.

This allows you to see exactly what the AI would do in the current market conditions without risking capital. You can activate it by toggling the AI Assistant switch on the Trade page (top right panel).

The newest AI response appears at the top of the panel. While you remain at the top, incoming responses continue to appear normally. If you scroll down to inspect an earlier response, the panel keeps that response in place while newer responses accumulate above it; return to the top to resume following the newest activity.

AI Trader

The automated execution side of the system relies on the same logic but connects directly to your active Trading Profile. It is designed with robust safety measures to protect your capital and active sessions:

  • Intelligent Pauses: In the event that an AI provider's network goes down (e.g., a "503 Service Unavailable" error) or you hit a temporary rate limit ("429"), the AI will automatically pause and display a clear warning banner. Crucially, the AI will not crash or halt indefinitely; it will intelligently retry running the analysis loop automatically instead. To start the AI Trader:
  1. Ensure your Hyperliquid API key is connected.
  2. Configure your strategy settings (Model, Risk, Prompts) on the AI page.
  3. Go to the Trade dashboard.
  4. Click the Start button inside the AI Trader panel.

Server Execution Mode: The AI Trader securely executes your strategy on VTX servers. Once started, it continues analyzing and trading 24/7, even if you close your browser or desktop app, log out, or turn off your device, until you explicitly click Stop.

Client Execution Mode: The AI Trader runs inside your browser or desktop app. This local execution mode keeps your keys strictly on your device and sends user-specific Hyperliquid account, order, fee, and execution reads from your active app session instead of using VTX servers as a live exchange proxy. VTX Macro still keeps shared market data, bot status, billing, history, and app settings in sync. Client mode has no guaranteed uptime or background daemon, but it provides best-effort auto-resume after app restart if the bot was active before closing and the same profile/session context is restored. Since the local app session manages the bot, it uses a single-master model; if you open the profile on another device, you can instantly take control of the AI Trader from that new device.

Multiple profiles in one app session: Client Mode can keep separate profile runtimes alive in one browser window or desktop app. You can start a Client Mode bot for one profile, switch profiles from the top selector, and start another profile's Client Mode bot without stopping the first one. Each profile still has one owner at a time, so another window or device can take over that specific profile.

Headless Client Mode: Advanced users can also run Client Mode from the VTX CLI or MCP agent on their own machine. Those runtimes still follow the same profile ownership, lease, and safety rules as app-owned Client Mode. If you need to remove access from an old machine, revoke its CLI token or use the Security page session controls.

Mode transparency: Whether running on VTX servers or in your local Client app session, decision logging, history, and active performance display look and feel the same. Execution safety logic remains identical across platforms.

The AI Trader will now execute trades automatically based on your configuration. Monitor the "Open Orders" and "Trade History" panels to see the AI in action.

VTX trading support is limited to Hyperliquid Manual account mode only. Hyperliquid's own account-mode guidance recommends this setup for market makers, high-volume automated users, and builders, so VTX follows that automation-oriented guidance for bot safety and reconciliation. Unified Account mode, Portfolio Margin, and HIP-3 DEX Abstraction remain unsupported for automated trading and are rejected by app safety checks.

Risk, Size & Leverage

VTX Macro keeps your automated trading defaults consistent across the platform:

  • AI Trade Amount (USDC): The notional size used for AI Trader orders. This is stored separately from your manual Trade page order size, so you can tune automation without affecting your one-off trades.
  • Leverage / Max Leverage: Your selected leverage is shared between the AI and Trade pages so you don't end up running automation at one leverage while placing manual orders at another.
  • Platform Cap: Leverage is capped at 50x (or the asset's specific limit) to ensure safety. If any setting reports a higher value, VTX Macro will clamp it back to the allowed maximum. The default recommended leverage is 2x.

Note: AI settings may auto-save with a short debounce. Once saved, other pages refresh the updated preference automatically.

Understanding the AI Control Panel

The panel displays your current Active Configuration during runtime:

  • Assets: List of symbols being monitored (e.g., BTC, ETH). HIP-3 markets may appear with clean labels plus DEX pills in the UI while prompts, API calls, and debug traces preserve canonical symbols such as xyz:GOLD.
  • Timeframes: Active intervals and candle lookback counts (e.g., 5m (25) = 25 candles of 5m data).

Max Trades Counter (Visible only when AI Trader is Active):

  • Used: Current number of "units" engaged in open positions.
  • Max: Your configured "Max Trades Global" limit.
  • Updates: Refreshes instantly on every AI execution cycle.

When you are using All view, each profile gets its own AI control block. Start and Stop buttons affect only that profile, and the status color follows the profile's execution mode.

AI Models & Reliability

VTX Macro uses advanced chat and reasoning models from your selected provider to analyze the market. Sometimes, a specific model may be unavailable due to high demand (Rate Limits).

Smart Fallback System If your preferred model encounters an error (e.g., 429 Rate Limit), the system automatically attempts to use a backup model to ensure your analysis continues without interruption.

  • Indicator: Look for the Amber colored badge and 🔀 shuffle icon in the AI log.
  • Hover Tooltip: Hover over the badge to see exactly which model was requested and which one was used.
  • Configured Cascades: The app can step from a preferred model to a lower-cost, lower-latency, or more available backup model from the same provider family.
  • Seamless: This happens automatically in the background. No action is required from you.

Local AI exception: When you select a model from the Local AI group, VTX Macro treats that local model as authoritative in Client Mode. It will not silently fall back to a cloud model or accept a non-local model override during runtime.

Multi-Asset Selection

You can configure the AI to monitor and trade multiple assets simultaneously using the Asset Selector on the AI page.

  • Click the assets input to open the selection menu.
  • Select assets to monitor (up to 3).
  • Use the sorting options (Volume, Price, Change) to find liquid markets.
  • The AI will analyze ALL selected assets in every execution cycle.

Operating Schedule

You can restrict autonomous trading to specific hours or market sessions (e.g., NY/London overlap) using the Schedule settings on the AI page.

  • Active Windows: Define specific day and time ranges. Outside these times, the AI status becomes Paused.
  • Timezone: Align windows with your local time or major market centers.
  • Presets: Quickly load standard sessions (e.g., "EU + US", "24/5 Weekdays") from the preset dropdown.
  • Close on Stop (Trader Only): Optionally force the AI to close all open positions when a schedule window ends.

Troubleshooting

If you are having issues starting the AI Assistant or AI Trader, please try disabling your VPN and/or ad blocker. These tools can sometimes interfere with the connection.

If you are using Local AI with Ollama, LM Studio, or llmster:

  • Keep the profile in Client Mode.
  • Prefer a loopback browser target on the same device:
    • LM Studio / llmster: http://127.0.0.1:1234/v1
    • Ollama: http://127.0.0.1:11434/v1
  • If the local server is running on another LAN machine, use a local forwarder on the browser device and still keep VTX Macro pointed at loopback. See the Local AI loopback setup.

Optional: Windows Boot Auto-Launch for Client Mode

Client mode runs in your browser tab or desktop app. If you want best-effort recovery after Windows reboot/login, you can auto-launch Chrome with a pinned VTX Macro Trade URL or use the desktop app's startup options.

This setup is not needed if your profile is in Server Mode. Opening or closing the browser window does not affect the Server Mode bot, and only an explicit Start or Stop command can change its state.

Preconditions:

  • You are logged into Windows for the scheduled task trigger.
  • Your VTX Macro auth session is still valid in that browser profile.
  • You already selected the target profile in VTX Macro.
  • Browser startup policy allows auto-opening the requested URL.

Task Scheduler Setup (Windows):

  1. Open Task Scheduler and choose Create Task.
  2. In General:
    • Set a name such as VTX Macro Client Resume.
    • Choose Run only when user is logged on.
  3. In Triggers:
    • Add trigger At log on for your user.
  4. In Actions:
    • Program/script: C:\Program Files\Google\Chrome\Application\chrome.exe
    • Add arguments: --new-window https://vtxmacro.com/trade
  5. Save the task and run it once manually to validate.

Client mode auto-resume and boot caveats:

  • This is best-effort only: it does not create a background daemon or guaranteed uptime.
  • Auto-resume only applies when runtime intent was active before close/restart.
  • Auto-resume is skipped when execution mode is not client or the restored profile does not match the bot that was active before close.
  • Ownership lease arbitration remains authoritative; another active owner window/device prevents duplicate local starts.
  • Startup retries are bounded with cooldown to avoid infinite failure loops; if resume is still skipped, open Trade and manually start once after resolving config/auth issues.
  • If your organization hardens browser startup policies, review Chrome policy restrictions for command-line URL launches.

AI Configuration

The AI page is the brain of your VTX Macro system. This is where you define how the AI thinks, what it trades, and the strict risk limits it must follow.

Tip: You can save different setups as Snapshots (e.g., "Bull Market Aggressive", "Weekend Conservative") to switch strategies instantly.

Fresh-profile baseline

When a profile has no saved override for an AI setting, VTX initializes that setting from this app-wide baseline:

  • Main Model uses gemma-4-31b-it. Review Model starts disabled with gemma-4-31b-it preselected.
  • The initial market scope is NEAR across 30m, 4h, 1d. If 5-minute or 15-minute analysis is selected later, its default lookback is 25 or 100 completed candles, respectively.
  • Each cycle runs every 60 seconds, uses 20 USDC units, and applies 2x leverage.
  • The application-side Tradability filter starts on, with an Open minimum of 8 and an Increase minimum of 8.
  • The hard Max Loss Count guardrail starts on for the short window at warning/critical 1/1, and on for the long window at 2/2.

The default System Prompt requires completed-candle confirmation, 30-minute/4-hour trend alignment, profitable-after-fee additions, position-specific exits, and a one-completed-30-minute-candle wait before entering the opposite direction after a full close. Regional timezone remains a System preference and defaults to Auto; Use My Averages remains a personal cost-display preference that defaults off. Neither is an AI-page bot strategy setting. Saved profile settings and snapshots continue to override this baseline.

Read-only configuration previews on Leaderboard, Trade Analysis, and embedded snapshot cards use the same compact Performance labels: Max F/E, Max DD%, and Max Loss%.

Recorded Last Execution Context panels appear automatically on AI and public Trade Analysis views. On public Trade Analysis, the panel is collapsed by default for signed-out visitors and remembers their choice in that browser. For a signed-in owner, the choice remains profile-specific. The panel animates when it opens or closes. Retained provider reasoning traces also appear automatically in History and Trade Analysis when the provider supplied one; there are no System-page visibility switches for either feature.

Changelog

The Changelog records profile setting updates as a compact timestamped list generated from the saved database event. Each entry shows the profile, source, setting, and readable before/after values. Snapshot changes show the snapshot name. Performance and Market Regime entries include each enabled switch, enforcement mode, evaluation or flip window, and warning/critical threshold, including Max Loss Count.

Prompt update rows are clickable. Open one to compare the complete saved prompt in a unified line-by-line view, where removed and added lines are marked separately. The Before and After tabs show either complete version by itself and provide copy buttons, while long unchanged sections can be expanded when needed. Profile Changelogs are public, so prompt text shown in a public Changelog can be viewed without signing in.

Settings updates approved through Codex or another VTX Insights MCP client are written to this same Changelog with an Insights MCP source label. The MCP result links to the saved event instead of maintaining a separate change log.

Model & Intelligence

Choose the brain that powers your trader.

  • Preferred Model: Select the specific chat or reasoning model used for trading decisions, such as a GPT, Claude, Gemini, Grok, Groq-hosted Llama/Qwen, or first-class BYOK provider model.
    • Models are dynamically synced from the app's current catalog of 967 available AI models across 16 BYOK providers, including Alibaba Cloud Model Studio, Amazon Bedrock, Anthropic, Cerebras, DeepSeek, Fireworks AI, Google Gemini, Groq, Lightning AI, Mistral, Moonshot/Kimi, OpenAI, OpenRouter, Together AI, Venice AI, and xAI.
    • If your profile has Local AI configured, an additional Local AI group appears in the selector.
    • The "Other Models" unified dropdown supports text search, available-key filtering, confirmed-free-model filtering, and multi-sort by model, provider, context window, token prices, and average observed cost. Model dropdowns animate when they open or close, and visible choices move smoothly when search, filters, or sort order changes. Local AI and WebGPU choices appear there when those runtimes are configured for the active profile.
    • If a BYOK provider has multiple saved keys, VTX tries Key 1, then Key 2, and continues in visible System-page order for key-specific or transient provider failures before using configured fallback models.
    • Every cloud model call requires a key stored for that provider on the active profile. Missing keys fail closed, fallback providers require their own profile keys, and Google endpoint retries keep using the same profile key.
  • Serverless vs. endpoint models: Some BYOK providers show both instantly callable serverless models and models that require you to create or start a provider-hosted endpoint first.
    • VTX Macro may show both kinds of models so you can use the full provider catalog.
    • Token prices are shown only when the provider publishes normal serverless or pay-as-you-go token pricing for that exact model.
    • Models that show $0.00 input and $0.00 output are treated as free in the model filters only when VTX Macro has confirmed both token prices are zero. Free models can be useful for testing or low-stakes analysis, but their quality, availability, rate limits, and latency may be less reliable than paid models.
    • BYOK users are responsible for reviewing each provider's current terms, free-tier limits, retention rules, and usage policies before relying on a free model for automated trading.
    • For Google models, Gemini API / Generative Language keys and Vertex AI Express keys can have different pricing, rate limits, and model availability for the same model. Treat the displayed catalog price as a guide and confirm the provider pricing page for the Google API surface your key is allowed to use.
    • Google Gemini API Gemma 4 models: Gemma 4 31B and Gemma 4 26B can be useful Google choices when your own Gemini API project shows them as available. VTX Macro routes Gemma 4 through the Gemini / Generative Language API because Vertex AI Express does not currently expose the Gemma 4 publisher-model endpoint for normal API-key calls.
      • A free Google AI Studio project currently shows about 1,500 requests per day for these Gemma 4 models. At the configured default loop interval of 60 seconds, one bot can use most of that daily request budget when each loop makes a single model call. Manual retries, extra testing, or a Review Model can push the project over the daily request limit.
      • In practice, default VTX Macro bot settings appear to run into Google AI Studio free-tier limits at around 5 active Gemma 4 bots total. For the best chance of stable operation, use one bot per Google AI Studio project and keep the total at 5 bots or fewer across the Google AI Studio account.
      • Among profiles whose Server Mode AI Trader is marked active, a profile counts toward the free-Google model limit only while its Main Model or Review Model is enabled. A Copy Trading-only profile with both models disabled does not use a model slot merely because an old Trader state is still marked active.
      • If you want the free-tier setup, do not add a credit card or enable billing on those Google AI Studio projects. Billing moves a project to a paid tier and changes the token/request limits; use a separate project for any paid Google API testing.
      • If multiple bots start hitting rate limits, stop all Gemma 4 bots for about 10 minutes, then restart no more than 5 bots total.
      • Google applies Gemini API rate limits per project, not per API key. Creating another key inside the same project does not multiply the daily request budget, and creating more projects, API keys, or Google accounts may not increase practical capacity. Google may associate related accounts or usage patterns when applying abuse and quota controls.
      • If you enable billing or your project is on a paid tier, the same Gemma 4 models may show different limits. Current AI Studio rate-limit pages have shown about 16K tokens per minute and 14.4K requests per day for Gemma 4 31B/26B. That is still usually one bot per project on default VTX settings, but only if the prompt stays below the token-per-minute limit. Larger prompts, more symbols/timeframes, longer lookbacks, shorter loop intervals, or a Review Model can hit the token limit before the daily request limit.
      • Review Model calls count separately from the primary trader call. If the reviewer uses the same Google project, it consumes the same request and token budgets as the main bot.
      • Always check Google AI Studio -> Rate Limit for the exact project and model before starting a long-running bot. Google can change limits, and your active account tier is the source of truth.
    • If the Models page shows - for a model's input or output price, VTX Macro does not have a safe per-token price for that model. For endpoint-required models, the provider may charge separately by hosted minute, hardware, replica, or reserved capacity instead of by tokens.
    • If a provider says a model is non-serverless or requires a dedicated endpoint, create or start that endpoint in the provider dashboard, then retry with the endpoint/model name the provider gives you.
  • Dynamic Reasoning Controls: Take control over how the AI "thinks" for compatible reasoning models.
    • Controls are provider-documented best effort and come from provider APIs or provider documentation. Some providers publish broad model-family controls, so a specific model may accept fewer choices than the AI page can show.
    • Advanced provider response details are handled automatically and kept out of normal AI Settings.
    • Leaving a reasoning control unselected means VTX Macro sends no value for that control, so the provider's own model default applies.
    • Explicit selections are sent to the provider as selected. If a provider rejects a combination, VTX Macro surfaces the provider error so you can clear the control so no value is selected/sent, or pick another supported setting and retry.
    • Some models are fixed reasoning or non-reasoning variants and intentionally expose no control unless the provider documents a configurable request parameter.
    • Effort Levels: Select documented provider effort values such as low, medium, high, or provider-specific values like max when the selected model supports them.
    • Thinking Budgets: Set strict token budget limits for models that support explicit thinking budgets to manage exactly how much computational effort the AI spends.
      • The -1 preset requests provider-managed adaptive budget behavior where supported.
      • Leaving all budget presets unselected sends no explicit budget override and uses provider default behavior.
    • Thinking Mode / Toggle Options: Some providers expose switches such as thinking enabled/disabled. These appear only when the provider documents them as user-configurable request parameters.
    • Anthropic adaptive thinking and Groq reasoning-output controls appear when documented for the model family. Lightning AI and xAI show no thinking-effort control unless their provider documentation adds a user-configurable thinking setting.
  • Cloud models are strictly filtered to a minimum system context window requirement of 16000 tokens.
    • Recommendation: Start with the configured default model and adjust based on your own latency, quality, and cost needs.
  • Main Model Enabled: Turn this off when you want the profile to stop AI-originated autonomous entries without disabling Review Model settings, Screener, or Copy Trading. The Main Model settings collapse when disabled and expand again when enabled.
  • Review Model Enabled: The Review Model settings also collapse when disabled and expand when enabled. Main Model, Review Model, and Screener Model use the same smooth panel transition while keeping each enable switch visible.
  • Cost Tracking: The panel shows raw model/source cost per run so you can budget before starting automation. It does not fold the flat trader-call fee into the displayed prompt/run cost.
    • Server Mode: Trader calls run on VTX Macro servers. This is the premium paid runtime. Qualifying calls are billed with the configured VTX Macro platform fee of $0.0025, but the displayed run cost stays raw.
    • Client Mode: VTX Macro is free forever and does not charge a platform fee. Your browser or desktop app sends model requests directly from your device, so any external provider costs come from the provider account or local runtime you choose, not from a VTX Macro client-mode fee.
  • Use My Averages: Toggle this to see costs based on your specific usage history rather than global platform averages.

Screener Model

The Screener Model panel controls the profile's symbol-discovery runtime. Use it when you want VTX Macro to rank possible symbols before you decide what to inspect or trade.

  • Enable Screener: Arms the profile-scoped Screener schedule. Screener runs only while AI Trader is running for that profile. Stopping AI Trader also stops active Screener work, while leaving this saved setting enabled for the next AI Trader start. Completed Screener runs can automatically switch that profile's AI trading symbols when a candidate passes the Symbol Assignment rules. The Screener page is monitoring-only; it does not expose separate Start/Stop controls.
  • Model: Chooses the model used to score candidate symbols. Its full model dropdown uses the same open, close, filter, and sort motion as the Main and Review model dropdowns. Local AI and WebGPU choices follow the same Client Mode requirements as the main model.
  • Exchange / Universe: Chooses the single universe scanned by each run.
  • Run Schedule and Limits: Controls how often runs start, how many full volume-ranked passes are made, and how many candidates are evaluated per run.
  • Candidates Per Run: Sets the discovery slice. The run can expand beyond this value when current AI trading symbols need to be included for comparison.
  • Symbol Assignment: Guarded automation that controls when active Screener runs may update the profile's AI trading symbols. Its controls set the minimum candidate score, required edge over a replaced symbol, duplicate-symbol allowance across your active profiles, and number of trading-symbol slots Screener may manage.
  • Prompts and Variables: Lets you edit Screener-specific prompts and select which Main model variables are included. Screener also adds its own candidate volume/rank context.

The Screener does not place trades, change leverage, or send BUY/SELL/HOLD instructions. Symbol assignment uses only completed Screener scores from the same run; it does not use Trade-page tradability or Main/Review model trading output. Use the Screener page to review ranked results and recent assignment history.

Copy Trading

The Copy Trading panel lets a profile mirror executed Hyperliquid fills from a VTX bot or any Hyperliquid wallet address.

  • Copy Trading is disabled by default and does not start live copying just because you select a source from Leaderboard or Analytics.
  • Source selection is profile-scoped. Leaderboard and Analytics Copy Trades actions update the active profile's Copy Trading source and recent-source list without changing the current page.
  • Account-size scaling is the default. VTX uses source and destination account value when both values are fresh and valid; if either value is missing, stale, zero, or invalid, the copy intent is skipped instead of silently resizing.
  • Fixed multiplier scaling can scale below or above 1.0 within configured bounds.
  • Copy Trading follows the profile's existing Server Mode or Client Mode setting. There is no separate Copy Trading runtime-mode toggle.
  • Copy Trading can run with Main Model and Review Model both disabled. In that copy-only setup, an old active Server Mode Trader state does not consume a free-Google model slot.
  • Copy Trading mirrors observed executed fills only. It does not copy unfilled resting source orders before they fill.
  • Server Mode Copy Trading charges $0.25 per executed copied fill against your VTX credit balance. A copied fill counts whether it opens, adds, reduces, closes, or flips a position; it is not based on winning or losing trades. Client Mode Copy Trading remains free because execution happens on your device. This copy-trading fill fee is separate from AI prompt/model cost estimates and is not included in cost-per-prompt displays.
  • If the Review Model is enabled, copied trades can be reviewed before execution. The review receives the same context as normal Trader review, with the proposed copied trade replacing the main model's decision, so CR rows include tradability and full reasoning.
  • AI snapshots do not import or enable live Copy Trading source settings.

Local AI model selection

  • Local AI is the recommended approach for high-performance offline inference. If you want larger context windows, higher speeds, and stability for local models, run them via a Local AI server (e.g., LM Studio, Ollama) rather than WebGPU.
  • Local AI models are available only when the profile is configured for Client Mode.
  • The System page tests the Local AI endpoint and refreshes the model list using the Local AI server-type toggle:
    • OpenAI-compatible mode: reads GET /v1/models
    • Native Ollama mode: reads GET /api/tags
  • Use the AI page model selectors to choose Local AI models for main and review roles after Test & Refresh has loaded the endpoint's models.
  • Click Apply on System to save endpoint access only: base URL, API key storage, sync setting, and server type.
  • For Ollama, keep the full returned model tag, such as :latest, if it appears in GET /v1/models.
  • When a Local AI model is selected, VTX Macro does not allow automatic cloud fallback takeover. The local model remains authoritative for Client Mode runtime.
  • Recommended Base URLs:
    • LM Studio / llmster: http://127.0.0.1:1234/v1
    • Ollama: http://127.0.0.1:11434/v1
  • The Use Ollama native API toggle changes only the request contract:
    • Off: VTX uses /v1/chat/completions and other OpenAI-compatible behavior.
    • On: VTX uses native Ollama /api/chat behavior.

WebGPU model selection

  • WebGPU runs AI models natively inside your browser using your local device's graphics card. The synced catalog is filtered to models with at least 4000 tokens of inferred context window.
  • What this means in practice: The 4000 value is a catalog floor, not a browser-side maximum. Actual usable prompt size still depends on the selected model, browser memory limits, and your device's available VRAM.
  • Use the System page to pick a WebGPU model, then click Apply to save it and switch the active AI page model to that WebGPU selection.
  • The WebGPU picker can sort by model, source, and context window, and can filter to models already downloaded in this browser.
  • To avoid browser tab crashes, we strongly recommend these pre-compiled models (-q4f16_1-MLC or -q4f32_1-MLC quantization) based on your hardware:
    • Balanced / Recommended (3–4GB VRAM): Llama-3.2-3B-Instruct-q4f16_1-MLC or Qwen2.5-3B-Instruct-q4f16_1-MLC. Fit comfortably in most modern browsers.
    • Maximum Capability (6–8GB+ VRAM): Llama-3.1-8B-Instruct-q4f16_1-MLC or DeepSeek-R1-Distill-Llama-8B-q4f16_1-MLC. Only use these with a dedicated modern desktop GPU (NVIDIA RTX or Apple Silicon M-series).
    • Maximum Speed / Low VRAM (<2GB VRAM): Llama-3.2-1B-Instruct-q4f16_1-MLC or Qwen2.5-1.5B-Instruct-q4f16_1-MLC. Best for older laptops or integrated graphics.
  • Tip: If a model fails to initialize, text generation freezes, or you are running into context limits due to large market data payloads, you must switch to a standalone Local AI server instead of WebGPU.

Market Analysis Scope

Define the data the AI "sees" when making a decision.

  • Trading Symbols: The assets the AI is allowed to monitor and trade (e.g., BTC, ETH, SOL).
  • Timeframes: The chart intervals analyzed (e.g., 5m, 1h, 4h).
  • Lookback: How many past candles are sent to the model for each timeframe. For example, the default 1h lookback is 48 candles.
  • Technical Indicators: Enabling these pre-calculates values like RSI, MACD, or Bollinger Bands and feeds them to the AI numerically.
  • Tradability Score: Each Trader decision includes a model-authored integer score from 1 (lowest) to 10 (highest). If your Main System Prompt defines Tradability or explicitly makes it a decision constraint, the model should follow that instruction; otherwise the score is based on model judgment and remains advisory. When review is enabled, the Review Model receives those Strategy Agent rules and should preserve their explicit Tradability constraints in its final decision. Tradability never replaces the required decision, units, or reasoning, and hard account, risk, capacity, and execution constraints always take precedence. A high score with HOLD, such as HOLD - 8, can still be correct because a high score permits but does not force a trade.

News Context

The News Context panel controls market-news headlines that can be included in prompts that use the {news} variable.

  • Max Headlines: Sets the maximum number of recent headlines sent to the AI.
  • Timespan: Sets how far back the news context can look, from 1 hour through 7 days. The default is 24 hours.
  • Source Filter: Selects which news sources/categories are eligible from Benzinga's returned channels and tags. Configured topic queries can retrieve oil or geopolitical coverage whose key terms appear in the article body rather than its headline, but they do not create separate categories.
  • No source selected: Includes all fresh market-news headlines that pass the normal limits.
  • Reset: Restores the default News Context settings for the profile.

News headlines and compact context snippets are advisory. Snippets help expose relevant details that Benzinga places in a general market-wrap body rather than its headline. News should not replace candles, account state, performance guardrails, or calendar risk controls.

Trading Limits & Frequency

Control the pace and size of the automation.

  • Loop Interval: How often the AI runs its analysis (e.g., every 60 seconds by default).
  • Trade Amount: The size (in USDC) of each position opened by the AI.
  • Max Trades: Hard limits to prevent over-exposure:
    • Global: Maximum total absolute exposure units across all assets.
    • Per Asset: Maximum absolute exposure units for one symbol.
    • Per Cycle: Shared BUY/SELL order-unit budget across all symbols in one decision cycle.

Safe Mode (Risk Management)

Automated safety nets that apply to every AI trade.

  • Tradability: An application-side filter with a master switch and two independent minimums.
    • Open Position: Rejects an initial position when the final 1-10 Tradability score is below its enabled minimum.
    • Increase Position: Rejects an addition to existing exposure when the final score is below its enabled minimum.
    • Reductions, closes, and position flips are never blocked by these minimums. The filter runs after the model responds, so it is not added to the model prompt.
    • A rejected attempt remains recorded as the model's original BUY or SELL decision. The Trade page shows Blocked by Tradability with the score and applicable minimum, and no order is placed.
  • Stop Loss / Take Profit: Automatically attach TP/SL orders to every entry.
    • Fixed: Leaves the exchange-side stop at its original percentage or USDC distance.
    • Trailing: On each AI HOLD cycle, ratchets the exchange-side stop behind favorable price movement using the same configured distance. It never moves the stop backward or loosens protection.
    • Trailing is mechanical application behavior, not an AI-suggested target. Client Mode must remain online to move the stop; if it goes offline, the latest exchange-side stop remains active.
  • Performance Guardrails: Advanced risk controls (like Max Drawdown %) that monitor the AI's trading behavior and halt trading if your current market equity drops from its peak beyond configured thresholds. For HIP-3 markets, market equity follows the selected DEX-specific Perps balance. See Advanced Features for details.

Operations & Scheduling

  • Killswitch: An emergency circuit breaker.
    • Threshold: If your current market equity drops from its highest peak by X% within your configured look-back window (e.g., Y hours), the system halts.
    • Action: Optionally close all open positions immediately upon trigger.
    • Runtime ownership: Server Mode monitors and acts from the VTX server. Client Mode monitors live equity and performs any configured close directly in the active browser or desktop runtime; it is not monitored after that client runtime closes.
  • Schedule: Restrict trading to specific hours (e.g., 09:00 - 16:00 London Time).
  • Calendar Filters: Prevent trading during high-impact news events (e.g., FOMC, CPI) by defining a "no-trade zone" buffer (e.g., 60 mins before, 30 mins after).

Prompts (The "Persona")

You have full access to the prompt text sent to the AI.

  • Prompt Data: Server and Client Mode both render unavailable JSON values as "-" in model-facing variables.
  • System Prompt: Defines the AI's core identity and rules. (e.g., "You are a conservative macro trader...").
  • User Prompt: The template used to present market data.
  • Advanced: You can edit these to enforce specific behaviors, like "Never trade against the 1-hour trend" or "Focus heavily on volume anomalies."

Prompt Variables Reference

Reference for the placeholder variables available when customizing the primary AI trader and Review Model prompt templates.

VariableUsed InDescription
account_statustrading_user_promptAccount equity, balances, margin, and fee-rate context.
behavior_statetrading_user_promptBehavior tracking fields such as recency, age, and add-count by symbol.
calendartrading_user_promptUpcoming/active macro event summary and risk windows.
candlestrading_user_promptSerialized multi-timeframe candle stream and indicators for selected symbols.
current_timetrading_user_promptCurrent analysis timestamp in user-local time.
guidancetrading_user_promptLegacy alias for market regime context
intervaltrading_user_promptTrading interval guidance line injected from runtime settings.
leveragetrading_user_promptConfigured leverage cap provided to the strategy prompt.
market_regimetrading_user_promptMarket regime metrics such as ADX/CHOP/ATR/RVOL by timeframe.
market_statstrading_user_promptDerived market statistics block computed from candle history.
newstrading_user_promptBounded market-news headline context.
performancetrading_user_promptRolling performance metrics summary used for guardrails.
positionstrading_user_promptOpen positions snapshot used for add/reduce/close decisions.
primary_decision_jsonreview_user_promptPrimary model decision JSON to be reviewed and validated.
primary_modelreview_user_promptModel id/name used by the primary strategy decision.
primary_system_promptreview_user_promptExact system prompt used by the primary strategy model.
primary_user_promptreview_user_promptExact user prompt (market context) sent to the primary model.
sizetrading_user_promptPer-unit trade size in USDC for the generated decision payload.

Review Model (Dual-Layer Analysis)

The Review Model acts as a "second opinion" for your AI trader. It allows you to configure a separate, potentially more powerful or specialized AI model to critique and validate the primary model's trading decisions before they are executed.

How It Works

  1. Primary Analysis: The main AI model analyzes the market and proposes a trade (e.g., "BUY BTC").
  2. Trigger Check: The system checks if the proposed decision matches your Review Triggers. Configured default: BUY, SELL.
  3. Review Process: If triggered, the Review Model receives the primary model's reasoning and the same market data. It acts as a risk manager or senior trader.
  4. Final Verdict: The Review Model can:
    • Confirm the trade.
    • Reject the trade (turning it into a "HOLD").
    • Modify the trade (e.g., reduce the size).

Both the primary model and Review Model provide their own tradability score for each symbol, as an integer from 1 (lowest) to 10 (highest). The primary model should follow any Tradability definition or explicit Tradability-based decision constraint in its Main System Prompt. The Review Model receives those Strategy Agent rules and should preserve their explicit Tradability constraints along with any additional constraint in its Review System Prompt; without an explicit constraint, its score remains advisory. The final score shown in decision history comes from the accepted final decision after review or fallback handling. Tradability never replaces the required decision, units, or reasoning, and hard account, risk, capacity, and execution constraints always take precedence.

Note on Client-Side Execution: The robust dual-stage "Reviewer" architecture natively runs even in local/client-side execution modes, ensuring strict trading safety across all executing environments.

Model Label Semantics

  • + means a Review Model was used (primary + reviewer).
  • -> means a fallback model was used (requested -> actual).
  • Both can appear together when fallback and review both occur in the same run.

Configuration

To enable the Review Model, navigate to the Advanced or AI Settings panel.

Core Settings

  • Enable Review Model: Toggles the feature on/off.
  • Review Model: Select the specific LLM to use for reviews.
    • Recommendation: Use a capable reasoning model from a provider you trust for the review layer, even if your primary model is a faster or cheaper chat model.
  • Triggers: Choose which decisions trigger a review.
    • Configured default: BUY, SELL.

Parameters

  • Temperature: Controls the creativity of the reviewer (default: 1.0 for strict logic).
  • Max Tokens: Limit the length of the review output.
  • Timeout: Maximum time in seconds to wait for the review (default: 90s).

Custom Prompts

Just like the primary trader, the Review Model has its own customizable prompts.

System Prompt

Defines the persona of the reviewer.

  • The configured default prompt is loaded from the current app configuration and can be edited.

User Prompt

The template for the data sent to the reviewer. It typically includes:

  • The Primary Decision (BUY/SELL/HOLD).
  • The Primary Reasoning (Why the first model wanted to trade).
  • The Market Data (Price, indicators, etc.).

Cost Implications

Using a Review Model essentially doubles the API calls for triggered trades.

  • If you review every decision, your costs will double.
  • If you only review entry decisions and the bot mostly holds, the extra cost is minimal.

Screener

The Screener is a symbol-discovery tool. It scans one configured exchange or universe, evaluates each eligible symbol in volume order, and records a model-authored tradability score with reasoning. Tradability is an integer from 1 (lowest) to 10 (highest); if your prompts provide a tradability definition, the model should use it.

Screener does not place trades, change leverage, size orders, or send BUY/SELL/HOLD execution instructions. When Enable Screener is active on the AI page, completed Screener runs can automatically update that profile's AI trading symbols, using Screener scores from that same run only.

Where To Configure It

Open the AI page and use the Screener Model panel.

Core settings:

  • Enable Screener: Arms the Screener schedule. Screener runs only while AI Trader is running for the same profile. Stopping AI Trader stops any active Screener work; the saved Screener setting stays enabled and becomes eligible to run again after AI Trader starts. When Screener is disabled, it does not run and the panel collapses. Completed runs can automatically switch that profile's AI trading symbols when a candidate passes the Symbol Assignment rules. Default state: off.
  • Screener Model: Selects the model used for symbol evaluation.
  • Exchange / Universe: Chooses the single exchange/universe scanned by each run.
  • Run Schedule: Controls how often a full run starts.
  • Symbol-List Loops: Controls how many full passes over the volume-ranked symbol list happen per run.
  • Candidates Per Run: Controls the volume-ranked discovery slice. Current AI trading symbols are always included when they resolve inside the selected universe, so a run may evaluate more symbols than this setting.
  • Symbol Assignment: Guarded automation for updating profile trading symbols after a completed run while Screener is enabled. Set the minimum Screener score, minimum edge over replaced symbols, maximum same-account profiles per symbol, and assignment slot count.
  • Candidate evaluations run back-to-back with no intentional per-symbol delay.
  • Screener Prompts: System and user prompt text for Screener-only evaluation.
  • Screener Variables: A selectable subset of the Main model prompt variables, rendered in the same canonical order as the Main model. Screener also adds the read-only screener_volume_context variable for the current candidate's volume rank and exchange context.

Screener Page

Open the Screener page to monitor the runtime.

The page shows:

  • Current enabled and runtime status.
  • Current and next candidate progress, current run time, current symbol time, next-run countdown, last symbol time/cost/tokens, and last run time/cost/tokens.
  • Run counters use three dot-separated values: prompts, symbols, and loops. For example, 125/125 · 25/25 · 5/5 means 125 of 125 prompt calls succeeded, 25 of 25 symbols were covered, and 5 of 5 symbol-list loops were completed.
  • Run counters and results use the effective queue, including current AI trading symbols that were added beyond Candidates Per Run.
  • Evaluated symbols sorted by displayed tradability descending, then recent evaluation time, then volume rank. Single-loop runs show the latest score; multi-loop runs show the average score plus spread, such as 7.0 ±0.8.
  • Current AI trading symbols are shown in bold in the evaluated-symbol list.
  • The symbol-assignment panel appears near the run summary while Screener is enabled. It shows a scrollable history table with assignment date/time, starting symbols, and ending symbols.
  • Full reasoning for the selected/latest candidate.
  • Recorded raw prompt and response context for your profile.

The Screener page is monitoring-only and does not expose separate Start or Stop controls. Enable Screener on AI Configuration arms the schedule, while AI Trader remains the master runtime control: Screener cannot start or continue after AI Trader stops.

Execution Mode

In Server Mode, VTX Macro servers run the Screener loop and model calls while AI Trader is running.

In Client Mode, your browser or desktop app runs Screener execution while AI Trader is running. VTX Macro prepares the candidate list and records status/results, but model-provider calls run from your active app session using your device-local provider keys. If AI Trader is running but no Screener owner is active, the page shows that it is waiting for a runtime owner instead of silently falling back to Server Mode.

Screener model calls are additional provider calls in both modes. Client Mode uses your local device/account provider keys and does not add a VTX Macro platform fee. Server Mode uses the configured server-side model/provider path and qualifying calls can use the same configured server-mode platform fee as other server-side trader model calls.

Data Scope

Screener state, runs, candidate evaluations, and assignment history are scoped to the authenticated user and active profile. Scan history is retained according to the configured Screener retention settings.

Symbol Assignment

When Screener is enabled on the AI page, assignment runs after Screener runs complete. If a candidate qualifies, VTX Macro writes the new symbol list back to that same profile's AI trading symbols. That means the AI Trader for that profile may evaluate different symbols on later runs.

Assignment controls:

  • Minimum Assignment Tradability: The candidate must reach this same-run Screener score before it can be assigned. Default: 7. Range: 1-10.

  • Minimum Assignment Edge: The candidate must beat the replaced current symbol by at least this many score points. Default: 1. Range: 0-9. The minimum value allows equal-score replacements when the other safeguards pass.

  • Max Profiles Per Symbol: Limits how many active profiles under the same account may use the same symbol, including the current profile. Default: 1. Range: 1-10.

  • Minimum Symbols: Controls how many profile trading symbols Screener should keep even when same-run scores are weak. Default: 1. Range: 1-3.

  • Maximum Symbols: Controls how many profile trading symbols Screener may add or manage. Default: 1. Range: 1-3. The app's maximum trading-symbol limit still applies.

  • Reset Symbol Assignment: Restores only the Symbol Assignment controls to their default values.

  • Assignment compares candidate symbols and current AI trading symbols using only scores from the completed Screener run.

  • Multi-loop runs use the average Screener score from that run. Single-loop runs use the latest completed score from that run.

  • Trade-page tradability, Main model output, Review model output, and trading prompt scores are not used.

  • If your trading symbols changed after the run started, assignment is skipped so an older run cannot overwrite newer changes.

  • Symbols with open positions can prevent assignment from removing them.

  • Assignment still respects the app's maximum trading-symbol limit.

  • The Screener page shows recent assignment changes with date, start symbol metadata, end symbol metadata, tradability, and 24h volume. Runs with no symbol change are hidden by default; use the panel checkbox to include them. The table has search, sort controls, and loads additional rows as you scroll inside the panel.

VTX Insights

VTX Insights connects agent apps to bot trade-chain investigations and approved actions on your profiles. It links settings and decision context to policy checks, reasoning, executions, fills, positions, and PnL.

Open VTX Insights for setup, examples, capabilities, troubleshooting, and connection guidance.

Codex adds a trade-chain skill. Results distinguish retained, same-decision repaired, recomputed, and unavailable evidence. Replay reports each selected profile; excursions separate population coverage from exact economics. These run on request, not as an always-running simulator or exact alternate-PnL forecast.

Public evidence can include another user's public profile, but regular users can change only profiles they own. Private data and actions require VTX sign-in and matching approval.

Stop the runtime before changing exchange credentials.

Insights is the single source for setup. Use VTX Help for other guidance or Telegram for community help.

Platform Features & Configuration

The following section covers the core platform settings, defaults, and analysis tools available in VTX Macro.

Global Platform Defaults

The following values represent the server-side default configuration. These settings are used as the baseline for the AI Trader unless overridden by your personal strategy settings.

AI Execution

  • Default Model: gemma-4-31b-it
  • Max Tokens: 8192
  • Loop Interval: 60s
  • Timeout: 90s
  • Trade Amount: $20

Trading Safety & Defaults

  • Max Units (Global): 10
  • Max Units Per Asset: 10
  • Max Units Per Cycle: 10
  • Max Slippage: 8.0%
  • Leverage: 2x (Max 50x)
  • Margin Mode: Cross

Small Account Optimization

For accounts with small balances ($10-50), Isolated Margin operations can sometimes fail due to exchange-level dust limits and collateral fragmentation. To ensure your leverage updates always succeed, the system employs an Auto-Recovery mechanism: If an Isolated Margin update fails due to insufficient margin/balance, the system automatically retries the request using Cross Margin. This ensures you can always adjust your leverage without manual intervention, even on small accounts.

Desktop App

VTX Macro Desktop gives Windows, macOS, and Linux users a native app window for the same VTX Macro experience available in the browser.

  • The desktop installer is free. Account access and billing stay tied to your normal VTX Macro login.
  • In a browser, open Download to install VTX Macro Desktop or continue using the web app.
  • Inside VTX Macro Desktop, the Download navigation item is hidden because you are already using the installed app.
  • To sign in on desktop, choose Continue in browser on the desktop login screen. After you authorize the request in your browser, return to VTX Macro Desktop to continue.
  • The desktop app uses the same Trade, AI, Screener, System, Security, History, Billing, and Help pages as the browser.
  • Desktop-only behavior, such as Start at login, Start minimized, and Close to tray, is available from the System page while you are using the desktop app.
  • Client Mode runtimes are owned per profile. Take Over transfers the current profile's runtime to the current window, while Take Over All transfers the other active Client Mode profile runtimes to the same window or desktop app.

Snapshots & Sharing

Snapshots allow you to save your entire AI strategy configuration (Model, Prompts, Parameters) into a reusable profile. This is useful for switching between different trading personalities (e.g., "Conservative Scalper" vs "Aggressive Trend Follower").

How Snapshots Work

  • Save: Click the "Save" icon in the Snapshot menu to store your current settings.
  • Match: The system automatically detects if your current settings match an existing snapshot or the system defaults.
  • Sync: When a matching snapshot is found, it is automatically selected, helping you keep track of your active strategy.

Sharing & Importing

You can share your strategy updates with other users or discover successful strategies from the community.

  1. Leaderboard: Browse the Leaderboard to find top-performing users. Click the Copy icon next to a trader's name to instantly import their latest snapshot.
  2. Direct Import: Alternatively, search for a specific user by their @handle or Wallet Address in the "Copy User" menu on the AI page.
  3. Activating: After importing, the snapshot appears in your library. Select it, then click the Reset button (counter-clockwise arrow) in relevant panels (e.g., Model, Prompts) to apply the settings.
  4. Modifying: Once loaded, you can tweak the settings to fit your needs and save it as your own version.

Link Previews

Public Analytics, Trade, Changelog, and Leaderboard links can show a moment-in-time image of the actual public page when a social or messaging service first loads the link. Analytics links keep the selected timeframe and explicitly identify scope=profile or scope=account; Changelog links use the same explicit scope names, and Leaderboard keeps its timeframe and page. Capture runs without a signed-in session, so it never includes private account state. If the page is unavailable, capture capacity is temporarily full, or the page does not produce a useful public preview, VTX Macro shows the transparent VTX favicon instead. LinkedIn, Telegram, and similar services may cache the first preview they fetch.

Decision History

The History page provides a complete, searchable log of all AI trading decisions and analysis. This is your primary tool for auditing the AI's behavior over time, including both executed trades and "HOLD" decisions.

Features & Filtering

  • Search Reasoning: Quickly find specific decisions by searching for keywords within the AI's reasoning text (e.g., "RSI", "bullish", "liquidation").
  • Timeframe: Filter decisions by the last 24 hours, 7 days, 30 days, 90 days, 365 days, or view all history.
  • Decisions: Toggle between BUY, SELL, and HOLD decisions to isolate specific actions.
  • Model & Overrides:
    • Filter by the specific AI model used for the decision.
    • Check Review to see decisions that were processed by the Review Model.
    • Check Fallback to see decisions where the primary model failed and the Fallback Model took over.
  • Units: Use the slider to filter decisions based on the number of units traded.
  • Blocked: Select Blocked to audit decisions rejected by the Tradability control. The Prompts count updates to the filtered total.

History Feed

The new notification follows the filters currently shown on the page. Incoming decisions that do not match the selected timeframe, decision, model, Review, Fallback, Units, Blocked, or search filters do not increase the notification. Select the notification to refresh the filtered feed.

Each entry in the history feed displays:

  • Timestamp & Model: When the decision was made and which model made it.
  • Latency & Cost: The time it took for the AI to respond and the cost of the prompt.
  • Reasoning: The full natural-language explanation generated by the AI, which includes the final decision.
  • Provider Reasoning Trace: When a provider returns a separate reasoning trace and trace capture is enabled, VTX Macro stores it with the decision, shows it automatically in History and Trade Analysis, and keeps it available for the full retained history. Providers do not guarantee a trace on every response.
  • Tradability: When available, decision headers append the model's 1-10 tradability score, such as SOL: HOLD - 7 or BTC: BUY (2 units) - 8. Older rows without the score still display normally.
  • Blocked Outcomes: If VTX rejected an Open or Add action, the entry keeps the original model decision and shows the score, applicable minimum, and confirmation that no order was placed.

Clicking on any history card that contains an analysis key will open the detailed Trade Analysis page for that specific decision.

Trade Analysis & Decision Transparency

VTX Macro provides complete transparency into every action the AI takes. The Trade Analysis page allows you to inspect the exact "thought process" behind any AI decision, whether it resulted in a trade or a "HOLD".

Accessing Analysis

  • Trade History: Click the Sparkles icon next to the timestamp on any trade row.
  • AI Logs: Click on any log entry in the AI Activity feed to view the decision context.

Decision Context

  • Trade Details: The precise execution price, size, fees, and PnL for the resulting trade (if execution occurred).
  • Model Info: The specific AI model used, response latency, and cost.
  • Reasoning: The full natural-language explanation generated by the AI (e.g., "Holding because RSI is overbought").
  • Tradability: The model-authored integer score from 1 (lowest) to 10 (highest). If the model's system prompt defines Tradability or explicitly makes it a decision constraint, the model should follow that instruction; otherwise the score is useful advisory context. Tradability never replaces the required decision, units, or reasoning, and hard account, risk, capacity, and execution constraints always take precedence.
  • Technical Inspection: AI Configuration, the recorded System Prompt and raw User Prompt, and the recorded Last Execution Context used for that decision. These non-secret decision inputs are part of the public Trade Analysis record.

Interactive Chat

Every analysis page includes a dedicated Chat Interface. This allows you to interact with the specific historical context of that decision.

  • Ask Follow-ups: "Why did you think the trend was bearish here?"
  • Challenge Decisions: "Given the RSI was 30, shouldn't you have bought?"
  • Memory: The AI replies using the PAST state data it had at that exact moment.
  • Call Details: Each new assistant reply keeps its own inference-call details, including retries and token availability, attached to that exact reply.

Inference-call details and retained provider response/reasoning content are part of the public decision record when they were captured.

Sharing Decisions

Every Trade Analysis page is public. Click Share to copy its canonical /analysis/{profile-handle}/{decision-id} link. The profile handle and decision ID in that one link make it useful for another person or a Codex session without a separate share token.

Analytics & Performance

The Analytics page provides a comprehensive dashboard to visualize and understand your trading performance over time.

When both views are available, the profile tab shows only the selected profile and the account tab combines the account's profiles. Analytics keeps that choice in the URL as scope=profile or scope=account, including links copied with the Share button and links opened between Analytics and Changelog.

Key Metrics

  • Prompts Processed: Completed AI trading decisions for the selected period. Provider, network, market-data, and legacy failure records remain available for troubleshooting but do not increase this total.
  • Total PnL: Your net profit or loss for the selected period.
  • Win Rate: The percentage of profitable trades.
  • Profit Factor: The ratio of Total Net Profit to Total Net Loss (> 1.0 is profitable).
  • Trades: Total number of executed trades.
  • Volume: Total trading volume generated.
  • Avg Trade: Average PnL per trade.
  • Fees Paid: Total trading fees incurred.

Visualizations

  • Equity Curve: A chart showing the growth (or decline) of your account balance over time. This helps visualize consistency and drawdown.
  • PnL Distribution: A bar chart (histogram) showing the distribution of your trade results. It helps identify if your profits come from many small wins or fewer large wins, and how your losses are distributed.
  • Advanced Stats: Click the Sigma button in the Analytics header to open a deeper stats panel for the current filters. It summarizes net return per closed trade, including mean, standard deviation, median, percentile range, min/max, skew, tail ratio, average win/loss returns, payoff ratio, downside deviation, return buckets, sigma bands, and 0.25 sigma resolution inside the central -1 to +1 sigma range. The panel follows the same timeframe and profile/account selection as the rest of Analytics.

Public Profiles

Every user has a public analytics profile accessible via their username or wallet address (e.g., /analytics/@username). You can view transparency insights and performance history for any trader on the platform.

Tax

The Tax page provides profile-scoped tax-year reporting for your trading activity.

Generating Documents

  • Tax Year: Isolate all trade data to a specific, complete calendar year.
  • Timezone Selection: The platform uses your designated timezone to calculate exact end-of-year boundaries, ensuring no offset trades bleed into the wrong tax year.
  • CSV Export: Produce a clean, formatted CSV download with FIFO tax lots, execution prices, sizes, trading fees, funding, ledger activity, and realized gains/losses for the selected period.

Billing & Payments

VTX Macro operates on a subscription or usage-based model. All payments are securely processed via Stripe. You can manage your subscription, view invoices, and update payment methods on the Billing page. Ensure your account is funded or has an active subscription to maintain uninterrupted access to AI trading features.

Usage & Model Pricing

The Models page shows the public model catalog, provider count, and token prices. When your selected profile is in Server Mode, it also shows the flat trader call fee used by server-side trader and Screener model calls. The Billing page is where logged-in users manage credits, subscriptions, invoices, and payment methods.

Server Mode vs. Client Mode Fees

  • Server Mode: VTX Macro runs trader and Screener model calls on VTX servers. This is the premium paid runtime and bills the configured platform fee of $0.0025 per qualifying call. Per-prompt and per-run cost displays remain raw model/source cost and do not include the flat fee.
  • Client Mode: VTX Macro is free forever and never charges a platform fee for browser- or desktop-app-owned trader and Screener model calls. Your browser or desktop app owns the runtime and sends model requests from your device. If you use a paid external BYOK provider, that provider may still bill your provider account directly; VTX Macro does not add a client-mode fee.

The model pricing table shows per-token prices only when VTX Macro has a safe serverless or pay-as-you-go token price for that exact provider model. A - price does not mean the model is free; it means the model may be unpriced, provider-billed through a dedicated endpoint, or billed through another unit such as hosted minutes, hardware, replicas, images, audio, video, or reserved capacity.

Models listed with both $0.00 input and $0.00 output are treated as free by the app's model filters only when both token prices are confirmed as zero. Free models can be useful for evaluation, but they may have lower reliability, weaker performance, stricter rate limits, or changing availability compared with paid models. If you use BYOK providers, review the provider's current terms and free-tier limits before depending on a free model for trading automation.

Leaderboard & Rankings

The Leaderboard ranks users based on their trading performance across multiple timeframes (24h, 7d, 30d, All Time). To provide a complete and accurate picture of a trader's current standing, the platform's performance metrics are calculated holistically.

ROI and PnL Calculations

  • Total PnL: The Profit and Loss (PnL) displayed on the leaderboard is the sum of both Realized and Unrealized PnL.
    • Realized PnL: Profits or losses from historically closed positions.
    • Unrealized PnL: Current floating profits or losses from active, open positions.
  • ROI (Return on Investment): The ROI percentage is calculated using the net PnL (Realized + Unrealized) relative to the starting account balance for the given timeframe, adjusted for deposits and withdrawals. This ensures that holding open positions (whether in profit or drawdown) is accurately reflected in a trader's rank and prevents artificial manipulation of stats by hiding unrealized losses.
  • Trades & Volume: The leaderboard also displays the total number of executed trades and total trading volume generated during the timeframe.

Advanced Strategies & Risk Management

This section covers advanced configuration for scaling, market context, and event-based risk controls.

Multi-Trade Execution & Scaling

The AI Trader supports advanced position management strategies, allowing it to scale in and out of positions. This behavior is controlled by three key settings in the AI page:

Max Units (Global)

Limits the total absolute exposure units held across all selected assets.

  • Prevents aggregate exposure from growing beyond the configured capacity.
  • Reaching the limit blocks additional exposure. Reducing, closing, or reversing without increasing absolute exposure remains available, subject to the cycle budget.
  • Example: With a global limit of 10, positions across all assets may use at most 10 exposure units in total.

Max Units Per Asset

Controls the maximum absolute exposure units the AI can hold for one asset.

  • Allows Dollar Cost Averaging (DCA).
  • Stops additional exposure in that asset when its limit is reached.
  • Example: Set to 5 → AI can hold up to 5 separate entries of BTC.

Max Units Per Cycle

Controls the total BUY/SELL order units the AI may execute across all symbols in one decision cycle.

  • Acts as a "speed limit".
  • Higher values allow faster entry, reduction, closing, or reversal.
  • units is the order quantity to execute now, not the desired final position size.
  • Example: Set to 2 → the cycle may execute BUY 2 for one asset, or BUY 1 for one asset and SELL 1 for another.

For an open position, {behavior_state} also reports a compact last risk-increase boundary when it can be derived from the current campaign's fills. ri.tf is the shortest configured candle timeframe, ri.cb is the latest fully closed candle end time at the entry or add, and ri.nc counts later fully closed candles. Reductions do not move it, a direction flip starts a new campaign, and flat positions omit it. This is informational context for the AI—not a VTX order block—and ri.nc > 0 does not by itself confirm a setup or authorize another add.

AI candle context keeps fully closed rows separate from a current live row. When a live row is unavailable, both that field and its format guidance are omitted from the model prompt.

Strategy Examples
  • Slow Accumulation: Set Max Units Per Asset to 10 and Max Units Per Cycle to 1. The AI can change positions by at most 1 total BUY/SELL unit per cycle.
  • Faster Trading: Set Max Units Per Asset to 3 and Max Units Per Cycle to 3. The AI can move one asset from flat to its full 3-unit capacity in one cycle if the signal is strong.

Market Regime & Performance Guardrails

The system acts as a real-time coach and risk manager for the AI. It analyzes both your account's trading habits (Performance) and the current market state (Regime) to inject context directly into the AI's prompt via two key variables: {performance} and {market_regime}.

Performance Panel ({performance})

The Performance Panel monitors HOW the AI is trading to prevent inefficient behavior. It provides a profile-level view of the trader's recent actions over two distinct time horizons: Short-Term (e.g., 6h) and Long-Term (e.g., 24h). This data is injected into the prompt via the {performance} variable.

  • Directional Flip Rate: Detects rapid direction changes on the same market, such as BTC Long -> BTC Short. Activity in another market cannot create a flip. Short-Term and Long-Term each use their own Flip Window, so changing one does not change the other.
  • Median Hold Time: Ensures trades are given time to play out. Detects "scalping noise" where the AI exits before a thesis can mature.
  • Fee to Equity % (Fee Burn): Calculates the total trading fees paid as a percentage of your total account equity over the rolling window. If the strategy is churning and burning capital on fees, it forces a slowdown to preserve capital. (Note: The system uses an institutional-grade FIFO matching engine to accurately track roundtrip trades, partial fills, and complex scaling in/out strategies for all performance metrics).
  • Max Drawdown %: Acts as a critical safety tripwire. It uses a Peak-to-Current calculation to measure dynamic account loss. The system continuously tracks your highest market equity (including both realized and unrealized PnL) during your configured look-back window. For default Hyperliquid perps this is the default Perps account equity; for HIP-3 DEX markets it is the selected DEX-specific Perps equity, such as Perps (xyz). If your current market equity drops from that peak by the specified percentage threshold, it forces the AI to reduce risk or halts trading entirely. This approach protects profits and quickly stops bleeding without relying on a static starting balance.
  • Max Loss %: Measures account loss from the first available market-equity snapshot in the same rolling window to the current market equity. Unlike Max Drawdown %, it does not re-anchor to an intra-window peak; it answers, "how far down are we over this short-term or long-term window?"
  • Max Loss Count: Tracks repeated losing closes while the rolling window is net negative. Each losing close increments the count; once rolling net PnL recovers to breakeven or better, the count resets to 0. Threshold checks are inclusive (>=), so hitting the exact warning or critical value triggers that level immediately.

Prompt Injection:

{performance} will contain a JSON summary of these metrics for both time windows, plus a clear instruction if a threshold is breached (e.g., "WARNING: Flip Rate High (Short-Term). Stop reversing direction.").

Market Regime ({market_regime})

The Market Regime system analyzes MARKET CONDITIONS across all your selected timeframes. It provides an "External" view of the environment. This data is injected into the prompt via the {market_regime} variable.

  • ADX (Trend Strength): Warns if the market is non-trending (Dead). Prevents breakout entries in ranges.
  • Chop Index: Detects consolidation. Warns if price action is sideways and dangerous.
  • ATR % (Volatility): Measures expected move size. Warns if the range is too small to cover fees.
  • RVOL (Relative Volume): Compares recent fully closed candle dollar volume with a liquid historical baseline for the same asset and timeframe. Low RVOL warns the AI that participation is thin, which is especially useful for avoiding low-liquidity entries outside an asset's active market hours. If there is not enough closed history to calculate RVOL, the snapshot shows - and no RVOL warning is added to the prompt.

Prompt Injection:

{market_regime} will contain a JSON summary of ADX/Chop/ATR/RVOL for each asset, plus a synthesized instruction (e.g., "Market is CHOPPY. Avoid breakout strategies.").

Multi-Timeframe Sync

The system automatically synchronizes with your Candle Timeframes configuration.

  • If you select 5m, 1h, and 4h candles, the Market Regime Engine analyzes ADX, Chop, ATR, and RVOL for all three intervals.
  • This allows the AI to see nuanced context (e.g., "The 5m chart is choppy and dangerous, but the 4h chart is in a strong uptrend").
  • You do not need to configure a separate "Market Regime Timeframe"; it is fully automatic.

Enforcement Modes

Performance and Market Regime guardrails are controlled per metric. Each metric has its own on/off switch and "Soft" or "Hard" enforcement mode; neither panel has a panel-wide enable/disable or enforcement setting.

  • Soft Mode: Injects warnings as advice. The AI is told the guardrail is elevated but can decide to trade anyway if it sees a specific setup.
  • Hard Mode: Injects warnings as prohibitions. Critical hard-mode breaches can explicitly forbid opening new positions while still allowing the AI to manage or close existing risk.

Market News Context

Market News Context is optional prompt context controlled from the AI page's News Context panel. It is used only when the active prompt includes the {news} variable.

  • What the AI receives: A compact list of recent rows with timestamp, topic/category, headline text, and a bounded context snippet. A snippet can carry the relevant oil or geopolitical detail when the provider uses a generic market-wrap headline.
  • Source filters: You can narrow eligible news by selecting source/category buttons. Eligibility uses Benzinga's returned channels and tags; configured topic queries improve retrieval without creating separate categories. Leaving all buttons unselected means all fresh available news is eligible.
  • Headline limit: The Max Headlines control caps how much news context is sent so the model still has room for candles, positions, performance, and risk data.
  • Timespan: The Timespan control caps headline age. It defaults to 24 hours and can be set from 1 hour through 7 days.
  • How to use it: Headlines and snippets are unverified context, not trading instructions. News text alone does not justify opening, adding, reversing, reducing, or closing a position. The AI must confirm symbol relevance, recency, and alignment with price structure; no matching news is not a bullish or bearish signal.

Calendar Risk Management

The Calendar Risk Management system allows you to control how the AI behaves during high-impact economic events (e.g., FOMC, CPI, NFP). By configuring these settings, you can prevent the AI from trading during volatile windows or use the events as advisory context.

Enforcement Modes

  • Soft Mode: Events are advisory volatility context. They do not by themselves justify opening, increasing, reducing, reversing, or closing a position.
  • Hard Mode: Opening new positions or increasing exposure is forbidden during the configured risk window. Existing positions remain governed by their own thesis, configured exits, price structure, and position-specific risk.

In both modes, an upcoming or recent event is not an automatic exit signal. The calendar changes how the AI evaluates new risk; it does not invalidate an otherwise valid position.

Risk Configuration

  • Impact Levels: Select which events trigger the risk gate (High, Medium, Low, Holiday).
  • Currencies: Filter by relevant economies (e.g., USD, EUR).
  • Lookahead Window: Define how many minutes before (Pre-Buffer) and after (Post-Buffer) an event the risk rules apply. Fractional configured choices such as 0.5 minutes retain their full precision.

Stale Data Protection

The system automatically checks the freshness of the economic calendar data before every AI execution cycle.

  • If the calendar data is outdated (stale), the system will flag it and prevent the AI from making decisions based on incorrect event times.
  • This ensures the AI never reacts to "ghost" events or misses a critical release due to data lag.

The Tuning Lifecycle: Scientific & Surgical

Great traders treat their bots like science experiments, not slot machines. The goal is to be intentional: make one surgical change at a time and let the bot run long enough to gather significant data. Randomly turning dials every hour is a recipe for noise, not signal.

1. The Bleeder (Cut Fast)

If a bot executes consistently negative trades and bleeds PnL day after day, it is a bad configuration.

  • Reality Check: It will not magically "get better" with more time.
  • Action: Kill the profile or revert the settings immediately. Do not fall in love with a losing idea.

2. The Grinder (Tweak It)

If the bot makes trades but PnL hovers around break-even—some wins, some losses, mostly flat—it is promising. It survives the market but hasn't found its edge yet.

  • Diagnosis: This is the prime candidate for optimization. Look at the losers: are stops too tight? Is it entering too late?
  • Action: Make one small adjustment (e.g., widen stops by 1% or switch from Soft to Hard enforcement). Then wait 24-48 hours.

3. The Winner (Protect It)

If a bot has positive PnL over multiple days or weeks, it is a Winner.

  • The Trap: The urge to "perfect" it is dangerous. Any change you make has a high probability of breaking the delicate balance that is working.
  • Action: Be ultra-wary of changes. If you must experiment, clone the profile and test your "improvements" on the copy, leaving the original Winner to keep printing.

Disclaimer

Not Financial Advice: The content, tools, and algorithms provided by VTX Macro are for informational and educational purposes only. Nothing on this platform constitutes financial, investment, legal, or tax advice. You are solely responsible for your trading decisions.

Risk Warning: Cryptocurrency trading, especially with leverage, involves a high level of risk and may not be suitable for all investors. You could lose some or all of your initial investment. Do not trade with money you cannot afford to lose.

No Warranty: VTX Macro is provided "as is" without any warranty of any kind. We do not guarantee the accuracy of market data, the performance of trading algorithms, or the uptime of the service. We are not liable for any financial losses incurred while using this platform.