UTM Platform User Trading Flows

Audience: End users learning how to trade with UTM Purpose: Step-by-step guide to all trading workflows

---

Overview: How Trading Works in UTM

UTM provides two ways to trade:

1. Direct Orders - Place orders manually through the web interface
2. Signal-Based Trading - Create signals (manually or via webhooks) that convert to orders

Both methods result in the same outcome: orders sent to your broker, executions tracked, and trades managed.

The Trading Pipeline

Signal (optional)     Order            Execution         Trade
    │                   │                  │               │
    │   "I want to      │   "Buy 100       │   "Filled     │   "Long position
    │    open long      │    AAPL at       │    50 @ 175,  │    in AAPL,
    │    AAPL"          │    market"       │    50 @ 176"  │    avg cost $175.50"
    │                   │                  │               │
    ▼                   ▼                  ▼               ▼
┌─────────┐       ┌─────────┐       ┌──────────┐     ┌─────────┐
│ Signal  │ ───▶  │  Order  │ ───▶  │Execution │ ──▶ │  Trade  │
└─────────┘       └─────────┘       └──────────┘     └─────────┘
                       │
                       ▼
                   [Broker]

---

Part 1: Getting Started

1.1 Account Setup

Before trading, you need to connect a broker.

Step 1: Navigate to Settings

• Open Settings from the sidebar (or the nav drawer on mobile), then go to the "Brokers" tab
• Or click your profile in the top-right and select the "Brokers" quick-link to jump straight to the tab

Step 2: Add a Broker

Broker	Auth Method	Supported Features
Alpaca	API Key	Full trading, positions, orders
TradeStation	OAuth	Positions, orders (read-only trading)

For Alpaca (Recommended for full trading):

1. Click "Add Alpaca"
2. Enter your API Key ID and Secret Key
3. Choose paper or live environment
4. Click "Connect"

Your accounts will sync automatically.

1.2 Paper vs Live Mode

UTM has a mode switcher that controls which accounts you see and can trade.

Paper Mode (Default):

• Shows only paper/demo accounts
• Orders go to paper trading environment
• Safe for testing strategies
• Green indicator in header

Live Mode:

• Shows only live accounts
• Orders go to real brokers with real money
• Irreversible trades
• Red indicator in header

To Switch Modes:

1. Click the mode indicator in the header
2. Select "Paper" or "Live"
3. Confirm if switching to Live

Safety Feature: UTM blocks orders if your selected account doesn't match your mode. You cannot accidentally place live orders while in paper mode.

1.3 Setting Your Primary Account

Each mode (paper/live) has a primary account used as the default for orders.

1. Go to Settings → Accounts
2. Find your preferred account
3. Click "Set as Primary"

The primary account appears first in all account selectors.

---

Part 2: Direct Order Placement

2.1 Placing a Market Order

The fastest way to enter or exit a position.

Step 1: Open Order Entry

• From Dashboard or Positions page
• Click "Place Order" button

Step 2: Fill Order Details

1. Account: Select your trading account
2. Symbol: Enter ticker (e.g., AAPL, MSFT)
3. Action: Buy or Sell
4. Quantity: Number of shares
5. Order Type: Select "Market"
6. Time in Force: Usually "Day"

Step 3: Review and Submit

• Click "Review Order"
• Verify details on confirmation screen
• Click "Place Order"

What Happens Next:

1. Order sent to broker (status: Pending)
2. Broker acknowledges receipt (status: Accepted)
3. Order fills (status: Filled)
4. Trade created/updated automatically
5. Position reflects new holdings

2.2 Placing a Limit Order

Get a specific price or better.

Same as Market Order, except:

• Order Type: "Limit"
• Limit Price: Your target price
  • For Buy: Order fills at limit price or lower
  • For Sell: Order fills at limit price or higher

Example: Buy 100 AAPL at $175 limit

• If AAPL is at $176, order waits
• If AAPL drops to $175, order fills
• Order expires at market close (if DAY)

2.3 Stop and Stop-Limit Orders

Protect positions or enter on breakouts.

Stop Order:

• Becomes market order when stop price is reached
• Stop Price: Trigger price
• Use for: Stop-losses, breakout entries

Stop-Limit Order:

• Becomes limit order when stop price is reached
• Stop Price: Trigger price
• Limit Price: Execution price after trigger
• Use for: Controlled stop-losses with price guarantee

2.4 Time in Force Options

How long your order stays active:

TIF	Name	Behaviour
DAY	Day Order	Expires at market close
GTC	Good til Cancelled	Stays active until filled or cancelled
IOC	Immediate or Cancel	Fill immediately or cancel unfilled portion
FOK	Fill or Kill	Fill completely or cancel entirely
OPG	Market on Open	Execute at opening auction
CLS	Market on Close	Execute at closing auction

2.5 Extended Hours Trading

Trade before market open (pre-market) or after close (after-hours).

To Enable:

• Toggle "Extended Hours" in order entry
• Only works with Limit orders
• Wider spreads and less liquidity

Extended Hours Sessions:

• Pre-market: 4:00 AM - 9:30 AM ET
• After-hours: 4:00 PM - 8:00 PM ET

---

Part 3: Signal-Based Trading

Signals are trading intentions that can be processed into orders.

3.1 Why Use Signals?

1. Automation: Receive signals from TradingView, custom scripts, etc.
2. Review Before Execution: Create signals, review them, then execute
3. Quantity Flexibility: Specify shares, % of equity, or dollar amounts
4. Strategy Tracking: Link signals to strategies for performance analysis
5. Scheduled Execution: Schedule signals for future times

3.2 Signal Actions Explained

Signals use four actions that combine direction and intent:

Action	Direction	Intent	Resulting Order
openLong	Long	Open	Buy
closeLong	Long	Close	Sell
openShort	Short	Open	Sell (short)
closeShort	Short	Close	Buy (cover)

Why not just "buy" and "sell"?

Because "buy" is ambiguous:

• Buying to open a long position?
• Buying to close a short position?

Signal actions make intent explicit, reducing errors.

3.3 Creating a Manual Signal

Step 1: Navigate to Signals

• Click "Signals" in the navigation
• Click "New Signal"

Step 2: Fill Signal Details

Field	Description
Account	Which account to trade
Symbol	Ticker symbol
Action	openLong, closeLong, openShort, closeShort
Quantity Type	How to interpret quantity
Quantity	Amount based on quantity type
Strategy	Optional - for tracking
Limit Price	Optional - for limit orders
Stop Price	Optional - for stop orders

Quantity Types:

Type	Quantity Meaning	Example
Fixed	Number of shares	100 = 100 shares
Percent Equity	% of account equity	5 = 5% of equity
Dollar Amount	Dollar value to invest	1000 = $1000 worth

Step 3: Save Signal

• Signal enters "Pending" status
• Ready for processing

3.4 Processing a Signal

Converting a signal to an order.

Single Signal:

1. Find signal in the Signals table
2. Click "Process" button
3. Order is created and sent to broker
4. Signal status: Executed

Batch Processing:

1. Select multiple pending signals
2. Click "Process Selected"
3. All signals convert to orders

What Can Go Wrong:

• Rejected: Invalid symbol, account issue
• Expired: Signal passed its validUntil time
• Cancelled: You cancelled before processing

3.5 Webhook Signal Ingestion

Receive signals from external systems (TradingView, custom scripts).

Step 1: Create an API Key

1. Settings → API Keys
2. Click "Create API Key"
3. Select signals:write scope
4. Save the key (shown only once!)

Step 2: Send Signals via Webhook

curl -X POST https://api.universaltrademanager.com/api/v1/signals \
  -H "Content-Type: application/json" \
  -H "X-API-Key: utm_your_api_key" \
  -d '{
    "symbol": "AAPL",
    "action": "openLong",
    "accountId": "your-account-uuid",
    "quantity": 100
  }'

For TradingView:

1. Create alert on your indicator/strategy
2. Set webhook URL to the ingest endpoint
3. Format message as JSON with signal fields
4. Add X-API-Key header (requires Pro+ plan)

3.6 Exit Rules (Auto-Close)

Automatically create exit signals when entry fills. Exit fields sit directly on the signal payload, not nested under an exitRule object.

Example: Close position at market close

{
  "symbol": "AAPL",
  "action": "openLong",
  "accountId": "your-account-uuid",
  "quantity": 100,
  "exitTriggerType": "minutesBeforeClose",
  "exitTriggerMinutes": 5,
  "exitOrderType": "moc",
  "exitTimeInForce": "cls"
}

See the Exit Rules section in the Signals guide for the full field list and trigger-type behaviours.

---

Part 4: Managing Positions

4.1 Viewing Positions

Dashboard → Positions Snapshot:

• Quick view of current holdings
• Unrealised P&L for each position

Positions Page:

• Full position details
• Filter by account, symbol
• Sort by various fields

4.2 Understanding Position Data

Field	Meaning
Symbol	Ticker symbol
Quantity	Number of shares held
Avg Cost	Average entry price
Market Value	Current market value
Unrealised P&L	Current profit/loss
Last Sync	When data was refreshed

4.3 Closing a Position

From Positions Page:

1. Find the position
2. Click "Close"
3. Opens order entry pre-filled with:
   • Action: Sell (for long) / Buy (for short)
   • Symbol: Position symbol
   • Quantity: Full position size

Partial Close:

• Modify quantity to close only part of position
• Remaining shares stay open

Closing outside the regular session: The Close button on the trades page (single trade or "Close Multiple Trades") always works, even when the US regular session is closed. Each order is placed for the next regular open: as a Market on Open order where your broker supports it, otherwise as a limit order 5% through the last broker-reported price for the position. The confirmation dialog tells you which will happen before you confirm.

---

Part 5: Managing Trades

5.1 Trade vs Position vs Order

Concept	What It Represents	Lifecycle
Order	Single broker command	Pending → Filled/Cancelled
Position	Current holdings (broker view)	Snapshot in time
Trade	Aggregated position (UTM view)	Open → Closed

Why Trades?

Positions show what you hold now. Trades show:

• When you entered
• Multiple orders that built the position
• Exit prices and P&L
• Strategy attribution

5.2 Trade Statuses

Status	Meaning
Pending	Trade created, no fills yet
Open	Position established
Partial Close	Some shares sold
Closed	Fully exited
Expired	Order never filled

5.3 Trade Views

Trades Page Tabs:

• Pending: Trades with unfilled orders
• Open: Active positions
• Closed: Completed trades with P&L
• Expired: Orders that expired unfilled
• Net Positions: Aggregated by symbol
• Import Review: Broker executions needing review

5.4 Editing Trades

Limited fields can be edited:

Field	Always Editable	Notes
Strategy	✅	Re-attribute to different strategy
Notes	✅	Add trade notes/comments
Opened At	Only imported	Fix import date
Closed At	Only imported	Fix import date

Financial fields (price, quantity, P&L) cannot be manually edited - they reflect actual executions.

---

Part 6: Reconciliation

6.1 What is Reconciliation?

Reconciliation compares:

• UTM's view: Trades and positions tracked in UTM
• Broker's view: Actual positions at the broker

Discrepancies can occur if:

• Orders placed outside UTM (other platforms)
• Sync issues or timing gaps
• Manual broker interventions

6.2 Viewing Discrepancies

Accounts Page → Reconciliation Tab

Shows any mismatches:

• Positions in broker but not UTM
• Positions in UTM but not broker
• Quantity differences
• Side mismatches

6.3 Resolving Discrepancies

Missing in UTM (broker has position, UTM doesn't):

• Click "Import" to create trade from broker position
• Optionally assign to a strategy
• Optionally split across strategies

Missing in Broker (UTM has trade, broker doesn't):

• May indicate closed position not synced
• Click "Close Trade" to mark as closed
• Or "Ignore" if intentional

Quantity Mismatch:

• Review the difference
• Adjust UTM trade or investigate broker

6.4 Pending Imports

Broker executions that don't match any UTM order.

Common Causes:

• Trades placed via broker's platform
• Mobile app orders
• Pre-existing positions before UTM

Resolution:

1. Navigate to Trades → Import Review tab
2. Review pending imports
3. Choose:
   • Approve: Create new trade
   • Merge: Add to existing trade
   • Reject: Ignore this execution

---

Part 7: Strategies

7.1 What are Strategies?

Strategies let you categorise and track trading approaches.

Examples:

• "Momentum" - Trend following trades
• "Mean Reversion" - Buy dips, sell rallies
• "Earnings Plays" - Around earnings dates

7.2 Creating a Strategy

1. Navigate to Strategies page
2. Click "New Strategy"
3. Fill details:
   • Name: Strategy identifier
   • Description: What it does
   • Type: Category (trend, mean reversion, etc.)
   • Auto-Close: Whether to close at market close

7.3 Strategy Tracking

Each strategy shows:

• Total Trades: Number of trades
• Win Rate: Percentage of profitable trades
• Total P&L: Cumulative profit/loss
• Last Trade: Most recent trade date

7.4 Auto-Close Feature

Automatically close positions at market close.

Enable on Strategy:

1. Edit strategy
2. Toggle "Auto-close at market close"
3. Set "Minutes before close" (0-30)

How It Works:

Auto-close uses an event-driven design with a startup failsafe.

Primary path (event-driven):

1. A trade linked to this strategy transitions to OPEN.
2. UTM schedules a close-position job for the next session whose close has not passed, timed at market close minus the configured minutes.
3. When the job fires, UTM creates and submits the close order.

Startup failsafe:

When the API starts up, UTM runs a one-time auto-close-startup-check job. This scans all strategies with auto-close enabled and schedules any close-position jobs that are missing for the upcoming session. The check is idempotent, so it skips strategies that already have a job scheduled. This catches any gaps from a restart or missed trigger during the trading day.

If you switch auto-close off, switch the strategy's Active toggle off, or delete the strategy, a close job that is already queued does not fire.

You can also trigger the startup check manually from Admin > Scheduled Jobs > Scheduled tab > Trigger Auto-Close.

Use Case: Day trading strategies that should not hold overnight.

---

Part 8: Dashboard Overview

8.1 Dashboard Components

Portfolio Summary:

• Total equity across all accounts
• Day P&L (dollar and percentage)
• Cash available
• Market value of positions

Equity Chart:

• 30-day balance history
• Visual trend of portfolio value

Positions Snapshot:

• Top open positions
• Quick unrealised P&L view

Orders Snapshot:

• Recent order activity
• Quick status check

8.2 Syncing Data

Manual Sync:

• Click sync icon next to broker
• Refreshes positions, orders, balances

Automatic Sync:

• After placing orders: 7-second delay, then sync
• Periodic background sync (when implemented)

Sync Status:

• Green checkmark: Recently synced
• Yellow: Stale data
• Red: Sync error

---

Part 9: Common Workflows

9.1 Day Trade Workflow

1. Morning: Check dashboard for overnight news impact
2. Open Positions: Use signals or direct orders
3. Monitor: Watch positions page for P&L
4. Close Before EOD: Use auto-close or manual exit
5. Review: Check closed trades for P&L

9.2 Swing Trade Workflow

1. Entry: Place order when setup triggers
2. Set Stop: Place stop order for risk management
3. Monitor Daily: Check positions
4. Adjust: Move stops, take partials
5. Exit: When target hit or stop triggered

9.3 Automated Strategy Workflow

1. Setup: Create API key, configure webhook
2. Signal Source: TradingView alerts, custom scripts
3. Ingest: Signals arrive via webhook
4. Execute: Signals process immediately (or schedule with scheduledProcessAt)
5. Track: View in Signals page
6. Analyse: Review strategy performance

---

Part 10: Troubleshooting

10.1 Order Not Filling

Check:

• Market hours (is market open?)
• Order type (limit price too aggressive?)
• Account has buying power?
• Symbol tradeable on this broker?

Resolution:

• Check order status for rejection reason
• Verify account balances
• Try different order type

10.2 Position Not Showing

Check:

• Sync status (when was last sync?)
• Correct account selected?
• Right trading mode (paper vs live)?

Resolution:

• Click manual sync
• Wait 30 seconds
• Check broker directly

10.3 Trade P&L Looks Wrong

Common Causes:

• Commission not included
• Average cost from multiple fills
• Currency conversion (if applicable)

Check:

• View trade details → Executions
• Verify each fill price
• Check commission field

10.4 Signal Rejected

Common Reasons:

• Invalid symbol
• Account not found
• Insufficient buying power
• Market closed

Check Signal Details:

• Error message field
• Validation details
• Account status

---

Quick Reference: Keyboard Shortcuts

Shortcut	Action
G then D	Go to Dashboard
G then P	Go to Positions
G then O	Go to Orders
G then T	Go to Trades
G then S	Go to Signals
N then O	New Order
N then S	New Signal
Esc	Close modal

---

Glossary

Term	Definition
Signal	Trading intent, can be processed to order
Order	Command sent to broker
Execution	Filled portion of an order
Trade	Aggregated position with P&L tracking
Position	Current holdings snapshot
Strategy	Category for trade attribution
TIF	Time in Force - order duration
P&L	Profit and Loss
MOC	Market on Close order
Reconciliation	Comparing UTM and broker data

---

Last updated: 2026-02-23