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

# n8n Integration Guide

> Step-by-step guide to connect AIOKA signals to n8n workflows — Telegram alerts, Discord notifications, and more.

## Overview

n8n is an open-source workflow automation platform. Connect AIOKA to Telegram, Discord,
Slack, email, or any webhook destination — without writing code.

**Tier:** Basic (\$49/mo) 🔒
**Endpoint:** `GET /v1/integrations/zapier/signal`
**Poll interval:** 5 minutes (respects 60s server-side cache)

***

## Quick Start — Import the Template

The fastest way to get started is to import the pre-built workflow template.

<Steps>
  <Step title="Download the workflow template">
    Download [n8n-workflow.json](/integrations/n8n-workflow.json) and save it locally.
  </Step>

  <Step title="Open n8n and import">
    In your n8n instance:

    1. Go to **Workflows** in the sidebar
    2. Click **+ Add Workflow**
    3. Click the **⋮** menu → **Import from File**
    4. Select the downloaded `n8n-workflow.json`
  </Step>

  <Step title="Set your API key credential">
    The workflow uses an HTTP Request node with a header credential:

    1. Open the **HTTP Request** node
    2. Under **Authentication**, click **Create New Credential**
    3. Set **Header Name:** `X-API-Key`
    4. Set **Header Value:** `aik_basic_YOUR_KEY_HERE`
    5. Save the credential
  </Step>

  <Step title="Configure your Telegram bot (optional)">
    If you want Telegram alerts:

    1. Open the **Telegram** node
    2. Click **Create New Credential**
    3. Enter your **Bot Token** and **Chat ID**
    4. Customize the message template if desired
  </Step>

  <Step title="Activate the workflow">
    Toggle the workflow to **Active**. It will poll AIOKA every 5 minutes and send
    a Telegram message whenever the verdict changes.
  </Step>
</Steps>

***

## Manual Setup

If you prefer to build the workflow from scratch:

### 1. Schedule Trigger

Add a **Schedule Trigger** node:

* **Trigger at:** Every 5 minutes

### 2. HTTP Request — Fetch AIOKA Signal

Add an **HTTP Request** node:

* **Method:** `GET`
* **URL:** `https://api.aioka.io/v1/integrations/zapier/signal`
* **Authentication:** Header Auth
  * **Name:** `X-API-Key`
  * **Value:** `aik_basic_YOUR_KEY`

### 3. Store Last Verdict ID

Add a **n8n Static Data** node (or a **Set** node writing to workflow static data):

```
lastVerdictId = {{ $json.id }}
```

### 4. IF Node — Check for New Verdict

Add an **IF** node:

```
{{ $json.id }} is not equal to {{ $workflow.staticData.lastVerdictId }}
```

**True branch** → New verdict detected, continue to notification\
**False branch** → Same verdict, stop

### 5. Update Stored ID

After the IF (true branch), add a **Code** node:

```javascript theme={null}
$workflow.staticData.lastVerdictId = $input.item.json.id;
return $input.item;
```

### 6. Send Telegram Message

Add a **Telegram** node:

* **Operation:** Send Message
* **Chat ID:** `YOUR_CHAT_ID`
* **Text:**

```
🤖 AIOKA Verdict: {{ $json.verdict }} ({{ $json.confidence }}% confidence)

📊 Regime: {{ $json.regime }}
🌊 Dark Pool: {{ $json.dark_pool }}/100
📈 RSI: {{ $json.rsi }}
👻 Ghost Trader: {{ $json.ghost_status }}

🕐 {{ $json.readable_time }}
```

***

## Response Fields Reference

| Field           | Type   | Description                                                                                  |
| --------------- | ------ | -------------------------------------------------------------------------------------------- |
| `id`            | string | SHA-256\[:16] deduplication key — changes on new verdict                                     |
| `verdict`       | string | `STRONG_BUY` / `BUY` / `ACCUMULATE` / `HOLD` / `REDUCE` / `SELL` / `STRONG_SELL` / `PENDING` |
| `confidence`    | float  | Judiciary composite confidence 0–100                                                         |
| `regime`        | string | Current HMM market regime                                                                    |
| `dark_pool`     | int    | OTC/institutional flow score 0–100                                                           |
| `rsi`           | float  | BTC 1H RSI(14)                                                                               |
| `ema_200`       | float  | BTC 1H EMA(200)                                                                              |
| `btc_price`     | float  | Live BTC spot price                                                                          |
| `ghost_status`  | string | `WAITING` or `IN_POSITION`                                                                   |
| `timestamp`     | string | ISO 8601 with Prague TZ offset                                                               |
| `readable_time` | string | Human-readable Prague CEST/CET time                                                          |

***

## Example: Discord Notification

Replace the Telegram node with a **Discord** node:

* **Operation:** Send Message
* **Message:**

```
**AIOKA** | {{ $json.verdict }} @ {{ $json.confidence }}% confidence
Regime: {{ $json.regime }} | Dark Pool: {{ $json.dark_pool }}/100
{{ $json.readable_time }}
```

***

## Example: Google Sheets Logging

Append every verdict change to a spreadsheet for historical tracking:

1. After the IF node (true branch), add **Google Sheets → Append Row**
2. Map columns:
   * **A:** `{{ $json.timestamp }}`
   * **B:** `{{ $json.verdict }}`
   * **C:** `{{ $json.confidence }}`
   * **D:** `{{ $json.regime }}`
   * **E:** `{{ $json.btc_price }}`
   * **F:** `{{ $json.id }}`

***

## Troubleshooting

| Symptom          | Cause                    | Fix                                                                 |
| ---------------- | ------------------------ | ------------------------------------------------------------------- |
| HTTP 401         | Missing or wrong API key | Check `X-API-Key` header value                                      |
| HTTP 403         | Free tier key            | Upgrade to Basic at [aioka.io/pricing](https://aioka.io/pricing)    |
| HTTP 429         | Rate limit exceeded      | Reduce poll frequency — 5 min is the recommended minimum            |
| Duplicate alerts | Deduplication not wired  | Add the IF node checking `id` field                                 |
| Always same `id` | Verdict hasn't changed   | This is expected — `id` only changes when AIOKA issues a new ruling |

***

## Related

* [Zapier Quick Start](/api-reference/integrations/zapier)
* [GET /v1/integrations/zapier/signal](/api-reference/integrations/zapier)
* [API Keys](/api-reference/keys/generate)