Trading

Learn how to place, modify, and cancel orders across different brokerages using Finatic's unified trading API.

Once you have connected brokerages and retrieved account data, you can start placing orders. Finatic provides a unified trading API that works across all supported brokers, with broker-specific parameters handled automatically.

Overview

Finatic's trading API supports three main operations:

Place Order: Submit a new order to a broker
Modify Order: Update an existing order (price, quantity, etc.)
Cancel Order: Cancel an existing order

All trading operations require:

✅ An active broker connection with trading permissions
✅ A valid account number
✅ Proper order parameters (symbol, quantity, order type, etc.)

Important: Trading operations require the user to have granted trading permissions when connecting their broker. If trading permissions were not granted, you'll receive a TRADE_ACCESS_DENIED error when attempting to place orders.

Place Order

Place a new order with a broker. Finatic provides a unified interface that works across all supported brokers, with broker-specific parameters handled automatically.

Basic Example

const result = await finatic.placeOrder({
  broker: 'robinhood',
  accountNumber: 123456789,
  order: {
    orderType: 'market',
    assetType: 'equity',
    action: 'buy',
    timeInForce: 'day',
    symbol: 'AAPL',
    orderQty: 1
  }
});

if (result.success) {
  console.log('Order placed:', result.success.data.order_id);
} else {
  console.error('Failed to place order:', result.error);
}

Parameters

The placeOrder method accepts flattened parameters for a clean, intuitive API:

Required parameters:

broker (string): The broker ID (e.g., 'robinhood', 'ninja_trader', 'tasty_trade', 'alpaca')
accountNumber (number): The account number to place the order in
order (object): The order details object

Standard order fields (required):

orderType (string): Order type (e.g., 'market', 'limit', 'stop', 'stop_limit')
assetType (enum): Asset type (e.g., 'equity', 'equity_option', 'crypto', 'forex')
action (enum): Order action ('buy' or 'sell')
timeInForce (string | object): Time in force - can be a string like 'day' or an object { timeInForce: 'day' }
symbol (string): The trading symbol/ticker (e.g., 'AAPL', 'TSLA')
orderQty (number): The quantity to trade

Optional order fields (broker-specific):

limitPrice (number): Limit price for limit orders
stopPrice (number): Stop price for stop orders
Additional broker-specific fields - see broker-specific examples below or the API Reference

Modify Order

Modify an existing order (e.g., change the limit price or quantity).

const result = await finatic.modifyOrder({
  orderId: 'order-123',
  broker: 'ninja_trader',
  accountNumber: 123456789,
  order: {
    orderType: 'limit',
    assetType: 'equity',
    action: 'buy',
    timeInForce: 'day',
    symbol: 'AAPL',
    orderQty: 15, // Changed from 10 to 15
    limitPrice: 151.00 // Changed from 150.00 to 151.00
  }
});

if (result.success) {
  console.log('Order modified:', result.success.data.order_id);
} else {
  console.error('Failed to modify order:', result.error);
}

Note: When modifying an order, you must include all required fields in the order object, not just the fields you want to change. The broker will use the entire order object to update the order.

Cancel Order

Cancel an existing order.

const result = await finatic.cancelOrder({
  orderId: 'order-123'
});

if (result.success) {
  console.log('Order cancelled:', result.success.data.order_id);
} else {
  console.error('Failed to cancel order:', result.error);
}

Response Format

All trading methods return a standard response format with an OrderActionResult in the success data:

{
  success: {
    data: {
      success: true,
      message: "Order placed successfully",
      order_id: "12345678"
    }
  }
}

The OrderActionResult includes:

success (boolean): Whether the operation completed successfully
message (string | null): Human-readable message describing the result
order_id (string | null): Broker-assigned order identifier

Order Types

Finatic supports various order types across brokers:

Market: Execute immediately at the best available price
Limit: Execute at a specific price or better
Stop: Trigger when price reaches a stop price, then execute as market order
Stop Limit: Trigger when price reaches a stop price, then execute as limit order

Note: Not all order types are supported by all brokers. Check the API Reference for broker-specific capabilities.

Time In Force

Orders can have different time-in-force (TIF) settings:

Day: Order is valid for the trading day
Good Till Canceled (GTC): Order remains active until filled or canceled
Immediate or Cancel (IOC): Fill immediately or cancel
Fill or Kill (FOK): Fill completely or cancel

The exact TIF options vary by broker. See the API Reference for broker-specific TIF options.

Error Handling

Trading operations can fail for various reasons:

Missing trading permissions: User didn't grant trading permissions when connecting
Invalid order parameters: Missing required fields or invalid values
Insufficient funds: Account doesn't have enough buying power
Market closed: Attempting to place an order when market is closed
Broker-specific errors: Broker rejected the order for their own reasons

Always check the response for errors:

const result = await finatic.placeOrder({
  broker: 'robinhood',
  accountNumber: 123456789,
  order: { /* ... */ }
});

if (result.error) {
  console.error('Error code:', result.error.code);
  console.error('Error message:', result.error.message);
  console.error('Error details:', result.error.details);
  
  // Handle specific error codes
  if (result.error.code === 'TRADE_ACCESS_DENIED') {
    // User needs to grant trading permissions
  } else if (result.error.code === 'BROKER_ERROR') {
    // Broker-specific error - check details
  }
}

For more details on error handling, see the Error Handling guide.

Next Steps

Now that you can place orders:

Getting Data - Retrieve orders, positions, and account data
Error Handling - Learn error handling patterns for trading operations
Explore the API Reference - See all available trading methods and broker-specific parameters
Try the Interactive Playground - Test trading operations in your browser