Trading

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.

Typical Trading Workflow

Most trading implementations follow this loop:

1. Submit a new order with placeOrder()
2. Track order status/fills with getOrders()
3. Adjust active orders with modifyOrder()
4. Cancel stale orders with cancelOrder()

Use the Getting Data guide to refresh order state after each action and keep your UI in sync with broker execution status.

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

Parameters

The API and SDK use top-level broker, account_number (or accountNumber), and order. The order object does not include the account identifier—it is supplied at the top level only, consistent with Modify Order below.

Required (top-level): broker (string), account_number / accountNumber (string or number), order (object). Standard order fields (required in order): orderType, assetType, action, timeInForce, symbol, orderQty. Common optional fields (all brokers): limitPrice / price, stopPrice, expireTime (GTD; ISO 8601).

The SDK and API use a discriminated union on broker: when you set broker, your IDE and the API accept different optional fields in order. Use the tabs below for per-broker parameters and examples; the API Reference shows the full schema per broker.

Per-broker parameters and examples

Modify Order

Modify an existing order (e.g., change the limit price or quantity). Pass broker, accountNumber, orderId, and an order object with only the fields you want to change (partial update).

Note: Include only the fields you want to change in the order object (partial update). The API merges your changes with the existing order.

Cancel Order

Cancel an existing order. Pass broker, accountNumber, and orderId (the broker's order identifier).

Response Format

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

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:

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

Next Steps

Now that you can place orders:

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