Broker Integration (cTrader)
============================

FTJ supports direct integration with **cTrader** brokers, allowing you to automatically fetch
and import your trades without manually exporting CSV files.

Navigate to **cTrader** in the sidebar to access the Broker Integrations view.


Overview
--------

The broker integration follows four stages:

.. image:: /_static/card_guidebroker.png
   :alt: cTrader connection screen
   :align: center
|
Step 1 - Select Provider
--------------------------

Currently, FTJ supports one broker provider:

- **cTrader**: Works with cTrader-powered brokers (e.g. Pepperstone, IC Markets, FxPro,
  Spotware, and others using the cTrader platform).


.. TODO: Add information about whether more brokers are planned (MT4/MT5, etc.)


Step 2 - Connect to cTrader
-----------------------------

1. Click the **Connect** button.
2. A browser window opens asking you to log in to your cTrader account and authorize FTJ.
3. Select your accounts that you want FTJ to access and click **Allow access**.
4. After successful authentication, the status changes from **Disconnected** to **Connected**.

The connection uses **OAuth 2.0**. FTJ stores an access token and refresh token securely locally. FTJ does not store passwords.



.. TODO: Replace with a screenshot showing the "Connected" state.

**Status Log**

A collapsible **Status Log** panel shows the authentication flow and any errors. Click **Copy**
to copy the log contents for troubleshooting.

.. note::
   An internet connection is required for broker authentication and trade fetching.


Step 3 - Link Accounts
------------------------

After connecting, you need to link your cTrader broker account(s) to FTJ journal accounts.

1. Select a **Broker Account** from the dropdown - this lists all accounts visible in your
   cTrader profile (both live and demo).
2. Select a **Journal Account** from the dropdown - this is the FTJ account where imported
   trades will be stored.
3. Click **Link Accounts**.

The linked account pair appears in the **Your Linked Accounts** section below. You can link
multiple broker accounts to different journal accounts.

.. image:: /_static/placeholder_link_accounts.png
   :alt: Account linking interface
   :align: center

.. TODO: Replace with a screenshot showing a linked account pair.

To remove a link, select it and click **Remove**.

.. important::
   The **base currency** of your FTJ journal account must match the **deposit currency**
   of your cTrader broker account. If the currencies differ, FTJ shows a
   **Currency Mismatch** warning explaining that P&L figures will be recorded in a
   different currency than your journal expects, which can skew statistics and reports.
   Linking mismatched accounts is unsupported and will produce incorrect P&L values.


Step 4 - Fetch & Import
-------------------------

Click **⟳ Fetch Executions** to download deals from all linked accounts. Executions stream
into a preview table where you can filter by date, symbol, side, or account and select which
rows to keep. Click **Import Selected** to save the checked executions - FTJ deduplicates,
validates P&L, derives trades automatically, and shows a summary of what was imported.


Troubleshooting
---------------

**"Disconnected" after being connected:**
OAuth tokens expire. Click **Connect** again to re-authenticate. FTJ will attempt to refresh
the token automatically, but if the refresh token has also expired, you'll need to log in again.

**Trades not appearing after fetch:**
Check that:

1. The correct broker account is linked to the correct journal account.
2. There are closed deals within the last 365 days.
3. The Status Log does not show any errors.

**Duplicate trades:**
FTJ uses a five-level deduplication cascade based on broker external IDs and execution
fingerprints. Re-fetching and re-importing the same deals will not create duplicates.