Broker Descriptors

Broker descriptors define connections to brokerage accounts for paper and live trade execution. They specify which broker to connect to, how to authenticate, what trading permissions your algo has, and what risk limits to enforce.

Purpose

Broker descriptors tell Datafye:

Which broker to connect to (Alpaca, Interactive Brokers, etc.)
How to authenticate with your brokerage account
Trading mode (paper or live)
Trading permissions (what assets the algo can trade)
Risk limits (position sizes, loss limits, etc.)
Order settings (default order types, time in force, etc.)

Based on your broker descriptor, Datafye provisions the Broker Connector and establishes a secure connection to your brokerage account.

When You Need Broker Descriptors

Broker descriptors are required for Trading scenarios only:

Trading: Data Cloud + Broker — Connects your own algo containers to broker
Trading: Full Stack — Connects Datafye Algo Container to broker

For Foundry scenarios (Data Cloud Only and Full Stack), you don't need a broker descriptor since they're for development and backtesting only.

Structure

TODO: Provide actual YAML/JSON schema for broker descriptors with complete field definitions.

A typical broker descriptor includes:

broker:
  provider: "alpaca"           # Broker name
  mode: "paper"                # paper or live

  account:
    # Authentication credentials

  permissions:
    # What the algo can trade

  limits:
    # Risk management constraints

  defaults:
    # Default order settings

Supported Brokers

TODO: Provide complete list of supported brokers, links to broker setup guides, and any broker-specific requirements.

Datafye supports connections to multiple brokers:

Alpaca

broker:
  provider: "alpaca"
  mode: "paper"  # or "live"

  account:
    api_key: "${ALPACA_API_KEY}"
    api_secret: "${ALPACA_API_SECRET}"
    # [Base URL configurable for paper vs. live?]

Features:

Commission-free US equities trading
Paper trading with simulated fills
[Crypto trading supported?]
REST and WebSocket APIs

Setup:

Create account at alpaca.markets
Generate API keys in dashboard
[Paper and live use different keys?]

Interactive Brokers

broker:
  provider: "interactive_brokers"
  mode: "paper"  # or "live"

  account:
    username: "${IB_USERNAME}"
    password: "${IB_PASSWORD}"
    # [TWS/Gateway connection settings?]
    # [Account number required?]

Features:

Multi-asset class trading (stocks, options, futures, forex)
Global market access
[Paper trading through IB's paper account?]

Setup:

IB account required
[TWS or IB Gateway installation needed?]
[Special API permissions required?]

Other Brokers

[List other supported brokers: TD Ameritrade, Schwab, Robinhood, etc.?]

Each broker may have specific configuration requirements — see broker-specific documentation.

Trading Modes

Paper Trading

Simulated trading with fake money to validate your algo:

broker:
  provider: "alpaca"
  mode: "paper"

  account:
    api_key: "${ALPACA_PAPER_API_KEY}"
    api_secret: "${ALPACA_PAPER_API_SECRET}"

Characteristics:

No real money at risk
Simulated order fills (may not match real execution exactly)
Full broker API functionality
Same trading hours as live markets
Reset account balance as needed

Use cases:

Initial algo validation
Testing new strategies
Confidence building before live trading
Debugging order logic

Limitations:

Fills may be more optimistic than reality
[Slippage modeling accurate?]
[No impact from your orders on market]
Some edge cases may not be simulated perfectly

Live Trading

Real trading with actual capital:

broker:
  provider: "alpaca"
  mode: "live"

  account:
    api_key: "${ALPACA_LIVE_API_KEY}"
    api_secret: "${ALPACA_LIVE_API_SECRET}"

WARNING: Live trading involves real money and real risk. Only trade with capital you can afford to lose. Always paper trade first and start with small positions.

Characteristics:

Real capital at risk
Actual market execution and slippage
Real transaction costs
Subject to real market conditions
Trades affect your actual portfolio

Best practices:

Always paper trade first
Start with small position sizes
Monitor closely initially
Set strict risk limits
Have a stop-loss plan

Authentication

Environment Variables

Store credentials securely using environment variables:

broker:
  provider: "alpaca"
  mode: "paper"

  account:
    api_key: "${ALPACA_API_KEY}"
    api_secret: "${ALPACA_API_SECRET}"

Security best practices:

Never commit credentials to git
Use different keys for paper and live
Rotate keys periodically
Restrict key permissions to trading only
[Does Datafye provide secure credential storage?]

Credential Management

[How does Datafye handle broker credentials securely?]

[Encrypted storage?]
[Key rotation support?]
[Access controls?]
[Audit logging of credential usage?]

Trading Permissions

Define what assets and actions your algo is allowed to perform:

broker:
  provider: "alpaca"
  mode: "paper"

  permissions:
    - trade_equities        # Can trade stocks
    - trade_options         # Can trade options
    - short_selling         # Can short sell
    # [What permission types are available?]

TODO: Document all available permission types and what they control.

Permission categories:

Asset classes:

trade_equities — US stocks
trade_options — Options contracts
trade_futures — Futures contracts
trade_crypto — Cryptocurrencies
trade_forex — Foreign exchange

Trading actions:

short_selling — Short positions allowed
margin_trading — Use margin/leverage
extended_hours — Pre-market and after-hours trading

Account actions:

modify_orders — Change existing orders
cancel_orders — Cancel pending orders

Why restrict permissions?

Risk management — Prevent algo from unexpected actions
Compliance — Meet regulatory requirements
Testing — Start with limited permissions, expand gradually
Safety — Limit potential damage from bugs

Risk Limits

Enforce position sizing and loss limits to manage risk:

broker:
  provider: "alpaca"
  mode: "paper"

  limits:
    max_position_size: 10000        # Max $ per position
    max_position_percent: 0.1       # Max 10% of portfolio per position
    max_portfolio_value: 100000     # Max total portfolio value
    max_daily_trades: 50            # Max trades per day
    max_daily_loss: 500             # Max $ loss per day
    max_total_loss: 2000            # Stop trading if this loss hit
    # [What limit types are available?]

TODO: Document all available risk limit types and how they're enforced.

Position Limits

Control position sizing:

limits:
  max_position_size: 10000           # Absolute $ limit per position
  max_position_percent: 0.1          # 10% of portfolio max
  max_positions: 20                  # Max number of open positions
  max_position_concentration: 0.25   # Max 25% in single symbol

How limits are enforced:

Orders that would violate limits are rejected
[Partial fills if full order would violate?]
[Warnings before limits are hit?]

Loss Limits

Prevent catastrophic losses:

limits:
  max_daily_loss: 500         # Stop trading if daily loss exceeds $500
  max_weekly_loss: 2000       # Weekly loss limit
  max_total_loss: 5000        # Cumulative loss before shutting down
  max_drawdown_percent: 0.15  # 15% drawdown triggers stop

What happens when limit is hit:

[All positions closed immediately?]
[Trading suspended until manual intervention?]
[Alerts sent?]

Order Limits

Control order flow:

limits:
  max_order_size: 5000           # Max $ per single order
  max_daily_trades: 50           # Max orders per day
  max_orders_per_minute: 5       # Rate limiting
  min_order_value: 100           # Don't place orders < $100

Why order limits:

Prevent runaway algos
Avoid pattern day trader violations
Manage broker rate limits
Control transaction costs

Default Order Settings

Configure default order parameters:

broker:
  provider: "alpaca"
  mode: "paper"

  defaults:
    order_type: "limit"           # limit, market, stop, stop_limit
    time_in_force: "day"          # day, gtc, ioc, fok
    limit_offset: 0.001           # Offset for limit orders (0.1%)
    # [Other default settings?]

TODO: Document all configurable order defaults and their options.

Order Types

defaults:
  order_type: "limit"  # Options: market, limit, stop, stop_limit, trailing_stop

Order type selection:

Market: Immediate execution, no price guarantee
Limit: Price guarantee, execution not guaranteed
Stop: Trigger at price, then market order
Stop Limit: Trigger at price, then limit order
Trailing Stop: Dynamic stop based on price movement

Default vs. override:

Descriptor sets default
Algo can override per-order
[Are some order types restricted?]

Time in Force

defaults:
  time_in_force: "day"  # Options: day, gtc, ioc, fok

Time in force options:

day: Order expires at end of trading day
gtc (Good 'Til Canceled): Open until filled or canceled
ioc (Immediate or Cancel): Fill immediately or cancel
fok (Fill or Kill): Fill completely immediately or cancel

Limit Order Offset

For limit orders, how much to offset from current price:

defaults:
  limit_offset: 0.001  # 0.1% offset
  # Buy limit: current_price * (1 - offset)
  # Sell limit: current_price * (1 + offset)

Purpose:

Increase fill probability
Get better prices than market orders
Balance execution speed vs. price

Example Broker Descriptors

Example 1: Paper Trading with Alpaca

Basic paper trading setup for initial validation:

broker:
  provider: "alpaca"
  mode: "paper"

  account:
    api_key: "${ALPACA_PAPER_API_KEY}"
    api_secret: "${ALPACA_PAPER_API_SECRET}"

  permissions:
    - trade_equities

  limits:
    max_position_size: 5000
    max_daily_trades: 20
    max_daily_loss: 200

  defaults:
    order_type: "limit"
    time_in_force: "day"
    limit_offset: 0.001

Example 2: Conservative Live Trading

Small-scale live trading with strict limits:

broker:
  provider: "alpaca"
  mode: "live"

  account:
    api_key: "${ALPACA_LIVE_API_KEY}"
    api_secret: "${ALPACA_LIVE_API_SECRET}"

  permissions:
    - trade_equities  # Equities only, no shorting

  limits:
    max_position_size: 2000         # Small positions
    max_position_percent: 0.05      # 5% max per position
    max_daily_loss: 100             # Stop if lose $100/day
    max_total_loss: 500             # Hard stop at $500 loss
    max_daily_trades: 10            # Limit activity

  defaults:
    order_type: "limit"
    time_in_force: "day"

Example 3: Options Trading

Options strategy with appropriate permissions:

broker:
  provider: "interactive_brokers"
  mode: "paper"

  account:
    username: "${IB_USERNAME}"
    password: "${IB_PASSWORD}"

  permissions:
    - trade_equities    # For covered calls
    - trade_options     # Options trading

  limits:
    max_position_size: 10000
    max_positions: 10              # Limit number of positions
    max_daily_loss: 500

  defaults:
    order_type: "limit"
    time_in_force: "gtc"           # Options often use GTC

Example 4: High-Frequency Strategy

More permissive settings for active trading:

broker:
  provider: "alpaca"
  mode: "live"

  account:
    api_key: "${ALPACA_LIVE_API_KEY}"
    api_secret: "${ALPACA_LIVE_API_SECRET}"

  permissions:
    - trade_equities
    - short_selling              # Needed for pairs trading
    - extended_hours             # Pre/post market

  limits:
    max_position_size: 5000
    max_daily_trades: 200        # High frequency
    max_orders_per_minute: 10    # Rate limiting
    max_daily_loss: 1000

  defaults:
    order_type: "limit"
    time_in_force: "ioc"         # Immediate or cancel for speed
    limit_offset: 0.0005         # Tighter offset

Validation

Before provisioning, Datafye validates your broker descriptor:

Schema Validation

All required fields present
Valid broker provider name
Valid mode (paper or live)
Credentials format correct

Broker Connectivity

Can authenticate with broker
Account exists and is accessible
[Test API connectivity?]
[Verify account permissions match requested permissions?]

Limits Validation

Limit values are reasonable
No conflicting limits
[Verify limits are within broker account constraints?]

Common validation errors:

Invalid broker credentials
Broker account not found or inaccessible
Requested permissions not available on account
Risk limits conflict or are invalid
[Other common errors?]

Broker-Specific Considerations

Alpaca

Strengths:

Easy setup with API keys
Good paper trading environment
Commission-free equities
Real-time data included

Limitations:

US markets only
[Options trading support status?]
[Crypto support?]

Interactive Brokers

Strengths:

Multi-asset class support
Global market access
Low commissions

Limitations:

More complex setup (TWS/Gateway)
[Minimum account balance?]
[API complexity?]

Other Brokers

[Document broker-specific setup, features, and limitations for each supported broker]

Security Best Practices

Credential Management

Do:

Use environment variables for credentials
Use different keys for paper and live
Rotate API keys regularly
Restrict key permissions to minimum needed
Monitor key usage for anomalies

Don't:

Commit credentials to git
Share credentials
Use same credentials across environments
Give keys broader permissions than needed

Permission Scoping

Principle of least privilege:

Start with minimal permissions
Add permissions only as needed
Review permissions regularly
Revoke unused permissions

Risk Limit Tuning

Start conservative:

Begin with small position sizes
Set tight loss limits initially
Gradually increase as confidence builds
Always have hard stop-loss limits

Monitoring and Alerts

TODO: Document monitoring and alerting capabilities for broker connections and risk limits.

Monitor:

Connection health to broker
Order success/failure rates
Position sizes relative to limits
Daily/total losses relative to limits
[What metrics are available?]

Alerts:

Connection failures
Approaching risk limits
Risk limits hit
Authentication errors
Unusual order patterns
[How are alerts configured and delivered?]

Transitioning from Paper to Live

Pre-Live Checklist

Before switching to live trading:

Extensive paper trading
- Run for at least [recommended period?]
- Include various market conditions
- Verify fills and execution
Review performance
- Compare to backtest expectations
- Check slippage and costs
- Analyze order fills
Validate risk controls
- Test position limits work
- Verify loss limits trigger
- Confirm permissions are correct
Update credentials
- Switch to live API keys
- Verify live account has adequate funds
- Double-check all settings
Start small
- Use smaller position sizes initially
- Tighter risk limits at first
- Monitor closely for first days/weeks

Descriptor Changes for Live

# Change mode
mode: "live"  # was "paper"

# Use live credentials
account:
  api_key: "${ALPACA_LIVE_API_KEY}"     # was PAPER_API_KEY
  api_secret: "${ALPACA_LIVE_API_SECRET}"

# Tighten limits for live
limits:
  max_position_size: 2000        # Start smaller
  max_daily_loss: 100            # Tighter control
  max_daily_trades: 10           # Limit activity

Best Practices

Development Workflow

Development (broker-paper.yaml):

broker:
  provider: "alpaca"
  mode: "paper"

  limits:
    max_position_size: 10000     # Generous for testing
    max_daily_trades: 100        # No strict limits

Production (broker-live.yaml):

broker:
  provider: "alpaca"
  mode: "live"

  limits:
    max_position_size: 2000      # Conservative
    max_daily_loss: 100          # Strict controls
    max_total_loss: 500

Version Control

Store broker descriptors in git (without credentials!)
Use environment variables for all secrets
Document broker setup in README
Tag descriptors with deployment versions

Testing

Verify paper trading matches backtest performance
Test risk limit enforcement
Validate order execution
Check error handling (network issues, rejections, etc.)

Next Steps

Learn about paper trading — Paper Trading Your Algo
Understand other descriptors — Data Descriptors, Algo Descriptors
See complete schema — Broker Descriptor Reference
Start trading — Trading: Data Cloud + Broker

Last updated: 2025-10-11

PreviousThe Broker Connector NextThe Datafye MCP Servers

Last updated 1 month ago

Good afternoon

Purpose

When You Need Broker Descriptors

Structure

Supported Brokers

Alpaca

Interactive Brokers

Other Brokers

Trading Modes

Paper Trading

Live Trading

Authentication

Environment Variables

Credential Management

Trading Permissions

Risk Limits

Position Limits

Loss Limits

Order Limits

Default Order Settings

Order Types

Time in Force

Limit Order Offset

Example Broker Descriptors

Example 1: Paper Trading with Alpaca

Example 2: Conservative Live Trading

Example 3: Options Trading

Example 4: High-Frequency Strategy

Validation

Schema Validation

Broker Connectivity

Limits Validation

Broker-Specific Considerations

Alpaca

Interactive Brokers

Other Brokers

Security Best Practices

Credential Management

Permission Scoping

Risk Limit Tuning

Monitoring and Alerts

Transitioning from Paper to Live

Pre-Live Checklist

Descriptor Changes for Live

Best Practices

Development Workflow

Version Control

Testing

Next Steps