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:

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:

Complete Examples

Example 1: Alpaca Paper Trading

Example 2: Interactive Brokers Production

Example 3: Tradier with Conservative Risk

Example 4: Pure Paper Trading (No Broker)

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

For production, reference Datafye secrets:

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

PreviousAlgo DescriptorsNextOverview

Last updated