FCS Trading Chart

Run the Demo in 5 Steps

The shortest path to a working trading chart: start the sample broker server on your machine, open the example page, and place a test order. You need Node.js with npm and the sample broker server included with your broker package.

Step 1: Set Your Feed Keys

The server uses the fcsapi price feed, the same prices the chart shows. Otherwise a Stop Loss could fire at a price the customer never saw. It needs two keys, and they are not interchangeable. Set them in config.js, or as environment variables (the environment variable wins when both are set).

Step 2: Install and Start the Server

cd sample-broker-server
npm install
npm start

npm start runs node server.js. The server listens on ws://localhost:6161 and prints the adapter settings to use in the chart. For another port run PORT=8080 node server.js.

Step 3: Open the Example Page

Open test-trading-platform.html from your package in the browser. In its script, ADAPTER_MODE is set to 'ws', so it connects to ws://localhost:6161 with accountId: 'usr12'. The sample auth.js accepts the token already set in that page.

The account is stored in users/user_usr12.json. For an account id with no file, the sample storage.js creates one with a balance of 10000 USD and leverage 100.

Step 4: Place a Test Order

Step 5: Check Multi-Tab Sync

Open the same page in a second browser window. Place an order in one window and the other window updates without a reload. Every connection of one account receives the same pushes from the server.

No Server Yet?

Set ADAPTER_MODE to 'demo' in the example page (this passes adapter: 'demo' to mountTradingPlatform). The chart then runs paper trading inside the browser, stored in localStorage, with a starting balance of 10000 and leverage 100. Nothing reaches a server, and Stop Loss and Take Profit only run while the tab is open. Use it to evaluate the UI, not to test your integration.

If Something Does Not Work

Two Integration Paths

There are two ways to put trading on the chart. Path A mounts the built-in trading platform and connects it to a broker server. Path B loads only the broker API, and you draw your own trades on the chart from your existing trading UI. Pick one before you write code.

Comparison

Path A: What You Load

<link rel="stylesheet" href="dist/fcsapi-chart.css"/>
<link rel="stylesheet" href="dist/fcsapi-chart-trading.css"/>

<script src="dist/fcsapi-chart.js"></script>
<script src="dist/fcsapi-chart-broker.js"></script>
<script src="dist/fcsapi-chart-trading.js"></script>

The trading script adds chart.mountTradingPlatform(options) to the chart. Load the chart script and the broker script before it: chart.on('ready') and chart.on('symbolChange'), used to mount the panel and keep it on the chart symbol, come from the broker script. The adapter option decides where orders go:

Path B: What You Load

<link rel="stylesheet" href="dist/fcsapi-chart.css"/>

<script src="dist/fcsapi-chart.js"></script>
<script src="dist/fcsapi-chart-broker.js"></script>

The broker script adds the methods you drive from your own UI: addDrawing, updateDrawing, removeDrawing, getDrawings and clearDrawings for trade lines, getCandle, getCandles and getPip for price data, and chart.on() / chart.off() for the events ready, tick, symbolChange, periodChange and drawing. Buy and sell markers come from the chart script itself: addMarker, removeMarker and clearMarkers.

How to Choose

Best Way to Add Trading: Let an AI Model Do the Work

The fastest and safest way to connect this chart to your own system is to give an AI coding assistant the code, the documents and the example page, and let it do the work while you answer its questions.

Why use an AI model

A trading integration touches several files: the login check, storage, handlers, settings, alerts and the chart page. An AI coding assistant reads all of them in minutes and keeps them consistent. It does the repetitive work, such as connecting your database, replacing the test login, setting spread and commission, and wiring alerts. You only decide the business rules. The sample broker server is organised for this: the files you edit are few and clearly marked, and core/ stays untouched.

Use any coding assistant that can read your folder, edit files and run commands, for example Claude Code, Cursor or the agent mode of GitHub Copilot.

What to give the AI

Set it up in 5 steps

Let the AI ask the questions

Do not start with "build me a broker". The instruction file makes the AI interview you first and wait for your "yes" before it edits anything. Typical questions:

Rules that keep it safe

You still review it

An AI can make mistakes, and this code handles money. Read the changes in handlers.js, storage.js and auth.js yourself. Place a test order with Stop Loss and Take Profit, close it, reload the page and check the balance. When it works, go through the Production Checklist.

Later: updates

Your changes live outside core/. When a newer package arrives, replace core/ and ask the AI to compare your files with the new document/README.md.

Path A: Built-in Trading Platform

Path A adds a complete trading screen to the chart: order form, positions, pending orders, history, balance history, journal and account details. You load the chart files and call one method. You do not build any trading UI yourself.

Working example: test-trading-platform.html in the chart package. It connects to the sample broker server at ws://localhost:6161.

Step 1: Load the files

Load the files in this order. The broker script adds chart.on() events. The trading script adds chart.mountTradingPlatform().

<link rel="stylesheet" href="fcsapi-chart.css"/>
<link rel="stylesheet" href="fcsapi-chart-trading.css"/>

<div id="fcs_chartparent">
    <div id="fcs_chart"></div>
</div>

<script src="fcsapi-chart.js"></script>
<script src="fcsapi-chart-broker.js"></script>
<script src="fcsapi-chart-trading.js"></script>

Step 2: Mount the platform

Create the chart as usual. Wait for the ready event, check that your user is logged in, then mount. The panels are built around the chart inside fcs_chartparent, so that element must have a defined height.

chart.on('ready', () => {
    // Check YOUR user login here before mounting.
    chart.mountTradingPlatform({
        adapter: { type: 'ws', url: 'wss://trade.yourbroker.com', token: 'USER_SESSION_TOKEN', accountId: 'usr12' },
        layout:  'right'
    });

    // Keep the order form on the symbol the chart is showing
    chart.on('symbolChange', ({ symbol }) => chart.tradingSetSymbol(symbol));
});

mountTradingPlatform() returns the platform instance. Calling it again removes the previous one first. chart.unmountTradingPlatform() removes it.

Adapter: where orders and balances come from

WebSocket is the only real-broker transport. There is no REST adapter.

Mount options

Every option is optional. With no options you get the demo adapter and the default layout.

Layout rules

Connection handling

Path B: Broker API Only, Build Your Own GUI

Use this path when you already have your own order form and position tables and only need the chart. Load the chart and the broker script, without the trading script. Your system keeps the orders. The chart shows what you send it (entry, Stop Loss and Take Profit lines, trade markers) and reports what the user does on the chart through events.

Load the Scripts

Load the chart first, then the broker extension. The broker script adds the drawing, data and event methods below to every FCSAPIChart instance. Use the path where you host the chart files.

<link rel="stylesheet" href="fcsapi-chart.css">
<script src="fcsapi-chart.js"></script>
<script src="fcsapi-chart-broker.js"></script>

Events

Subscribe with chart.on(event, callback). Remove one listener with chart.off(event, callback), or all listeners of an event with chart.off(event).

Methods

The standard chart methods also work, for example setSymbol(), setPeriod() and exportImage(). See the chart documentation.

Drawing Options

Options of addDrawing() and updateDrawing(). Only type is required.

Extra options per type: fibonacci accepts levels, levelColors and visibleLevels. note and pricelabel accept backgroundColor, borderColor, borderRadius and padding. A note needs text. A pricelabel shows the price when text is empty, and accepts showPointer.

Markers

A marker is a small icon pinned to one candle, for example a buy sign where the order was filled. Set price to the candle low to place it below the bar, or high to place it above.

const c0 = chart.getCandle(0);
chart.addMarker({
    id: 'trade-marker',            // needed to remove it later
    timestamp: c0.timestamp, price: c0.low,
    type: 'buy', color: '#26a69a',
    lock: true                      // user cannot move or delete it
});
chart.removeMarker('trade-marker');

Marker types:

Let the User Drag a Stop Loss Line

Leave lock off so the line can be dragged, and set lockDelete so it cannot be deleted. When the user drops the line, the drawing event fires with type: 'moved' and the new price in e.drawing.price. Send that price to your own server. The example on the right shows the full flow.

Running the Sample Broker Server

The sample broker server is a Node.js WebSocket server that the trading chart connects to. It keeps the accounts, positions and orders, fills orders at the live FCS price, and fires stop-loss, take-profit and margin stop-out on the server, even when the customer has closed the chart. Run it as it is first, then change a small set of files to connect your own database, login and business rules.

Requirements

The server must use the same FCS price feed as the chart. Otherwise SL/TP would fire at prices the customer never saw.

Install and Start

cd sample-broker-server
npm install

# set your two FCS keys in config.js (wsKey + restKey),
# or pass them as environment variables (see below)

node server.js          # listens on ws://localhost:6161

npm start runs the same command. To use another port: PORT=8080 node server.js.

At start the server prints the core version, the active socket transport, the line FCS sample broker WS server running on ws://localhost:6161, and the adapter settings (url, token, accountId) that the sample login accepts.

Now open test-trading-platform.html from the chart folder (online copy). It connects to ws://localhost:6161 with accountId: 'usr12'. Place a trade, then open the page in a second browser window. Both windows stay in sync, because the server pushes every change to all open connections of that account.

The Files and What Each One Is For

What You Edit: handlers.js and config.js

config.js holds values. Change a number, save, restart. A restart drops every customer socket, so once you are live, put the values you change during market hours in settings/broker-settings.json instead. Only these keys can be changed there: askBid, commission, commissionOnClose, tradingMode, qtySizing, stopOutLevel, maxOpenPositions, maxPendingOrders, enforceMarketHours, checkTradeable, brokerCurrency. Everything else (ports, keys, limits, currency settings, audit log) needs a restart, and the server refuses to boot if you put another key in the JSON file.

A key in broker-settings.json replaces the config.js value as a whole. It is not merged. For example, an askBid with only spreadPips drops the perSymbol block from config.js. The server logs the dropped sub-keys.

handlers.js holds logic. Every chart request is already implemented in core/handlers-base.js. Your file spreads that base and overrides only what is really yours:

const { base } = require('./core/handlers-base');

module.exports = {
  ...base,

  // Your rule first, then let the base do the mechanics
  async placeOrder(ctx) {
    if (await myRisk.isBlocked(ctx.accountId)) return ctx.fail('symbol_not_allowed');
    return base.placeOrder(ctx);
  },
};

Anything you do not list keeps the base implementation, so a request type added in a later release works with no edit. Do not copy a base function into handlers.js without changing it: the copy replaces the base for good, and later fixes to that function will not reach you.

What Must Stay Untouched: core/

Never edit a file inside core/. A value you configure belongs in config.js or settings/. The code that reads that value belongs in core/. Because none of your work lives in core/, an upgrade is: replace core/ and the chart dist/ folder, then restart. A release does not touch server.js, config.js, handlers.js, storage.js, auth.js, admin.js, events.js or settings/.

If your own files live somewhere else (a database-backed storage module, for example), pass them in server.js instead of editing core/:

const boot = require('./core/boot');
boot.start({ storage: require('./my-db-storage') });

config, handlers, storage and auth are required. admin, events and transport are optional: leave one out and that feature stays off (for transport, the default ws package is used).

Environment Variables

Ports and secrets can be set from the environment, so you do not commit them. A value from the environment wins over the value in config.js.

Production: Run It Under PM2

If the process stops, SL/TP and stop-out stop for every customer. On a fatal error the server logs it and exits, and it expects a process supervisor to start it again. The included PM2 process file, pm2_server.config.js, does this:

pm2 start pm2_server.config.js
pm2 logs broker_server
pm2 restart broker_server
pm2 save            # survive reboots (after: pm2 startup)

The process is named broker_server. It restarts automatically, restarts if memory passes 500 MB, and writes to logs/pm2-out.log and logs/pm2-error.log. Set PORT, ADMIN_PORT, ADMIN_HOST, ADMIN_TOKEN, FCS_WS_KEY and FCS_REST_KEY in the env block of that file.

The file runs one instance in fork mode on purpose. Positions, the trigger book (SL/TP and pending order levels) and the price feed live in the memory of that one process. Do not switch to cluster mode and do not run two copies behind a load balancer.

User Data: Request Flow and Required Formats

The chart is a thin client. It sends a request over the WebSocket. Your broker server decides, saves and replies, then pushes the change to every open tab of that user. This section shows that round trip and the exact shape of the account, position, order and history records the chart panels expect.

How a request flows

Requests of the same account run one at a time, in order, so two orders can never spend the same margin. Different accounts run in parallel. You can watch the whole flow in the live example page.

On connect the chart sends auth first. The server answers authResult, then one snapshot with account, positions, orders, the newest 100 history rows and the FX pins. The panels fill without extra requests. Older history is fetched with getHistory and the filters symbol, limit, fromTime and toTime. Frame formats are in Protocol Reference.

Per-user state shape

This is the one record storage.js reads and writes per account. The sample keeps it in users/user_<id>.json; you keep it in your database. The storage can change, the shape must stay the same.

{
  "account":        { ... },   // one object      -> account panel and balance widget
  "positions":      [ ... ],   // open positions  -> Positions tab and lines on the chart
  "orders":         [ ... ],   // pending orders  -> Orders tab
  "history":        [ ... ],   // closed trades   -> History tab
  "balanceHistory": [ ... ],   // optional ledger -> Balance History tab
  "custom":         { ... }    // optional arrays for your own tabs, keyed by tab name
}

account (object)

positions[] (open positions)

The server stamps the economics on each position when it opens. The price engine keeps currentPrice, pnl and pnlPercent live and pushes them as positionsPriced every config.positionPushMs (default 2000 ms). The chart shows these values as sent and does not recompute them.

The sample server also stores rawPrice, spreadRevenue and _profile (the symbol profile used at open) on each position. Keep them in your database: _profile lets margin and P&L be computed again after a restart.

orders[] (pending limit and stop orders)

The order the chart sends

placeOrder arrives as ctx.data.order. A market order replies with the new position; a limit or stop order replies with the pending order.

history[] (closed trades)

New rows go to the start of the array, so history is stored newest first.

balanceHistory[] and custom{}

balanceHistory is your real ledger, returned newest first by getBalanceHistory. Each entry has id, type, a signed amount (plus is a credit, minus is a debit), balance (the running balance after the entry), time in milliseconds and a note. The sample server writes deposit and withdraw (Admin API), nbp (negative-balance protection) and reset (demo reset). It does not add a row per trade; use trade and fee for your own entries. The panel sums deposit and withdraw rows into its totals.

custom holds arrays for your own tabs, keyed by tab name. The chart asks for one with getData and data.type set to the tab key, and fills the columns of your template.

Account ids

The account id is the key for the open sockets, the request lock and the price engine that watches SL/TP. It is checked at login and never rewritten.

storage.isValidAccountId('usr12')        // true
storage.isValidAccountId('usr12_demo')   // true
storage.isValidAccountId('alice@b.com')  // false: @ and . are not allowed
storage.isValidAccountId('Usr12')        // false: uppercase is not allowed

// the rule:  /^[a-z0-9_-]{1,64}$/

An id outside this rule gets { "v": 1, "type": "authResult", "ok": false, "error": "invalid_account_id" } and the socket is closed with code 4002. If your user ids are emails or contain uppercase letters, issue a separate trading account id or convert them before they reach the chart.

Changes made outside a handler

The price engine broadcasts SL/TP hits, pending-order fills, expiries and margin stop-outs for you. For a deposit or withdrawal, call the Admin API POST /admin/balance with { "id", "amount", "note", "token" }. It changes the balance under the account lock, adds the ledger row and pushes account to the open charts. If your own code changes an account, save it, then broadcast the new state:

const protocol = require('./core/protocol');
protocol.broadcast(accountId, 'account', updatedAccount);

WebSocket Protocol Quick Reference

The chart and your broker server talk over one WebSocket with plain JSON messages. This page lists every message the chart sends and every message the server pushes, so you can write the server in any language or check your own server against the sample.

Connection Lifecycle

Message Envelope

Every request has the same outer shape. The payload is inside data. v is the protocol version, currently 1.

// Request (chart to server)
{ "v": 1, "type": "cancelOrder", "reqId": "b3f1c2e0-7d4a-4c1e-9a55-2f6e0c9d1a10",
  "token": "YOUR_SESSION_TOKEN", "accountId": "usr12",
  "data": { "accountId": "usr12", "orderId": "360393_a7" } }

// Reply on success
{ "v": 1, "type": "ack", "reqId": "b3f1c2e0-7d4a-4c1e-9a55-2f6e0c9d1a10",
  "ok": true, "s": "ok", "data": true, "d": true }

// Reply on failure
{ "v": 1, "type": "ack", "reqId": "b3f1c2e0-7d4a-4c1e-9a55-2f6e0c9d1a10",
  "ok": false, "s": "error", "error": "order_not_found", "errmsg": "order_not_found" }

Handshake and Control Messages

Requests (Chart to Server)

The data column is the content of data in the request. The ack.data column is what a successful reply carries. ? marks an optional field.

While connected, the chart answers getAccount, getPositions and getOrders from the snapshot it keeps in memory, so these rarely reach the wire. Your server must still implement them.

closePrice is the price the chart was showing. The sample server does not trust it. It closes at its own live quote with your spread applied, and uses the client value only when it has no quote for that symbol.

The placeOrder Order Object

{ "order": {
    "symbol": "EURUSD",            // the chart also sends "instrument"
    "side": "buy",                 // "buy" | "sell"
    "type": "market",              // "market" | "limit" | "stop"
    "qty": 0.1,
    "price": 1.0852,               // market: the quote the user saw. limit/stop: the trigger price
    "stopLoss": 1.0800,            // or null
    "takeProfit": 1.0900,          // or null
    "trailing": { "mode": "pips", "value": 20 },   // or null
    "expiresAt": null,             // pending orders only: ms epoch when the order expires (GTD), null = no expiry
    "oco": false,                  // pending orders only: when this fills, cancel the other OCO orders on the same symbol
    "slRaw": { "mode": "pips", "value": 50 },      // what the user typed for SL, or null
    "tpRaw": null,                 // what the user typed for TP, or null
    "clientPrice": 1.0852,         // the quote the chart used to compute stopLoss / takeProfit
    "profile": { }                 // the symbol profile from the data feed
} }

A limit or stop order also carries limitPrice or stopPrice with the same value as price. A market order is filled at the server price, not at price. When the two differ, the sample server recomputes SL and TP from slRaw / tpRaw against its own fill price, then checks them again.

Push Events (Server to Chart)

All push events have the shape { "v": 1, "type": "...", "data": { ... } }.

positionsPriced keeps profit and loss moving. The chart only receives prices for the symbol it displays, so on a broker connection it does not compute position P&L itself. It shows the currentPrice, pnl and pnlPercent your server sends for every open position, merged by id, and treats the attached account block as a normal account push. pnlPercent is the return on the position margin.

Close Codes

The server closes the socket with an application code when a connection cannot continue. The chart treats every code from 4000 to 4099 as final and does not reconnect. Any other close is treated as a network problem and retried. The limits.* settings are in config.js.

Error Codes in ack.error

A limit or stop price on the wrong side of the market is refused with a plain sentence such as buy limit must be below market (1.0852); use a buy stop to enter above. The chart also knows the codes invalid_limit_price and invalid_stop_price if your own server returns a code instead.

You can return your own codes from your checks in handlers.js, for example ctx.fail('symbol_not_allowed') or ctx.fail('declined: KYC pending'). The chart picks the text in this order: your errorMessages override for the code, then the detail after the colon, then its built-in wording, then the raw string.

Chart and Trading Settings

You change the trading UI in three places: FCSAPIChart constructor options (toolbar, symbol search, displayed quote), chart.mountTradingPlatform() options (layout, tabs, action buttons, order form), and your own HTML templates and CSS (columns, labels, colors). These settings only change what the customer sees. Your broker server enforces limits, leverage, spread and commission.

Hide Parts of the Chart

These are FCSAPIChart constructor options. Every enable... switch below defaults to true; set it to false to remove that control. The full list is in the Chart API configuration.

Trading Platform Options

Pass these to chart.mountTradingPlatform({ ... }). All are optional.

Order Size Limits

qtySizing sets minQty, maxQty and qtyStep for the order form. The input decimals follow qtyStep.

chart.mountTradingPlatform({
    qtySizing: {
        byType:   { forex: { minQty: 0.01, qtyStep: 0.01 }, stock: { minQty: 1, qtyStep: 1 } },
        bySymbol: { 'TSE:7203': { minQty: 100, qtyStep: 100 } }   // board-lot stock
    }
});

Most specific wins: sizing sent by your broker server for the symbol, then the feed profile, then bySymbol, then byType, then the built-in default (forex and commodity 0.01, crypto 0.0001, stock, fund and futures 1). Your server is the final authority and rejects a wrong size with invalid_qty.

Columns: Your Own Panel Templates

Each table reads its columns from the <thead> of the panel template. <th data-field="key"> is the exact JSON key of the record. Remove a <th> and the column is gone; reorder them and the cells follow. Add one for any field your server sends and it shows; a missing value prints a dash. The <th> text is only a label.

<table class="fcs-table">
  <thead><tr>
    <th data-field="symbol">Instrument</th>
    <th data-field="qty">Volume</th>
    <th data-field="pnl">Profit</th>
    <th data-field="swap">Swap</th>   <!-- any field your server sends -->
    <th></th>                          <!-- empty = action buttons column -->
  </tr></thead>
  <tbody class="fcs-positions-tbody"></tbody>
</table>
<div class="fcs-empty-msg" style="display:none">No open trades</div>

If a template URL cannot be loaded, the built-in panel is used. Keep the hook classes the chart fills: fcs-*-tbody, fcs-empty-msg, and in positions fcs-positions-count and fcs-positions-total-pnl. In positions and orders, one empty <th></th> is the action buttons column; which buttons show is set by positionActions and orderActions. Sample templates are in the my-templates folder of the sample broker server.

Labels and Text

Styling Overrides

Load your stylesheet after fcsapi-chart-trading.css and override only what you need. Keep loading ours so new UI in later releases is styled. Most rebrands only need the CSS variables on .fcs-trading-wrapper:

.fcs-trading-wrapper {
  --fcs-bg: #0d0d12;  --fcs-bg-raised: #16161d;  --fcs-bg-header: #1c1c26;
  --fcs-text: #e8e8f0;  --fcs-muted: #8b8b9a;  --fcs-border: #2a2a38;
  --fcs-input: #22222c;  --fcs-hover: rgba(255,255,255,0.06);
  --fcs-buy: #2e7dff;  --fcs-buy-hover: #1a5fd6;    /* buy buttons, positive P&L */
  --fcs-sell: #ff4d6d; --fcs-sell-hover: #d63356;   /* sell buttons, negative P&L */
}
/* Light chart theme */
.fcs-trading-wrapper.fcs-theme-light { --fcs-bg: #ffffff; --fcs-text: #14141c; }

/* Hide the trailing stop row of the order form */
.fcs-order-form .fcs-of-trail-row { display: none; }

On a light chart the wrapper gets the class fcs-theme-light. Every class starts with fcs- (fcs-of-* is the order form); find them with the browser inspector. Style them freely, but do not rename them.

Displayed Ask/Bid Quote

askBid is an FCSAPIChart constructor option. It changes the ask and bid the chart draws, so the customer sees your dealable quote. Candles are not changed. With a broker server you normally leave it unset: the server sends the spread from its own askBid setting for each symbol the chart loads, and fills at the same value. Use the chart option for demo or offline pages.

For the same setting, price units win over pips, and pips win over percent. Change it at runtime with chart.setAskBid({ base: 'feed', spreadPips: 20 }), always passing a new object. chart.setAskBid(null) returns to the raw feed quote.

Broker Economics: Spread, Commission and Swap

This section covers the settings that earn you money: the spread and markup on the feed price, commission per trade, overnight swap and the currency conversion fee. All of them are set in config.js of the sample broker server and applied on the server. The chart shows the customer the same numbers before the trade.

Where each revenue setting lives

A house default goes in config.js. A value that differs per customer goes on that customer's account record (users/user_<id>.json under account in the sample, your own database in production). A customer with no override gets the house default, so you only record the exceptions.

"Live change" means the key can be overridden in settings/broker-settings.json and takes effect without a restart. A key placed there replaces the whole config.js value. It is not merged, so copy the complete key, not only the field you change.

Spread and markup: askBid

askBid widens the feed price in your favour. A buy fills above the feed ask, a sell fills below the feed bid. The same rule is sent to the chart when a symbol loads, so the quote the customer sees is the price they are filled at.

buy fill  = feed ask + spread + markup
sell fill = feed bid - spread + markup

The amount is applied in full to each side. It is not halved. Examples:

Rules are layered from least to most specific: top level, then byType, then perSymbol, then the customer's own account.askBid (top level, byType, perSymbol). When a more specific layer sets any one of spread, spreadPips or spreadPercent, the other two from lower layers are cleared. So a VIP rule of spreadPips: 1 is never beaten by a house rule of spread: 15. The markup fields work the same way.

The spread earned on a market fill is recorded as spreadRevenue on the position, next to the raw feed price in rawPrice. A pending-order fill records 0. The history row of a closed trade carries the round-trip total in spreadTotal.

Commission

Commission is charged per side and deducted from the balance in the account currency. Pick the base that is fair for the asset: a flat fee suits a forex lot but not one share.

Optional min and max cap the result. They are in the account currency, so on a book with customers in different currencies either use percent without caps or set commission per customer. Set commission: null for no default fee.

// config.js
commission: {
    type: 'per_lot', value: 1,                            // default for everything
    byType: {
        crypto: { type: 'percent', value: 0.1 },          // 0.1% of notional
        stock:  { type: 'percent', value: 0.1, min: 5 }   // 0.1% with a floor of 5
    },
    bySymbol: {
        'PSX:HBL': { type: 'percent', value: 0.2, min: 25 }
    }
},
commissionOnClose: true

The rule is resolved most specific first: the customer's account.commission, then a commission carried on the instrument profile, then config.commission. Inside a block the order is bySymbol, byType, then the flat rule. A byType or bySymbol entry is a complete rule that replaces the default, so a min on the default does not carry over. The fee is stored on the position (commission) and on the history row (commission for the close side, openCommission, commissionTotal).

Swap: overnight financing

A position held past the daily rollover accrues swap. Rates are swap points (pips) per 1.0 lot per night: negative is charged to the customer, positive is credited. long applies to a held buy, short to a held sell. The rate is looked up in bySymbol, then byType. Otherwise there is no swap.

// config.js
swap: {
    enabled: true,
    rolloverHourUTC: 21,     // nightly accrual time (21:00 UTC)
    tripleWeekday: 3,        // 0=Sun ... 3=Wed: this night counts 3 times
    bySymbol: { 'FX:EURUSD': { long: -0.8, short: 0.3 } },
    byType:   { forex:  { long: -0.5, short: -0.5 },
                crypto: { long: -20,  short: -20 } }
}

One night = points * pip size * contract size * point value * quantity, converted to the account currency. Example: 1 lot long FX:EURUSD at -0.8 is -0.8 * 0.0001 * 100000 = -8.00 per night, and -24.00 on the triple night. Accrued swap is kept in the position's swap field and counts in equity while the position is open. On close it moves into the balance and appears in the history row's swap. The total is recomputed from the number of rollovers the position has lived through, so a restart or a repeated run never charges a night twice.

Conversion fee and your reporting currency

Margin, profit and percent commission are calculated in the symbol's quote currency and converted into each customer's account currency. When the two currencies differ, every conversion rate is multiplied by (1 - fxMarkup): 0.005 takes 0.5%, 0 switches it off.

brokerCurrency is the currency of your own books. Commission and spread income is also restated in it as commissionBase and spreadBase on history rows and trade-log lines, with ccy naming the customer's currency. A book with customers in several currencies then adds up. Run node broker-report.js in the server folder to total commission and spread income across all accounts. It reports in USD unless you pass a currency, for example node broker-report.js PKR.

Risk Controls: Leverage, Margin, Stop-Out and Limits

These are the safety rails of the sample broker server: how much leverage a customer gets, how margin is reserved, when the engine force-closes a losing account, how many orders a customer may hold, and when a market order is refused because the market is closed. The server runs these checks when each request arrives.

Where each control is configured

A property of the instrument or of the house is global and lives in config.js. A property of the customer lives on the account record.

Of these, stopOutLevel, maxOpenPositions, maxPendingOrders, enforceMarketHours, tradingMode and qtySizing can be changed on a running server in settings/broker-settings.json. That file is re-read at most once per settings.recheckMs (5000 ms). Everything else in config.js needs a restart. A key that is not allowed in that file stops the server at boot, with the key named in the error.

Leverage

Leverage differs per customer, so it is stored on the account record, not in config.js.

// users/user_<id>.json -> "account"
"leverage": 100,
"leverageByType":   { "stock": 1, "forex": 100, "crypto": 20 },
"leverageBySymbol": { "PSX:HBL": 100 }

Resolved most specific first: leverageBySymbol[symbol], then leverageByType (the feed type, then the asset class such as forex, crypto, stock), then the flat leverage. A spot symbol always uses 1:1. When a record loads, a flat leverage that is missing, zero or not a number is replaced by 1 (1:1), and an invalid leverageByType entry is dropped, each with a console warning. A typo can over-margin an account, never under-margin it. The leverage used is stamped on every position as leverage. The admin operation POST /admin/settings can also change these three fields.

Margin and free margin

required margin = price * quantity * contract size * point value / leverage
                  (converted into the account currency)
equity          = balance + unrealized P&L + accrued swap
free margin     = equity - used margin

Contract size is 100000 for forex and 1 for everything else, unless the instrument profile sets its own. Examples on a USD account: 1 lot EURUSD at 1.0850 with leverage 100 locks 1,085.00. 0.1 BTC at 60,000 with leverage 20 locks 300.00.

Stop-out

stopOutLevel is the margin level, in percent, at which the engine starts closing positions. It acts as the account's stop for positions that have no stop-loss.

margin level = (balance + unrealized P&L of margin positions)
               / margin used by margin positions * 100

The level is computed from live quotes. When it is at or below stopOutLevel, the engine closes the margin position with the largest loss, recalculates, and repeats until the level recovers. Each forced close carries reason: 'margin' on the positionClosed message and on the history row. Example with stopOutLevel: 50: with a balance of 2,000 and 1,085 of margin in use, liquidation starts when the floating loss reaches 1,457.50. The sample has this one threshold and no separate margin-call warning level.

Negative balance protection. With negativeBalanceProtection: true, if a close leaves the account with no open positions and a balance below zero, the balance is reset to zero. The amount you absorbed is written to the balance ledger as an entry of type: 'nbp'. Set it to false only if your customers stay liable for a negative balance.

Spot or margin per instrument

tradingMode decides whether a symbol is leveraged at all. It is global because it describes the instrument, not the customer.

// config.js
tradingMode: {
    byType:   { stock: 'spot' },
    bySymbol: { 'BINANCE:BTCUSDT': 'spot', 'PSX:HBL': 'margin' }
}

Resolved as bySymbol, then byType, then margin. The map is sent to the chart on the watchSymbol reply so the order form matches the server.

Order limits

Market-closed checks

A market execution has to pass two independent gates. Limit and stop orders are never blocked by either gate; they wait for the market to open. Stop-loss, take-profit and stop-out closes fired by the engine are never blocked.

Gate 2 needs no calendar. The session of each symbol arrives with the live WebSocket feed, and a market order is accepted only while that session is the regular market session. If the session has not been reported yet, the order gets market_status_unknown and the customer can retry or place a limit order. Gate 2 runs only when the WebSocket feed is on.

Gate 1 is your own rule per exchange. The exchange is the symbol prefix (PSX:HBL is PSX). An exchange that is not listed is unrestricted, and "*" is a catch-all. The file is re-read while the server runs, within tradingHours.recheckMs. Set tradingHours.enabled: false to skip this gate.

// settings/trading-hours.json
{ "exchanges": {
    "PSX":     { "session": "on", "from": "09:32", "to": "15:30",
                 "tradeoff": ["saturday", "sunday"], "timezone": "Asia/Karachi" },
    "BINANCE": { "session": "on" },
    "FX":      { "session": "on", "tradeoff": ["saturday", "sunday"] }
} }

While tradingHours.enabled is true, the rules file is checked at startup: a missing file or invalid JSON stops the boot. A bad edit made later keeps the last good rules and logs the error.

Adding your own checks

Put house rules such as KYC or a blocked symbol list in handlers.js. Run your check, then hand over to the built-in handler so all the checks above still run:

async placeOrder(ctx) {
    if (await myRisk.isBlocked(ctx.accountId)) return ctx.fail('symbol_not_allowed');
    return base.placeOrder(ctx);
}

Demo Accounts - Practice Trading

A demo account lets a customer trade with practice money. There are two tiers: a browser-only paper account for visitors with no login, and a server-side demo account for signed-up clients. Pick the one that matches who is looking at the chart.

The Two Tiers

Tier 1: Browser-Only Practice

Set adapter to 'demo'. No broker server is needed.

chart.mountTradingPlatform({
    adapter: 'demo'   // paper trading stored in this browser only
});

The chart also uses this adapter when adapter is left out, or when its value is not recognised (for example a ws object with a wrong type). Check the option if a logged-in client sees a 10,000 USD Demo Account.

Tier 1 is acceptable only for anonymous visitors. They have no identity to come back to, so losing the account when browser storage is cleared costs nothing. Once a customer logs in, use tier 2: a client who set a stop loss expects it to fire whether or not the laptop is open.

Tier 2: A Demo Account Is Just an Account

There is no demo subsystem to install and no demo block in config.js. A demo account is a normal account record with a different id. Point the chart at it the same way as a live account:

chart.mountTradingPlatform({
    adapter: {
        type:      'ws',
        url:       'wss://your-broker.example/ws',
        token:     'USER_SESSION_TOKEN',
        accountId: 'usr12_demo'   // the only change vs. this client's live account
    }
});

Everything else already works, because every per-customer condition is read from the account record, not from a mode flag: leverage (pricing.resolveLeverage), commission (resolveCommission), spread (resolveSpreadRule), FX pins (fxOverrides) and the account currency.

The isDemo Flag

isDemo: true on the account record is the only thing that makes an account demo. It is never inferred from the id. usr12_demo is a practice account because its record says so, not because of its name, so your own id scheme works unchanged.

The fail-safe points at Live on purpose. The dangerous mistake is treating a real account as practice money, so anything that is not the boolean true reads Live. Write "isDemo": false on your live records anyway, as users/user_usr12.json and users/template.json do, so the field is visible in the record.

Creating a Demo Record

Copy the client's live record, then change the fields below. Copying is the point: the currency, the leverage (leverage, leverageByType, leverageBySymbol), a per-user askBid spread and a per-user commission are inherited, so the practice account behaves like the real one.

A worked example ships as users/user_usr12_demo.json, next to the live record users/user_usr12.json it was copied from. The code panel shows its fields, with a placeholder name.

Creating the record is your business logic, not the chart's. It is the "Open demo account" button in your client portal. You decide who may have one, how many, with how much practice money and for how long. The sample server has no "create demo account" operation.

Do not rely on the sample's default record. When a valid token connects with an id that has no file yet, the sample storage.ensureAccount() creates a default record: 10,000 USD, leverage 100, name Demo Account. That record has no isDemo flag, so it reads Live and is counted in revenue. Always create demo records yourself with "isDemo": true.

Moving to a Database

There is no demo code path to port, because a demo account is a row like any other. Add one boolean column (for example is_demo, plus owner_id if you want the link to the live client), returned as isDemo in the record your ensureAccount() hands back. Add one WHERE clause, WHERE is_demo = 0, to your revenue and P&L reporting. listAccountIds() stays SELECT id FROM accounts with no demo filter, and so does listRiskRows() if you export it.

The Demo / Live Badge

The account tab's identity strip ends with the account type, so a customer can always tell which money they are trading. Demo is a tinted chip and Live is muted.

Client Name (Demo)  ·  #usr12_demo  ·  PKR  ·  1:1  ·  DEMO
Client Name         ·  #usr12       ·  PKR  ·  1:1  ·  LIVE

The badge is derived from isDemo with the same fail-safe: anything other than the boolean true renders Live. Keep the account type visible somewhere the customer can reach.

Revenue Reporting Excludes Demo

Demo accounts trade the same engine and stamp the same commission and spread as live ones. Without a filter their practice income would land in your real revenue total. broker-report.js skips every account whose record has isDemo === true and prints what it left out:

$ node broker-report.js

  (excluded 1 DEMO account from revenue: user_usr12_demo.json)

BROKER REVENUE REPORT — all amounts converted to USD

It filters on the flag, never on the id: an account called practice_bob with no isDemo is counted. A record that cannot be parsed is never treated as demo, so a broken file is not silently dropped from the books.

Reset, Expiry and Deletion

These use the Admin API, which is server-to-server only. It listens on adminHost:adminPort from config.js (default 127.0.0.1:6162). The token is your adminToken. Send it from your own backend, never from a browser.

curl -X POST http://127.0.0.1:6162/admin/reset \
  -H "Content-Type: application/json" \
  -d '{"id":"usr12_demo","target":100000,"token":"YOUR_ADMIN_TOKEN"}'

Going to Production: Checklist

The sample broker server runs out of the box so you can test the chart with trading. Work through this list before real customers and real money use it. Each item says what to change and why.

Settings (config.js)

Your Business Files

Deployment and Security

Troubleshooting Common Issues

The problems broker developers meet most often, with the cause and the fix. Start with the server log: the server prints a clear line for every start-up failure and every reloaded setting.

The Server Does Not Start

The Chart Cannot Log In

When the server refuses a connection it closes the socket with a code between 4000 and 4099. The chart treats these codes as final and stops reconnecting until the page is reloaded. Other closes (network drops) reconnect automatically, starting after 1 second and backing off up to 30 seconds. The close code is printed in the browser console on a line starting with [WsAdapter].

Orders and Prices

Sync, Stops and Performance

Terms & Disclaimer

What the trading chart and the sample broker server are, and what stays your responsibility as the broker.

Sample Code

The sample broker server is reference code. It shows how a broker back end talks to the FCS Trading Chart. It ships with development defaults: JSON file storage, a development token check, and example prices, limits and trading hours. It is not a finished brokerage system. Review, adapt and test it before any live use.

Your Responsibilities

You operate the server, so you are responsible for everything it does with customer money. This includes order execution, fills, margin and stop-out, account balances, deposits and withdrawals, data storage and backups, security of the server and its keys, and your licensing, regulatory and reporting duties in every country you serve. The chart is a display and an input form. It makes no trading decision.

Market Data and Prices

Prices come from multiple exchanges and liquidity providers. We work to keep them accurate, but data can be delayed, interrupted or different from other sources. Any order your server fills at a price is your decision as the broker.

Trading Disclaimer

Charts, indicators and trading tools are provided for informational purposes only. They are NOT trading advice. We bear NO responsibility for trading losses, missed fills, wrong settings or downtime that result from using the chart or the sample broker server.

License

The broker server is provided under a commercial license. It gives you a non-exclusive, non-transferable right to use, modify and deploy it for your own brokerage operations. It may not be resold, redistributed as a standalone product or sublicensed. The software is provided "AS IS", without warranty of any kind. For white-label or redistribution terms contact sales@fcsapi.com.