Broker Descriptors

Complete schema reference for Datafye Broker Descriptors.

Overview

A BrokerSpec defines your broker connection and trading configuration, including:

• Broker type and credentials

• Order routing preferences

• Position and risk management

• Execution settings

• Account configuration

Schema

Root Structure

apiVersion: datafye.io/v1
kind: BrokerSpec
metadata:
  name: <string>
  description: <string>
broker:
  type: <string>
  credentials:
    apiKey: <string>
    apiSecret: <string>
  endpoint: <string>
  account: <string>
routing:
  defaultRoute: <string>
  symbolRoutes:
    <symbol>: <route>
execution:
  orderType: market | limit | stop | stop_limit
  timeInForce: day | gtc | ioc | fok
  allowShortSelling: true | false
  allowMarginTrading: true | false
risk:
  maxPositionSize: <number>
  maxOrderValue: <number>
  maxDailyLoss: <number>
  positionLimits:
    <symbol>: <number>

Field: apiVersion

• Type: string

• Required: Yes

• Value: datafye.io/v1

• Description: Schema version for this descriptor

Field: kind

• Type: string

• Required: Yes

• Value: BrokerSpec

• Description: Identifies this as a Broker Descriptor

Field: metadata

• Type: object

• Required: Yes

• Description: Metadata about this broker configuration

metadata.name

• Type: string

• Required: Yes

• Format: lowercase alphanumeric with hyphens (DNS-1123 subdomain)

• Description: Unique identifier for this broker configuration

• Example: alpaca-paper, ib-production

metadata.description

• Type: string

• Required: No

• Description: Human-readable description

• Example: Alpaca paper trading account

Field: broker

• Type: object

• Required: Yes

• Description: Broker connection configuration

broker.type

• Type: string

• Required: Yes

• Values: alpaca | interactive-brokers | tradier | paper

• Description: Broker type

Type	Description
alpaca	Alpaca Markets
interactive-brokers	Interactive Brokers
tradier	Tradier Brokerage
paper	Simulated paper trading

broker.credentials

• Type: object

• Required: Yes (except for paper broker)

• Description: API credentials for broker authentication

broker.credentials.apiKey

• Type: string

• Required: Yes

• Description: API key for broker

• Security: Store in secrets, not plain text

broker.credentials.apiSecret

• Type: string

• Required: Yes

• Description: API secret for broker

• Security: Store in secrets, not plain text

Note: For production deployments, use Datafye's secrets management instead of embedding credentials directly.

broker.endpoint

• Type: string

• Required: No

• Description: Broker API endpoint URL

• Default: Standard endpoint for the broker type

• Examples:

  • https://paper-api.alpaca.markets — Alpaca paper trading

  • https://api.alpaca.markets — Alpaca live trading

broker.account

• Type: string

• Required: No

• Description: Account identifier (for brokers with multiple accounts)

• Example: U1234567 (Interactive Brokers account)

Field: routing

• Type: object

• Required: No

• Description: Order routing configuration

routing.defaultRoute

• Type: string

• Required: No

• Description: Default routing destination for all orders

• Examples:

  • SMART — Interactive Brokers smart routing

  • ARCA — NYSE Arca

  • ISLAND — NASDAQ

routing.symbolRoutes

• Type: object (map of symbol to route)

• Required: No

• Description: Symbol-specific routing overrides

• Example:

  symbolRoutes:
    AAPL: ISLAND
    SPY: ARCA

Field: execution

• Type: object

• Required: No

• Description: Default execution parameters

execution.orderType

• Type: string

• Required: No

• Default: market

• Values: market | limit | stop | stop_limit

• Description: Default order type for submissions

execution.timeInForce

• Type: string

• Required: No

• Default: day

• Values: day | gtc | ioc | fok

• Description: Default time-in-force for orders

Value	Description
day	Good for day (cancel at market close)
gtc	Good till canceled
ioc	Immediate or cancel
fok	Fill or kill

execution.allowShortSelling

• Type: boolean

• Required: No

• Default: false

• Description: Whether short selling is permitted

execution.allowMarginTrading

• Type: boolean

• Required: No

• Default: false

• Description: Whether margin trading is permitted

Field: risk

• Type: object

• Required: No

• Description: Risk management controls

risk.maxPositionSize

• Type: number

• Required: No

• Description: Maximum position size (in shares) for any single position

• Example: 1000

risk.maxOrderValue

• Type: number

• Required: No

• Description: Maximum order value (in dollars) for a single order

• Example: 50000

risk.maxDailyLoss

• Type: number

• Required: No

• Description: Maximum daily loss (in dollars) before trading is halted

• Example: 5000

risk.positionLimits

• Type: object (map of symbol to limit)

• Required: No

• Description: Symbol-specific position size limits

• Example:

  positionLimits:
    AAPL: 500
    TSLA: 100

Complete Examples

Example 1: Alpaca Paper Trading

apiVersion: datafye.io/v1
kind: BrokerSpec
metadata:
  name: alpaca-paper
  description: Alpaca paper trading for testing

broker:
  type: alpaca
  credentials:
    apiKey: ${ALPACA_API_KEY}
    apiSecret: ${ALPACA_API_SECRET}
  endpoint: https://paper-api.alpaca.markets

execution:
  orderType: market
  timeInForce: day
  allowShortSelling: true
  allowMarginTrading: false

risk:
  maxPositionSize: 1000
  maxOrderValue: 50000
  maxDailyLoss: 5000

Example 2: Interactive Brokers Production

apiVersion: datafye.io/v1
kind: BrokerSpec
metadata:
  name: ib-live
  description: Interactive Brokers production trading

broker:
  type: interactive-brokers
  credentials:
    apiKey: ${IB_API_KEY}
    apiSecret: ${IB_API_SECRET}
  account: U1234567

routing:
  defaultRoute: SMART
  symbolRoutes:
    SPY: ARCA
    QQQ: ISLAND

execution:
  orderType: limit
  timeInForce: day
  allowShortSelling: true
  allowMarginTrading: true

risk:
  maxPositionSize: 5000
  maxOrderValue: 100000
  maxDailyLoss: 10000
  positionLimits:
    AAPL: 1000
    TSLA: 500
    NVDA: 300

Example 3: Tradier with Conservative Risk

apiVersion: datafye.io/v1
kind: BrokerSpec
metadata:
  name: tradier-conservative
  description: Tradier with strict risk controls

broker:
  type: tradier
  credentials:
    apiKey: ${TRADIER_API_KEY}
    apiSecret: ${TRADIER_API_SECRET}

execution:
  orderType: limit
  timeInForce: day
  allowShortSelling: false
  allowMarginTrading: false

risk:
  maxPositionSize: 500
  maxOrderValue: 25000
  maxDailyLoss: 2500
  positionLimits:
    AAPL: 200
    MSFT: 200
    GOOGL: 100

Example 4: Pure Paper Trading (No Broker)

apiVersion: datafye.io/v1
kind: BrokerSpec
metadata:
  name: pure-paper
  description: Simulated paper trading with no broker connection

broker:
  type: paper

execution:
  orderType: market
  timeInForce: day
  allowShortSelling: true
  allowMarginTrading: true

risk:
  maxPositionSize: 10000
  maxOrderValue: 1000000
  maxDailyLoss: 50000

Validation Rules

Required Fields

• apiVersion must be datafye.io/v1

• kind must be BrokerSpec

• metadata.name is required

• broker.type is required

• broker.credentials required unless broker.type is paper

Credential Rules

• API keys and secrets should use environment variable substitution: ${VAR_NAME}

• For production, use Datafye secrets management

• Never commit credentials to version control

Risk Management Rules

• All risk limits are optional but recommended for live trading

• maxPositionSize must be positive if specified

• maxOrderValue must be positive if specified

• maxDailyLoss must be positive if specified

• Position limits must be positive and <= maxPositionSize

Execution Rules

• orderType must be valid for the broker

• timeInForce must be supported by the broker

• Some brokers may not support all order types

Broker-Specific Notes

Alpaca

• Endpoint: Use https://paper-api.alpaca.markets for paper trading

• Credentials: API key and secret from Alpaca dashboard

• Routing: Not configurable (handled by Alpaca)

Interactive Brokers

• Account: Required if you have multiple accounts

• Routing: Supports SMART and specific exchanges

• Credentials: Use IB API keys, not login credentials

Tradier

• Endpoint: Automatically configured based on credentials

• Routing: Limited configuration

• Credentials: OAuth token from Tradier

Paper Broker

• No credentials: Completely simulated

• No routing: Orders executed instantly at market price

• Fills: Simulated based on market data

• Use case: Testing and development only

Security Best Practices

Credential Management

1. Never hardcode credentials in descriptors

2. Use environment variables for local development

3. Use Datafye secrets for production deployments

4. Rotate credentials regularly

5. Use separate credentials for paper vs. live

Example with Secrets

broker:
  credentials:
    apiKey: ${BROKER_API_KEY}      # Environment variable
    apiSecret: ${BROKER_API_SECRET} # Environment variable

For production, reference Datafye secrets:

broker:
  credentials:
    apiKeySecret: broker-api-key-secret      # Datafye secret name
    apiSecretSecret: broker-api-secret-secret # Datafye secret name

Risk Control Recommendations

By Trading Style

Style	maxPositionSize	maxOrderValue	maxDailyLoss
Conservative	500-1000	$25k-$50k	$2.5k-$5k
Moderate	1000-5000	$50k-$100k	$5k-$10k
Aggressive	5000-10000	$100k-$250k	$10k-$25k
HFT/Scalping	10000+	$250k+	$25k+

Note: Adjust based on account size. Common practice is to limit daily loss to 1-2% of account value.

Related Documentation

• Concept guide: Broker Descriptors

• Algo integration: Algo Descriptors

• CLI usage: trading provision, trading start

• Security: Private Cloud Deployments