<!-- Public documentation export; not library implementation source. -->
# Trading overview

Trading adds an order ticket, an account manager (orders, positions and account summary), an optional depth-of-market panel, and orders and positions drawn on the chart, where they can be dragged to modify them. It is built on the Lumen Charts trading platform, which is open source under the Apache License 2.0 ([source on GitHub](https://github.com/lumenchartshq/trading-platform)). Every Lumen Charts build includes it. There is no separate add-on to buy.

The chart never talks to a broker on its own. You write a broker adapter that connects to your broker or backend, and the chart calls it to read accounts, orders and positions and to place, modify and cancel orders. The adapter follows the widely used broker API shape, so an existing adapter written for that shape connects without changes.

## What ships where

| Part | What it is | How you get it |
| --- | --- | --- |
| Trading runtime | The order ticket, account manager, depth panel and on-chart trading, as `assets/chart-trading.js` and `assets/chart-trading.css` | Included in every release. The chart downloads it only when you call `loadTrading()` |
| Trading platform package (open source) | Broker and datafeed types, a simulated broker and a conformance kit for testing your adapter | `npm install @lumencharts/trading-platform` |
| Broker adapter | Your connection to the broker: accounts, orders, positions, executions and quotes | Your application |

You don't need the npm package to use trading in the chart. The broker types are also in the chart's `lumen_charting_library.d.ts`. The package is useful for testing your adapter, and for building trading screens outside the chart.

## Connect a broker

Pass a broker factory and its configuration when you create the widget, then load trading once the chart is ready:

```ts
const widget = new LumenChartingLibrary.widget({
  container: 'chart',
  library_path: '/lumen_charting_library/',
  symbol: 'NASDAQ:AAPL',
  interval: '1D',
  datafeed,
  broker_factory: host => createBrokerAdapter(host),
  broker_config: {
    configFlags: { supportPositions: true, supportClosePosition: true, supportOrderBrackets: true },
  },
});

widget.onChartReady(() => {
  widget.loadTrading().catch(showTradingError);
});

// When the page or component goes away:
widget.remove();
```

`broker_factory` receives the host services (push updates for orders, positions and executions, connection status, notifications and formatters) and returns your adapter. `broker_config` declares what your broker supports: order types, brackets, durations, custom ticket fields and account manager layout. Features you don't declare stay off.

`loadTrading()` downloads the trading runtime, checks it matches the core build and connects your adapter. It rejects if the widget has no `broker_factory`. A failed load can be retried. Removing the widget disconnects the broker session and releases the runtime.

### Prices and depth

Quotes for the order ticket and the depth panel come from your datafeed's quote and depth methods. The depth panel also needs the `dom_widget` feature, Level 2 support from your broker, and bulk cancellation.

### Session options

`trading_session` is a Lumen Charts extension for hosts that need more control: a stable `settingsKey` so account table choices survive a reload, your own clock, market-data or formatter ports, and broker extensions such as a close-position preview.

```ts
trading_session: {
  settingsKey: 'my-broker',
  extensions: {
    previewClosePosition: request => adapter.previewClose(request),
  },
},
```

Credentials, pending commands and order or position snapshots are never saved.

## How orders are confirmed

A resolved broker promise only means the request was sent. The chart waits for your adapter to push the updated order or position before it treats a command as done, and it never resends a command on its own. If no confirmation arrives within ten seconds, the ticket says it is still checking with the broker and keeps asking your adapter to reconcile for up to a minute. Push every change through the host's update methods, including changes made outside the chart.

## Test your adapter

The open-source package has a simulated broker for demos and tests, and a conformance kit that runs acceptance scenarios against your adapter:

```bash
npm install --save-dev @lumencharts/trading-platform
```

```ts
import { createDeterministicBroker } from '@lumencharts/trading-platform/mock';
import { runConformance } from '@lumencharts/trading-platform/conformance';

// A simulated broker with its own clock and prices, for demos and tests.
const simulated = createDeterministicBroker({ profile: 'equity-net' });
// Pass simulated.brokerFactory and simulated.brokerConfig to the widget.

// Run the acceptance scenarios against your adapter. setup() returns your
// broker factory and config, a market-data port, and a tradable symbol with
// a price and quantity to trade.
const report = await runConformance({ name: 'my-broker', setup: () => createMyConformanceSetup() });
console.log(`${report.passed} passed, ${report.failed} failed, ${report.skipped} skipped`);
```

Each result names the scenario, its outcome, and the broker calls it observed, so a failure points at the call to fix.

---
Documentation page: https://docs.lumencharts.com/charting-library/trading/