Install and enable

The addon installs like every other Bicrypto extension: buy it, activate the licence, let the updater unpack it, restart. What follows that is the part worth reading, because the order matters. Instruments cannot be activated before a provider is active, a provider cannot be activated before its credentials are in .env, and live trading cannot be switched on before either of those exist.

Nothing here touches ScyllaDB. This addon stores everything in MySQL and uses Redis for provider cool-offs, the chart cache and the engine lease.

Before you start

• A working Bicrypto install — see Core install
• Shell access to the app server, because credentials go in .env and the backend has to be restarted to read them
• A market-data provider account whose plan includes WebSocket streaming
• Decided which countries you will refuse — the geo-block list defaults to US, CA and applies the moment the extension is live

1. Install and activate the extension

Buy the product, then activate it under Admin → System → Extensions, or run the updater from the shell. On the next backend boot the extension's models sync and its tables appear:

fx_provider              market-data vendors (one active at a time)
fx_execution_provider    A-book hedge venues (many may be enabled)
fx_instrument            the tradable catalog
fx_symbol_group          dealing-desk config per group of symbols
fx_session_calendar      trading-hours calendars
fx_account_group         account tiers (margin call, stop out, NBP)
fx_account               customer trading accounts
fx_order                 orders, market and pending
fx_position              open and closed positions
fx_deal                  the immutable money ledger
fx_routing_rule          A-book placement-time routing overrides
fx_execution_alert       the operator alert inbox
fx_economic_event        economic calendar
fx_market_news           terminal news feed

The addon's admin lives at /admin/forex-trading and its customer terminal at /forex-trading/trade. Both appear under Admin → Extensions once the extension row is active.

2. Add a market-data credential

Pick one provider and add its variables to .env:

APP_TWELVEDATA_API_KEY=
APP_FINNHUB_API_KEY=
APP_TRADERMADE_API_KEY=
APP_POLYGON_API_KEY=

Restart the backend afterwards — the provider manager reads process.env and nothing reloads it.

Which one to choose, what each plan actually includes, and how to validate a key before you write it into .env is covered in Market data providers. Read that page before you pay anyone: four of the five vendors paywall the WebSocket, and without a WebSocket this addon cannot quote a tradable price.

3. Activate the provider

Go to Admin → Forex Trading → Market Data → Providers (/admin/forex-trading/provider).

Activation is single-active by design: one feed owns the marks that fills are priced against, so turning one on turns every other one off. Before it commits, the endpoint does three things:

1. Refuses if the adapter is not implemented in this release.
2. Refuses if the credentials are absent from the environment.
3. Runs a live credential check, then probes the quote stream for up to 12 seconds.

The stream probe does not block activation — a socket can be transiently down — but its verdict rides out on the response. If you see "WARNING: the quote stream did not connect", stop and fix that before going further. Everything downstream will look like it is working and will refuse every order.

4. Import the instrument catalog

On the same page, press Import Instrument Catalog.

Two separate things happen:

Seeding. The addon creates its curated catalog if it is missing — three session calendars (FX 24/5, US Stocks RTH, CME Metals & Energy), seven symbol groups (FX Majors, FX Crosses, Metals, Energy, US Stocks, Indices (ETF), Crypto CFDs) and around 86 instruments: 7 FX majors, 21 crosses, gold, silver, WTI, Brent, 50 US large caps, 4 index ETFs and 2 crypto CFDs. Everything is created INACTIVE with correct contract specifications. Existing rows are never modified, so re-running this is safe and never overwrites your tuning.

Linking. It then pulls the active provider's instrument list and writes the matching provider-side symbol onto each catalog row. Matching is keyed by asset class and pair, deliberately: matching on the pair alone once linked the WTI crude contract to a same-named US penny stock and quoted crude at $3.66 forever.

The response tells you what did not match. Pay attention to strandedActive — those are instruments already live for customers that this provider cannot quote. They will go silent.

5. Enable the instruments you want to offer

Admin → Forex Trading → Market Data → Instruments. Everything is INACTIVE until you promote it.

The lifecycle is deliberately one-way in places, so that you cannot strand a customer holding an open position:

Activation is refused unless the instrument carries a symbol mapping for the currently active provider. A mapping for some other, now-inactive vendor does not count; that check exists because such instruments activate cleanly and then either stream nothing or fall through to a heuristic guess.

INACTIVE and DELISTED are refused while open positions exist. Take a market away through CLOSE_ONLY and wait for it to empty.

Start small. Ten liquid FX pairs plus gold is a complete product; 86 instruments is a wide surface to watch on day one.

6. Review the desk configuration

Market Data → Symbol Groups carries your economics. The seed defaults are conservative but they are defaults, not recommendations:

There are no account groups seeded. Without one, accounts fall back to a margin-call level of 100% and a stop-out level of 50%. If you want ESMA-style tiers, offshore leverage, or negative-balance protection turned off, create account groups before you take a live customer — see Instruments, groups and sessions.

7. Switch on live trading

Admin → Forex Trading → Settings (/admin/forex-trading/settings).

Until this is on, customers can still get a demo account and trade paper money — that is the funnel and it works out of the box. Live accounts cannot be created, funded or traded.

While you are on this screen, check the other tabs:

• Risk & Data — quote staleness thresholds (10s for FX, 30s for stocks).
• Accounts — which account currencies customers may pick. Defaults to USD, EUR. The currency is fixed for the account's lifetime.
• Compliance — the geo-block list (US, CA by default) and the leveraged trading risk disclosure.

Full definitions are in the settings reference.

8. Confirm the scheduled jobs are running

Admin → System → Cron. Six jobs are registered under the forex_trading category. Two of them move money:

9. Smoke test on demo

Do this before you tell anyone the desk is open.

Production checklist

• Provider activated and the stream probe reported success
• Catalog imported; strandedActive empty
• Only the instruments you intend to support are ACTIVE
• Symbol groups reviewed — spread markup, leverage, commission, swap policy
• At least one account group exists, with a defaultForType for LIVE
• Geo-block list saved deliberately (an empty saved list blocks nobody; a deleted row resurrects the US, CA default)
• Risk disclosure decision made
• All six cron jobs green
• fxTradingDelayedStocksTradable left off unless your plan genuinely streams real-time equities
• Notification templates reviewed under Admin → System → Notifications: FxTradingDepositConfirmation, FxTradingWithdrawalStatus, FxTradingMarginCall, FxTradingStopOut
• A Super Admin user exists with a working email — every execution alert fans out to Super Admin holders only
• Then, and only then, fxTradingEnabled on

Next

• Market data providers — choosing and wiring the feed
• Instruments, groups and sessions — the catalog and your economics
• The trading terminal — what customers see
• Troubleshooting — when it does not quote