> ## Documentation Index
> Fetch the complete documentation index at: https://docs.quanux.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Automate trading workflows with n8n

> Use the QuanuX n8n extension to trigger alerts, log trades to external systems, and build risk workflows visually — no custom application code required.

n8n is a visual workflow automation tool. The QuanuX n8n integration lets you react to trading events — position changes, order fills, risk threshold breaches — and connect them to external systems like databases, notification services, spreadsheets, or custom webhooks. You build the workflow logic visually in n8n's editor; QuanuX provides the bridge that feeds real-time trading events into it.

The integration runs as a QXP sidecar extension located at `extensions/n8n`. It is a Go-based bridge that connects to the QuanuX core over a local key-authenticated channel and forwards events to your n8n instance.

## How it works

The n8n extension subscribes to internal QuanuX events and forwards them to n8n as webhook payloads. From there, n8n takes over: you can route events through any of n8n's 400+ integrations, apply conditional logic, enrich data, and trigger actions — all without writing application code.

```mermaid theme={null}
graph LR
    QC[QuanuX Core] -- events --> EXT[n8n Extension]
    EXT -- webhook --> N8N[n8n Workflow Engine]
    N8N --> SYS[External systems]
```

**Example use cases:**

* Send a Telegram or Slack message when a position is opened or closed
* Log every filled order to a Google Sheet or database
* Trigger a risk halt workflow when a daily loss threshold is breached
* Send an email summary of the day's trades at market close

<Note>
  The n8n workflow editor and server run separately from QuanuX. You are responsible for running your own n8n instance — either locally, via the n8n cloud service, or self-hosted on a server. QuanuX only provides the bridge that connects to it.
</Note>

## Setup

<Steps>
  <Step title="Start your n8n instance">
    If you do not already have n8n running, start it locally with Docker or npm:

    <CodeGroup>
      ```bash Docker theme={null}
      docker run -it --rm \
        -p 5678:5678 \
        -v ~/.n8n:/home/node/.n8n \
        n8nio/n8n
      ```

      ```bash npm theme={null}
      npx n8n
      ```
    </CodeGroup>

    n8n is available at `http://localhost:5678` by default. Create a webhook trigger node in n8n and note the webhook URL — you will configure the extension to send events to that URL.
  </Step>

  <Step title="Generate a bridge key">
    Generate a key so the extension can authenticate to the QuanuX core:

    1. Open the QuanuX web interface.
    2. Go to **Settings → QuanuX Extensions**.
    3. Click **Generate Key**.
    4. Store the key in the OS keyring:

    ```bash theme={null}
    quanuxctl secrets set QUANUX_N8N_BRIDGE_KEY "your_generated_key_here"
    ```
  </Step>

  <Step title="Configure the extension environment">
    Export the bridge key and your n8n webhook URL into your shell:

    ```bash theme={null}
    export QUANUX_BRIDGE_KEY=$(quanuxctl secrets get QUANUX_N8N_BRIDGE_KEY)
    export QUANUX_N8N_WEBHOOK_URL="http://localhost:5678/webhook/your-path"
    ```

    Replace the webhook URL with the one n8n generated for your trigger node.
  </Step>

  <Step title="Start the extension">
    Run the n8n extension from its directory:

    ```bash theme={null}
    cd extensions/n8n
    go run main.go
    ```

    The extension connects to the QuanuX core, subscribes to trading events, and begins forwarding them to n8n as they occur.
  </Step>
</Steps>

## Building workflows in n8n

Once the extension is running, events arrive in n8n as webhook payloads. A typical workflow starts with a **Webhook** trigger node and then branches based on event type or field values.

<Tip>
  Use an **IF** node in n8n to branch on event type — for example, route position open events to a Slack notification and position close events to a spreadsheet logger.
</Tip>

**Suggested workflow patterns:**

<AccordionGroup>
  <Accordion title="Trade alert via messaging">
    1. Add a **Webhook** trigger node — note the URL and set it as `QUANUX_N8N_WEBHOOK_URL`.
    2. Add a **Telegram** or **Slack** node.
    3. Map the event fields (symbol, side, quantity, price) to the message body.
    4. Activate the workflow.
  </Accordion>

  <Accordion title="Trade log to a spreadsheet">
    1. Add a **Webhook** trigger node.
    2. Add a **Google Sheets** node (or **Airtable**, **Notion**, etc.).
    3. Map the order fill fields to the appropriate columns.
    4. Activate the workflow.
  </Accordion>

  <Accordion title="Risk threshold alert">
    1. Add a **Webhook** trigger node.
    2. Add an **IF** node that checks the `daily_pnl` field against your threshold.
    3. On the `false` branch (threshold breached), add a notification node.
    4. Optionally add a second action to call a QuanuX endpoint to halt trading.
    5. Activate the workflow.
  </Accordion>
</AccordionGroup>

## Remote usage

If QuanuX is running on a cloud server and n8n is running locally, configure the extension's webhook URL to point at your local n8n instance's public address or use an ngrok tunnel to expose it:

```bash theme={null}
# Expose local n8n to the internet temporarily
ngrok http 5678
# Use the ngrok HTTPS URL as QUANUX_N8N_WEBHOOK_URL
export QUANUX_N8N_WEBHOOK_URL="https://your-ngrok-subdomain.ngrok.io/webhook/your-path"
```

If n8n is also on the cloud server, set `QUANUX_N8N_WEBHOOK_URL` to the internal address (for example, `http://localhost:5678/webhook/your-path`) so traffic stays within the server.