Connecter Kinetic Flow à n8n

1. Architecture non-custodial

Kinetic Flow ne détient jamais tes clés API. Le screener détecte les fractures énergétiques (E = V · ΔP²) et émet un webhook signé vers ton instance n8n. Ton n8n exécute l'ordre sur Binance avec tes clés.

┌────────────────┐   HMAC webhook    ┌──────────────┐   Signed REST    ┌────────────────┐
│  KINETIC FLOW  │──────────────────▶│  Ton n8n     │─────────────────▶│ BINANCE FUTURES│
│  (détection)   │  X-Kinetic-*      │  (exécution) │  API-Key + HMAC  │  (execution)   │
└────────────────┘                   └──────────────┘                  └────────────────┘

2. Vérification HMAC-SHA256

Chaque webhook porte deux headers : X-Kinetic-Signature (HMAC-SHA256 hex) et X-Kinetic-Timestamp (Unix seconds). La signature couvre `${timestamp}.${raw_body}`. Vérifie-la avant tout appel Binance.

import crypto from "node:crypto";

// n8n Function node — verify signature BEFORE placing any order.
const secret = $env.KINETIC_HMAC_SECRET;
const signature = $json.headers["x-kinetic-signature"];
const timestamp = $json.headers["x-kinetic-timestamp"];
const raw = JSON.stringify($json.body);

// Reject replays older than 5 minutes.
if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) {
  throw new Error("Stale timestamp — replay attack blocked");
}

const expected = crypto
  .createHmac("sha256", secret)
  .update(`${timestamp}.${raw}`)
  .digest("hex");

if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
  throw new Error("Invalid HMAC signature");
}

return $json.body;

Sans vérification HMAC, un attaquant peut spoofer des signaux et vider ton compte. C'est non négociable.

3. Payload de référence

{
  "event": "kinetic.signal",
  "version": "1",
  "id": "sig_01HXYZ...",
  "timestamp": 1751443200,
  "symbol": "SOLUSDT",
  "side": "LONG",
  "energy": 118420.5,
  "threshold": 42000,
  "kms": 94,
  "price": 168.42,
  "mode": "live"
}

4. Mode testnet Binance

Avant tout capital réel, exécute pendant 7 jours minimum sur le testnet Binance Futures. Zéro risque, données réalistes.

1. Crée un compte sur testnet.binancefuture.com et génère des clés API testnet.
2. Dans n8n → node Binance, pointe la baseURL sur https://testnet.binancefuture.com.
3. Dans Kinetic Flow → header → mets le webhook en mode Test. Aucun ordre live n'est émis.
4. Observe 7 jours : latence webhook, taux de rejet HMAC, PnL simulé. Passe en Live uniquement si tout est vert.

5. Checklist sécurité (12 points)

Coche chaque point avant de basculer en Live. Une seule case non cochée = risque de perte totale.

• Clé API Binance en lecture + trading Futures uniquement (jamais Withdraw).
• IP-whitelist ton serveur n8n dans les paramètres API Binance.
• Stocke KINETIC_HMAC_SECRET dans les credentials n8n, jamais en clair dans le workflow.
• Active la vérification HMAC dans le Function node avant TOUT order.
• Rejette les timestamps > 5 min (protection replay).
• Utilise timingSafeEqual, pas === (protection timing attack).
• Démarre en mode testnet Binance pendant 7 jours minimum.
• Limite chaque trade à 1–2 % du capital (risk sizing).
• Toujours poser un stop-loss dans le même workflow que l'entrée.
• Log chaque exécution (Sheets / Notion) pour audit et fiscalité.
• Alerte Slack/Telegram en cas d'échec HMAC ou d'ordre rejeté.
• Rotate KINETIC_HMAC_SECRET tous les 90 jours depuis /app.

6. Troubleshooting

401 Invalid HMAC signature

Le secret n8n ne correspond pas à celui affiché dans ton dashboard. Rotate depuis /app puis recolle-le dans n8n.

Stale timestamp

Horloge serveur désynchronisée. Active NTP : timedatectl set-ntp true.

Binance -2015 Invalid API key

Vérifie que Futures est activé sur ta clé et que l'IP de ton n8n est whitelistée.

Doublons d'ordres

Utilise le champ id du payload comme clé d'idempotence — stocke-le dans un node Set + condition If.