# Use BTCMatic with n8n

_Last updated: August 2026_

Exchanges are blind to the chain and generic automation tools are Bitcoin-blind. BTCMatic is the Bitcoin senses of your n8n workflows: the on-chain event engine, backtesting and guarded execution stay here — orchestration is yours. Every rule fire can be delivered to n8n as a **signed webhook**, and from there anything n8n can reach is fair game: a Google Sheets portfolio log, a Discord or Slack announcement, a Home Assistant scene, your accounting system.

## The verified community node

`n8n-nodes-btcmatic` (https://www.npmjs.com/package/n8n-nodes-btcmatic) is a **verified n8n community node**. On **n8n Cloud**, search for "BTCMatic" on the canvas and drag it in; on self-hosted, install it under Settings → Community Nodes. It ships two nodes:

- **BTCMatic Trigger** — starts a workflow on every rule fire. It registers its own URL as a webhook endpoint, stores the one-time signing secret, and verifies every delivery's HMAC itself — no manual Webhook + Code node pair needed.
- **BTCMatic** (action) — manage rules (list, create dry-run, pause/resume), read fires and order history with evaluation traces, run backtests, and create or post to inbound hooks.

The credential is an API key (Pro/Power — see below) plus the base URL `https://api.btcmatic.com`. Everything below documents the raw contract, which the node implements for you — read on if you prefer plain Webhook/HTTP nodes or another automation tool.

## How it works

1. **Register a webhook endpoint.** In Settings → Channels, add your n8n webhook URL as an endpoint. You get a **signing secret exactly once** at registration — store it in your n8n workflow. Endpoints must be `https` and publicly reachable.
2. **Create the n8n trigger.** Add a **Webhook** node (HTTP Method `POST`, Options → Raw Body **on**) and use its production URL as the endpoint you registered in step 1.
3. **Point a rule at it.** Give any rule a `webhook` action — or attach one under `on_action_result` to be notified when an order fills. Dry-run fires deliver exactly like live ones, flagged `"simulated": true`.
4. **Verify every delivery.** Check the HMAC signature before acting (snippet below).

**Self-hosted n8n?** Deliveries go through an SSRF-guarded fetch that refuses private, LAN and link-local addresses, and endpoints must be `https`. An n8n instance on your home network is unreachable by design — expose it behind a public HTTPS hostname (a reverse proxy or tunnel works). n8n Cloud URLs work out of the box.

## The delivery contract

| Property | Behavior |
|---|---|
| `X-BTCMatic-Signature` | `t=<unix seconds>,v1=<HMAC-SHA256 hex>` — the HMAC of `"<t>.<raw body>"` with your endpoint secret. Reject timestamps outside ±5 minutes. This format is frozen; it will not change. |
| `X-BTCMatic-Delivery` | The claim key of the fire — **stable across retries**. Use it as your idempotency key: if you have seen the value before, skip the item. |
| Retries | Non-2xx responses and timeouts are retried with backoff, up to 6 attempts, then dead-lettered with a notification to you. A redelivery carries a fresh `t` and signature; the delivery header stays the same. |
| Response | Answer with any 2xx quickly — the delivery has a 5-second timeout. Do slow work after responding (the n8n Webhook node default of responding immediately is correct). |

## Payload

The body is JSON and always carries the full evaluation trace — not just _that_ the rule fired, but every condition leaf with the metric value it saw. `outcome` is present only on order-result follow-ups:

```json
{
  "claim_key": "rul_01KXGEQNFNV8BJG9F70MBJ01JW:2026-07-22T14:03:00.000Z",
  "rule_id": "rul_01KXGEQNFNV8BJG9F70MBJ01JW",
  "rule_name": "dip buyer",
  "event": { "event_id": "evt_…", "type": "price_tick", "source": "binance:BTCUSDT", "ts": "2026-07-22T14:03:00.412Z" },
  "trace": {
    "evaluated_at": "2026-07-22T14:03:00.415Z",
    "leaves": [
      { "metric": "price_change_pct", "window": "24h", "op": "<=", "threshold": -5, "value": -5.4, "passed": true }
    ]
  },
  "outcome": { "status": "filled", "price": 64100.5, "amount": 0.00015, "simulated": true }
}
```

## Verifying the signature in n8n

Place a **Code** node directly after your Webhook node: parse `t=<unix>,v1=<hex>` from `x-btcmatic-signature`, reject timestamps more than 300 s from now, compute HMAC-SHA256 of `"<t>.<raw body>"` with your secret and compare in constant time. On **n8n Cloud**, Code nodes expose neither `require('crypto')` nor the Web Crypto API — use the dependency-free variant (https://btcmatic.com/integrations/n8n/verify-signature.js) with an inlined HMAC-SHA256, verified byte-for-byte against Node's `crypto`. It also runs unchanged on locked-down self-hosted instances.

## Template workflows

- TradingView signal + cheap-fee gate (community node): https://github.com/btcmatic-com/n8n-nodes-btcmatic/tree/main/templates/tradingview-fee-gate — a TradingView alert wakes a rule that only fires when the technical signal _and_ a cheap next-block fee hold, decided by the engine with an auditable trace.
- Discord fire announcements: https://btcmatic.com/integrations/n8n/btcmatic-discord-alert.json
- Google Sheets portfolio log: https://btcmatic.com/integrations/n8n/btcmatic-sheets-portfolio-log.json
- Home Assistant trigger: https://btcmatic.com/integrations/n8n/btcmatic-home-assistant.json

Each plain-node workflow starts with the Webhook + verification pair using the dependency-free variant; replace the placeholder secret and credentials with your own.

## Inbound: wake rules from n8n or TradingView

Create an **inbound hook** under Settings → Channels and you get a delivery URL (`POST /hooks/{id}/{token}`). POST a **flat JSON object** to it — a TradingView alert, an n8n HTTP node, plain curl — and any of your rules with the _Incoming webhook_ trigger wakes up. Every top-level string/number field of the body becomes a condition metric (`{"signal": "buy", "strength": 7}` lets a rule say `strength > 5`), and `received == 1` matches every delivery. The contract:

- Body fields: flat `snake_case` keys, string or number values (booleans as 0/1). Nested JSON is rejected with a precise error — never silently dropped.
- `X-BTCMatic-Idempotency` (optional): redeliveries with the same id collapse into one logical event.
- `X-BTCMatic-Signature: t=<unix>,v1=<hex>` (optional, same HMAC format as our outbound deliveries, ±5 min): verified whenever present. TradingView cannot send headers — the URL token alone authenticates it.
- Webhook-triggered rules require a throttle — a flapping sender cannot double-fire.

## Programmatic access: API keys

Pro and Power plans can mint scoped API keys (Settings → API keys). A key opens the management surface — rules, fire history, backtests, hooks, dry-run automation — and **cannot** create a live order rule, touch billing, exchange keys or channels. Use it from n8n HTTP nodes as `Authorization: Bearer btcm_…` — or let the verified community node handle it; the full OpenAPI spec lives at https://api.btcmatic.com/docs.

## Direction of trust

The trust model survives both directions: BTCMatic pushes signed, traced events out, and anything coming _in_ — a webhook delivery, an API-key call — can at most **wake** a rule or manage dry-run automation. Execution decisions are made only by the BTCMatic engine, with its own condition evaluation, claims and guardrails, and live order rules can only ever be enabled from this app — see https://btcmatic.com/security.

---

Canonical page: https://btcmatic.com/integrations/n8n  
Machine index: https://btcmatic.com/llms.txt · Agent notes: https://btcmatic.com/agents.md