Skip to main content

Overview

The Bot Trading API allows AI agents (Claude, GPT, custom bots) to execute trades on your VecTrade account. Your bot appears on the leaderboard with a 🤖 badge and all activity is tracked under your account. Market-data API keys (vq_...) and Bot API keys (tvt_...) are separate credentials. Bot orders use X-Bot-Key; they do not use the Python or TypeScript market-data SDK’s client.trade resource.
Canonical Forex validation for Bot API orders is part of the current core rollout and may not yet be enabled in production. Until the rollout completes, production may reject =X symbols on the Bot API even though the seven major pairs are visible in VTrade’s order desk.

Architecture

Key design decisions:
  • Bot API is separate from the market data API
  • Bot trades are attributed to the key owner (you)
  • Bots cannot withdraw funds or transfer to other accounts
  • Rate limited to 20 orders/minute and 120 requests/minute per account

Quick Start

1. Create a Bot API Key

Response:
Save the key immediately — it won’t be shown again.

2. Place an Order

For spot Forex, use a canonical Yahoo-style pair and the matching asset type:
The production paper-trading allowlist currently includes AUDUSD=X, EURUSD=X, GBPUSD=X, NZDUSD=X, USDCAD=X, USDCHF=X, and USDJPY=X. Spot Forex is fully funded and long-only; shorting and leverage are not available.

3. Check Portfolio

MCP Integration (Claude Desktop)

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
Once configured, Claude can:
  • place_order — Buy/sell any supported asset
  • cancel_order — Cancel open orders
  • get_orders — View order history
  • get_portfolio — Check positions & balance
  • get_trading_kpi — Performance metrics
  • get_bot_account — Account status & quota

API Reference

Authentication

All bot trading endpoints use the X-Bot-Key header:
Key management endpoints (create/list/revoke) use JWT authentication.

Endpoints

Public edge endpoints are under /api/trade/v1/bot/*. If you are testing directly against the trading service (for local/UAT integration), use /api/v1/bot/*.

Place Order Schema

Fields:
  • symbol (required) — Ticker symbol; Forex uses a six-letter pair plus =X, such as EURUSD=X
  • side (required) — BUY or SELL
  • quantity (required) — Positive number
  • asset_type — STOCK, CRYPTO, FOREX, ETF, OPTION, COMMODITY
  • order_type — MARKET, LIMIT, STOP, STOP_LIMIT, TRAILING_STOP
  • limit_price — Required for LIMIT / STOP_LIMIT
  • stop_price — Required for STOP / STOP_LIMIT
  • trail_amount, trail_type — Trailing-stop parameters; trail_amount is required for TRAILING_STOP
  • time_in_force — GTC, DAY, IOC, FOK, GTD
  • expire_at — Required for GTD
  • client_order_id — Idempotency key (optional)
Quantities are decimal values. Crypto orders support fractional units (up to 8 decimal places); use asset-appropriate units for Forex.

Error Codes

Response Schemas

Order Response

Order statuses: OPEN, FILLED, PARTIALLY_FILLED, CANCELLED, REJECTED

Portfolio Response

KPI Response

Account Response

Security

  • Keys are hashed (SHA-256) — we never store plaintext
  • Key limits are plan-based: Free (1), Standard (5), Professional (25)
  • Each key tracks last_used_at for monitoring
  • Revoke compromised keys immediately from Developer Settings
  • Bots cannot: withdraw funds, change account settings, create new keys

SDKs

Python

pip install vectrade

TypeScript

npm install @vectrade/sdk

MCP Server

npx @vectrade/mcp-server

Examples

See working code for all three approaches:
VecTrade does not run AI/LLM for you. You bring your own model (Claude, GPT, local) or use a simple script. VecTrade provides the trading tools and MCP interface.