Trading

Place, modify, and cancel account-scoped orders with authorization and idempotency.

After a user grants trading access, you can place, modify, and cancel orders through Finatic's account-scoped routes. The route accountId is the financial account ID returned by account APIs, not the tenant companyAccountId.

Requirements

Every trading command requires:

An active account grant with canTrade: true.
A valid financial accountId.
Broker-specific fields from the account's order schema.
An idempotency key for the write command.

Important: Read access does not authorize trading. If canTrade is false, send the user back through Connect and request trading access for that account.

Basic workflow

Confirm the selected account grant has canTrade: true.
Fetch GET /api/v1/accounts/{accountId}/order-schemas?action=place.
Submit { order: { ... } } with an idempotency key.
Check accepted and the embedded order snapshot.
Track state with listOrders or webhooks.
Read fills and events from the same account-scoped order route family.
Modify or cancel only while the provider and returned schema permit it.

Request and response shape

{
  "broker": "robinhood",
  "order": {
    "orderType": "market",
    "assetType": "equity",
    "action": "buy",
    "timeInForce": "day",
    "symbol": "AAPL",
    "orderQty": 1
  }
}

broker is optional. When present, it must match the account grant's broker.

A successful command returns an FDXBrokerOrderCommandResult:

{
  "action": "PLACE",
  "accepted": true,
  "executionStrategy": "CANCEL_REPLACE",
  "order": {
    "orderId": "ord_123",
    "status": "PENDING",
    "legs": []
  },
  "clientOrderId": "partner-order-123",
  "supersededOrderId": null,
  "message": null
}

executionStrategy describes how Finatic handled the command:

Value	Meaning
`CANCEL_REPLACE`	The provider contract requires cancel plus replacement, for example Robinhood
`NATIVE_MODIFY`	The provider supports same-ID modification, for example TradeStation or eToro position SL/TP
`ASYNC_COMMAND`	MT4/MT5 queues the command to the customer's EA and waits for an acknowledgement

For ASYNC_COMMAND, the embedded order can receive the EA ticket as brokerOrderId after acknowledgement. Handle MT_COMMAND_TIMEOUT and MT_COMMAND_REJECTED explicitly; accepted: true by itself is not final execution proof.

Order field schemas

Fetch the provider schema at runtime instead of hard-coding a matrix:

const schema = await finatic.v1.getAccountOrderSchema({
  accountId: 'account_123',
  action: 'place',
});

Supported actions are place, modify, and cancel. The response includes supportedOrderTypesByAssetClass and provider-specific field requirements.

{
  "supportedOrderTypesByAssetClass": {
    "equity": ["market", "limit", "stop", "stop_limit", "trailing_stop"],
    "option": ["market", "limit"]
  }
}

Event Contract eligibility

Use the generated Client SDK contract for Event Contracts. Do not reuse an equity enum, infer support from a provider-wide trading flag, or treat catalog visibility as permission to trade.

import {
  FDXAssetType,
  type AccountOrderSchemaResponse,
  type FinaticAPIErrorResponse,
} from '@finatic/client';

const response = await finatic.v1.getAccountOrderSchema<AccountOrderSchemaResponse>({
  accountId,
  action: 'place',
});
const capability = response.success?.data.eventContract;
const canOpen =
  capability?.publicEnabled === true &&
  capability.accountEntitled === true &&
  capability.closingOnly !== true;

if (canOpen) {
  await finatic.v1.createAccountOrder({
    accountId,
    idempotencyKey: crypto.randomUUID(),
    body: {
      order: {
        assetType: FDXAssetType.EventContract,
        symbol: selectedEventContractSymbol,
      },
    },
  });
}

Treat a missing capability, disabled public access, missing account entitlement, or closingOnly: true as a hard block on opening orders. A closing-only account can close an existing position only when the returned account schema permits that exact action.

For a FinaticAPIErrorResponse, show the attempted operation, stable error code, and safe trace or correlation reference. Never render raw provider bodies, stack traces, tokens, credentials, or account identifiers.

Provider restrictions

Broker	Entry order types	Modify behavior
Alpaca, Webull, Tastytrade, NinjaTrader, Trading 212	Use `supportedOrderTypesByAssetClass`	Use the returned provider capability and schema; do not infer behavior from transport type
Robinhood	Use `supportedOrderTypesByAssetClass`	Cancel-replace (`CANCEL_REPLACE`)
TradeStation	Use `supportedOrderTypesByAssetClass`	Native same-ID modify (`NATIVE_MODIFY`)
eToro	`market` and `limit` by asset class	Position SL/TP uses `modifyTarget: position_sl_tp`; other modifies use cancel-replace
MT4 / MT5	`market`, `limit`, and `stop` only	Async EA commands (`ASYNC_COMMAND`); a registered connector is required

For eToro, fetch the place schema because payloads use instrumentId and amount or units instead of a universal symbol and orderQty pair. MT commands can wait up to 90 seconds for a ticketed acknowledgement.

Place an order

const result = await finatic.v1.createAccountOrder({
  accountId: 'account_123',
  idempotencyKey: 'partner-order-123',
  body: {
    order: {
      orderType: 'market',
      assetType: 'equity',
      action: 'buy',
      timeInForce: 'day',
      symbol: 'AAPL',
      orderQty: 1,
    },
  },
});

if (!result.success?.data?.accepted) {
  console.error(result.error, result._id);
}

Select an exact instrument

When a read returns instrument.finaticInstrumentId, send that opaque value as finaticInstrumentId inside the provider order payload. instrumentId remains the provider-native identifier for providers that require it. If both are sent, they must resolve to the same instrument within the authorized account and provider.

Never derive a canonical ID from a product root such as MGC, parse MGCZ6, or substitute another contract month. Fetch the descriptor through the same authorized account/provider path used for placement.

Modify an order

Pass only changed fields inside order and use a new idempotency key for this distinct command.

const result = await finatic.v1.modifyAccountOrder({
  accountId: 'account_123',
  orderId: 'order_123',
  idempotencyKey: 'partner-order-123-modify-1',
  body: {
    order: {
      orderQty: 2,
      limitPrice: 185.25,
    },
  },
});

For eToro position stop-loss or take-profit updates, include modifyTarget: position_sl_tp and positionId. Native modifies return NATIVE_MODIFY; cancel-replace can return supersededOrderId.

Cancel an order

const result = await finatic.v1.cancelAccountOrder({
  accountId: 'account_123',
  orderId: 'order_123',
  idempotencyKey: 'partner-order-123-cancel-1',
});

Track the order

const orders = await finatic.v1.listOrders({
  accountId: 'account_123',
  limit: 50,
});

const fills = await finatic.v1.getAccountOrderFills({
  accountId: 'account_123',
  orderId: 'order_123',
});

Error handling

Missing trading permission: The grant does not have canTrade: true.
Idempotency conflict: Reuse a key only for the exact same command; preserve it while reconciling a timeout.
Broker rejection: Use stable error details without exposing raw provider bodies.
Market restriction: The market, instrument, or asset is not currently tradable.

Log traceId with your own order ID and idempotency key. Never blindly retry a write with a new key.

Next steps

Getting Data — read orders, fills, and events.
Webhooks — subscribe to order lifecycle events.
Error Handling — handle terminal and retryable failures.

Command Palette