Trade Manager

Trade Manager - Automated Stop-Loss, Take-Profit, and Trailing Stops

Use this skill to create automated trading rules (stop-loss, take-profit, trailing stop) for your Polymarket positions. The Trade Manager runs as part of the Vincent backend and automatically executes trades when price conditions are met.

All commands use the @vincentai/cli package.

How It Works

Trade Manager is a companion to the Polymarket skill:

1. Use the Polymarket skill to browse markets and place bets
2. Use Trade Manager to set automated exit rules on those positions
3. The Trade Manager monitors prices in real-time via WebSocket (with polling as fallback) and executes trades through the same Polymarket infrastructure when triggers are met

Architecture:

• Integrated into the Vincent backend (no separate service to run)
• API endpoints under /api/skills/polymarket/rules/...
• Uses the same API key as the Polymarket skill
• Stores rules and events in the Vincent database
• Executes trades through the same policy-enforced Polymarket pipeline
• All Vincent policies (spending limits, approvals) still apply

Quick Start

1. Check Worker Status

Before creating rules, verify the monitoring worker is running:

npx @vincentai/cli@latest trade-manager health
# Expected: {"status":"ok","version":"0.1.0"}

npx @vincentai/cli@latest trade-manager status --key-id <KEY_ID>
# Returns: worker status, active rules count, last sync time, circuit breaker state

2. Create a Stop-Loss Rule

Automatically sell a position if price drops below a threshold:

npx @vincentai/cli@latest trade-manager create-rule --key-id <KEY_ID> \
  --market-id 0x123... --token-id 456789 \
  --rule-type STOP_LOSS --trigger-price 0.40

Parameters:

• --market-id: The Polymarket condition ID (from market data)
• --token-id: The outcome token ID you hold (from market data — use the token ID you bought)
• --rule-type: STOP_LOSS (sells if price <= trigger), TAKE_PROFIT (sells if price >= trigger), or TRAILING_STOP
• --trigger-price: Price threshold between 0 and 1 (e.g., 0.40 = 40 cents)

The CLI automatically passes {"type": "SELL_ALL"} as the action (only supported type in MVP).

3. Create a Take-Profit Rule

Automatically sell a position if price rises above a threshold:

npx @vincentai/cli@latest trade-manager create-rule --key-id <KEY_ID> \
  --market-id 0x123... --token-id 456789 \
  --rule-type TAKE_PROFIT --trigger-price 0.75

Pro tip: Create both a stop-loss AND take-profit on the same position to bracket your trade.

4. Create a Trailing Stop Rule

A trailing stop starts with a stop price, then automatically moves that stop price up as price rises.

npx @vincentai/cli@latest trade-manager create-rule --key-id <KEY_ID> \
  --market-id 0x123... --token-id 456789 \
  --rule-type TRAILING_STOP --trigger-price 0.45 --trailing-percent 5

Trailing stop behavior:

• --trailing-percent is percent points (for example 5 means 5%)
• Trade Manager computes candidateStop = currentPrice * (1 - trailingPercent/100)
• If candidateStop is above the current triggerPrice, it updates triggerPrice
• triggerPrice never moves down
• Rule triggers when currentPrice <= triggerPrice

5. List Active Rules

# All rules
npx @vincentai/cli@latest trade-manager list-rules --key-id <KEY_ID>

# Only active rules
npx @vincentai/cli@latest trade-manager list-rules --key-id <KEY_ID> --status ACTIVE

# Only triggered rules
npx @vincentai/cli@latest trade-manager list-rules --key-id <KEY_ID> --status TRIGGERED

6. Update a Rule's Trigger Price

npx @vincentai/cli@latest trade-manager update-rule --key-id <KEY_ID> --rule-id <RULE_ID> --trigger-price 0.45

7. Cancel a Rule

npx @vincentai/cli@latest trade-manager delete-rule --key-id <KEY_ID> --rule-id <RULE_ID>

The rule status changes to "CANCELED" and won't trigger anymore.

8. View Monitored Positions

See what positions the Trade Manager is currently tracking:

npx @vincentai/cli@latest trade-manager positions --key-id <KEY_ID>

Returns cached position data with current prices. This cache updates via WebSocket and periodic polling.

9. View Event Log (Audit Trail)

See detailed history of rule evaluations and executions:

# All events (most recent first, default limit=100)
npx @vincentai/cli@latest trade-manager events --key-id <KEY_ID>

# Events for specific rule
npx @vincentai/cli@latest trade-manager events --key-id <KEY_ID> --rule-id <RULE_ID>

# Paginated results
npx @vincentai/cli@latest trade-manager events --key-id <KEY_ID> --rule-id <RULE_ID> --limit 50 --offset 100

Event types:

• RULE_CREATED - Rule was created
• RULE_TRAILING_UPDATED - Trailing stop moved triggerPrice upward
• RULE_EVALUATED - Worker checked the rule against current price
• RULE_TRIGGERED - Trigger condition was met
• ACTION_PENDING_APPROVAL - Trade requires human approval, rule paused
• ACTION_EXECUTED - Trade executed successfully
• ACTION_FAILED - Trade execution failed
• RULE_CANCELED - Rule was manually canceled

Each event includes a data object with fields relevant to the event type:

• currentPrice - Price at time of evaluation
• triggerPrice - The rule's trigger threshold
• shouldTrigger - Whether the condition was met
• source - "websocket" for real-time WebSocket updates, absent for polling-based evaluations

Complete Workflow: Polymarket + Trade Manager

Here's how to use both skills together:

Step 1: Place a bet with Polymarket skill

# Search for a market
npx @vincentai/cli@latest polymarket markets --key-id <KEY_ID> --query bitcoin

# Place a bet on "Yes" outcome
npx @vincentai/cli@latest polymarket bet --key-id <KEY_ID> --token-id 123456789 --side BUY --amount 10 --price 0.55
# You bought 18.18 shares at 55 cents

Step 2: Set stop-loss with Trade Manager

# Protect your position with a 40 cent stop-loss
npx @vincentai/cli@latest trade-manager create-rule --key-id <KEY_ID> \
  --market-id 0xabc... --token-id 123456789 \
  --rule-type STOP_LOSS --trigger-price 0.40

Step 3: Set take-profit with Trade Manager

# Lock in profit if price hits 85 cents
npx @vincentai/cli@latest trade-manager create-rule --key-id <KEY_ID> \
  --market-id 0xabc... --token-id 123456789 \
  --rule-type TAKE_PROFIT --trigger-price 0.85

Step 4: Monitor your rules

# Check status
npx @vincentai/cli@latest trade-manager list-rules --key-id <KEY_ID> --status ACTIVE

# Check recent events
npx @vincentai/cli@latest trade-manager events --key-id <KEY_ID>

What Happens When a Rule Triggers

1. Worker detects trigger: The background worker checks all active rules against current prices in real-time via WebSocket (with periodic polling as fallback)
2. Rule marked as triggered: Status changes from ACTIVE to TRIGGERED atomically (prevents double-execution)
3. Trade executes: Calls the Polymarket bet pipeline to place a market sell order (same pipeline as manual trading, with full policy enforcement)
4. Events logged: Creates RULE_TRIGGERED and ACTION_EXECUTED events

Important: Executed trades still go through Vincent's policy enforcement. If your trade violates a spending limit or requires approval, the Trade Manager respects those policies.

Rule Statuses

• ACTIVE - Rule is live and being monitored
• TRIGGERED - Condition was met, trade executed (or attempted)
• PENDING_APPROVAL - Trade requires human approval; rule is paused until the approval is granted or denied
• CANCELED - Rule was manually canceled before triggering
• FAILED - Rule triggered but trade execution failed
• EXPIRED - (Future feature for time-based expiration)

Background Worker