API

Mit der API steuern eigene Programme deine Chains und holen deine Alarme ab: ein Bot, ein Dashboard oder ein Skript, das morgens die Alarme der Nacht in eine Tabelle schreibt. Anders als beim Webhook, den Bellchain bei jedem Alarm aufruft, fragt dein Programm hier selbst; es braucht dafür keine öffentliche Adresse. Die API gibt es ab dem Plan Trader. Über sie arbeitet auch der MCP-Server für KI-Assistenten.

Schlüssel anlegen

Unter Einstellungen in der Karte API wählst du die Rechte, gibst dem neuen Schlüssel einen Namen, etwa „Mein Bot“, und klickst Schlüssel erstellen:

• Nur lesen (Vorgabe): Konto, Chains, Alarme, Vorlagen und Kurse lesen und Replays rechnen. Geheime Einstellungen der Chains sieht so ein Schlüssel nie. Gut für Dashboards und KI-Assistenten.
• Lesen und ändern: dazu Chains anlegen, aktivieren und pausieren. Für Bots und Skripte, die etwas schalten sollen.

Der Schlüssel beginnt mit bc_ und erscheint nur dieses eine Mal: Kopier ihn gleich und bewahr ihn auf wie ein Passwort. Danach zeigt die Karte nur noch seine Rechte, die letzten vier Zeichen und wann er zuletzt benutzt wurde. Schlüssel von vor dem 21.10.2026 dürfen lesen und ändern, so wie bisher.

Bis zu fünf Schlüssel, am besten einen je Programm. Widerrufen (Mülleimer) sperrt einen Schlüssel sofort. Endet Trader, antwortet die API nicht mehr; deine Schlüssel kannst du trotzdem widerrufen.

Achtung

Der Schlüssel gehört nur auf deinen Rechner oder Server, nie in eine Webseite, ein öffentliches Repository oder einen Chat. Wer einen Schlüssel „Lesen und ändern“ hat, kann deine Chains anlegen, aktivieren und pausieren. Ist er doch einmal draußen, widerruf ihn und leg einen neuen an.

Anmelden

Jede Anfrage schickt den Schlüssel im Kopf Authorization:

curl -H "Authorization: Bearer bc_…" https://app.bellchain.app/api/v1/account

Dieselben Endpunkte gibt es auch unter https://api.bellchain.app/v1/…, etwa https://api.bellchain.app/v1/account. Antworten sind JSON. Zeiten stehen in UTC als ISO 8601, etwa 2026-10-20T08:00:00.000Z. Ohne oder mit falschem Schlüssel antwortet die API mit 401, ohne Trader mit 403, und ein Schlüssel „Nur lesen“ bekommt beim Ändern 403 mit read_only_key.

Endpunkte

Methode und Pfad	Wirkung
GET /api/v1/account	Plan, aktive Chains und Grenze, Zeitraum fürs Replay (replayDays), Sprache, Zeitzone und die Rechte des Schlüssels (access: read oder full). Gut, um einen Schlüssel zu prüfen.
GET /api/v1/chains	alle Chains mit status (draft, active, paused), Märkten, Revisionen und lastAlertAt
GET /api/v1/chains/{id}	eine Chain, dazu ihre gespeicherte Fassung im Chain-Format (definition), ihre Bausteine in Sätzen (summary) und ihre Geheimnisse (secrets)
POST /api/v1/chains	eine Chain aus einer Vorlage mit eigenen Werten oder als Preisalarm anlegen, als Entwurf (Lesen und ändern)
POST /api/v1/chains/{id}/activate	aktivieren oder gespeicherte Änderungen übernehmen, mit denselben Prüfungen wie in der App (Lesen und ändern)
POST /api/v1/chains/{id}/pause	pausieren (Lesen und ändern)
GET /api/v1/alerts	Alarme der letzten 90 Tage, neueste zuerst
GET /api/v1/alerts/{id}	ein Alarm mit „Warum?“: welche Bedingungen wahr waren und welche Werte hineinliefen
GET /api/v1/templates	die Vorlagen der Galerie mit Plan, Markt und Ergebnis ihres Tests
GET /api/v1/templates/{id}	eine Vorlage mit allen Einstellungen zum Anpassen (parameters) und Tipps
POST /api/v1/replay	wie oft eine Chain, eine Vorlage mit eigenen Werten oder ein Preisalarm ausgelöst hätte
GET /api/v1/markets/quote	aktueller Kurs eines Paars (?pair=BTC/USDT) mit Hoch und Tief der letzten 7 Tage

Aktivieren und pausieren

Ohne Body nimmt activate die zuletzt gespeicherte Fassung; mit {"revision": 3} nur genau diese, sonst kommt 409. Geht es nicht, etwa weil der Plan keine weitere aktive Chain erlaubt, antwortet die API mit 422 und nennt die Gründe:

{ "error": "not_activatable", "message": "…", "problems": [{ "code": "limit", "message": "…" }] }

Gibt es ein Paar an der gewählten Börse nicht, heißt der Code pair, und message schlägt passende Paare vor, wie in der App. Liefert die Börse ihre Paare gerade nicht, wird die Chain trotzdem aktiv; dann steht ein Hinweis in warnings.

curl -X POST -H "Authorization: Bearer bc_…" https://app.bellchain.app/api/v1/chains/Xy12ab/activate
curl -X POST -H "Authorization: Bearer bc_…" https://app.bellchain.app/api/v1/chains/Xy12ab/pause

Geheimnisse in Chains

Adressen von Webhooks, Discord, Slack, Teams und Google Chat, Tokens und Codes der Trading-Bots sind Geheimnisse: Wer sie kennt, kann selbst dorthin senden. GET /api/v1/chains/{id} nennt sie unter secrets (Baustein, Einstellung und Name), ihre Werte stehen aber nur mit einem Schlüssel „Lesen und ändern“ in definition. Mit ?secrets=omit lässt die API sie auch dann leer, wie der Export zum Weitergeben im Editor; secretsOmitted sagt, ob sie fehlen. Setzen lassen sich Geheimnisse nur in der App, nicht über die API.

Vorlagen und neue Chains

GET /api/v1/templates/{id} nennt unter parameters jede Einstellung der Vorlage mit Baustein, Wert, Grenzen, Auswahl und Erklärung. Daraus baut POST /api/v1/chains eine eigene Chain, wie Vorlage verwenden in der App, in der Sprache deines Kontos:

{
  "template": "dip",
  "name": "ETH Dip",
  "pair": "ETH/USDT",
  "timeframe": "1h",
  "settings": { "k1": { "value": 30 } },
  "once": false
}

• pair gilt für die Kerze von Vorlagen mit einem Paar, timeframe für alle Kerzen. Scanner bekommen ihre Coins mit pairs.
• settings setzt einzelne Einstellungen: Baustein → Einstellung → Wert. Jeder Wert wird geprüft wie im Editor.
• once: nach dem ersten Alarm pausieren.

Statt template legt priceAlert einen Preisalarm an, wie der Dialog in der App:

{ "priceAlert": { "pair": "BTC/USDT", "kind": "below", "value": 60000, "channels": ["telegram"] } }

kind ist above (steigt über), below (fällt unter), rise oder fall (um value Prozent in window: 1m, 5m, 15m, 1h, 4h oder 24h, Standard 24h). Ohne channels geht der Alarm an den ersten eingerichteten Kanal (Telegram, dann Push, dann E-Mail). coins oder top ({"count": 20, "quote": "USDT"}) machen aus rise und fall einen Scanner.

Die neue Chain ist ein Entwurf (201, status: "draft") und läuft erst nach activate; dort gelten die Grenzen deines Plans. Die Antwort nennt unter plan den kleinsten Plan, mit dem sie sich aktivieren lässt, und unter warnings etwa eine Kursmarke, die schon überschritten ist.

Replay

POST /api/v1/replay rechnet wie Replay starten im Editor und legt nichts an. Die Chain kommt aus deinem Konto ({"chainId": "Xy12ab"}, ihre gespeicherte Fassung) oder entsteht wie beim Anlegen aus template oder priceAlert; days wählt den Zeitraum, Standard 90, höchstens replayDays.

{
  "name": "BTC Dip-Käufer",
  "days": 90,
  "source": "live",
  "market": { "exchange": "…", "pair": "ETH/USDT", "timeframe": "1h" },
  "alerts": 7,
  "heldByCooldown": 2,
  "firstAlertAt": "2026-07-30T13:00:00.000Z",
  "lastAlertAt": "2026-10-17T09:00:00.000Z",
  "recent": [{ "time": "2026-10-17T09:00:00.000Z", "price": 2412.5, "message": "…" }]
}

recent nennt die zehn jüngsten Alarme. Ist die Börse nicht erreichbar, rechnet das Replay mit gespeicherten Beispielkursen; dann steht "source": "fixtures" da und ein Hinweis in notice. Ein Scanner zählt je Coin (coins).

Alarme abrufen

Parameter	Bedeutung
since	nur Alarme ab diesem Kerzenschluss (einschließlich), ISO 8601 oder Millisekunden
chain	eine oder mehrere Chains, durch Komma getrennt
limit	1 bis 100, Standard 50
cursor	der Wert next der vorigen Antwort, für die nächste Seite

{
  "alerts": [
    {
      "id": "Xy12ab.1792429200000",
      "chainId": "Xy12ab",
      "chainName": "BTC Dip-Käufer",
      "time": "2026-10-18T17:00:00.000Z",
      "test": false,
      "pair": "BTC/USDT",
      "timeframe": "1h",
      "price": 77788,
      "quote": "USDT",
      "message": "BTC Dip-Käufer: RSI unter 30",
      "values": [{ "label": "RSI 14", "value": 27.69, "text": "27,69" }],
      "deliveries": [{ "channel": "telegram", "outcome": "sent" }, { "channel": "push", "outcome": "muted", "reason": "quiet_hours" }],
      "moves": [{ "afterMs": 3600000, "percent": 0.5 }, { "afterMs": 14400000, "percent": -1.2 }, { "afterMs": 86400000, "percent": null }]
    }
  ],
  "next": "…"
}

• exchange nennt die Börse aus der Kerze der Chain, als Kennung wie in ihrer Auswahl.
• deliveries sagt je Kanal, wie es ausging: sent, failed, held, muted, pending oder logged, mit Grund wie auf der Seite Alarme, etwa quiet_hours in deinen Ruhezeiten.
• moves ist die Kursveränderung danach in Prozent, je Zeitspanne in Millisekunden; null, solange die Zeit noch nicht um ist.
• Alarme eines Scanners tragen "scanner": true. Jeder Coin ist ein eigener Alarm: pair nennt ihn, und id endet auf ihn, etwa Xy12ab.1792429200000.ETH_USDT. Die Chain selbst hat dann das Feld scanner mit Kerze und Paaren, wie im Chain-Format; bei Top N mit top und unter pairs den Coins von heute, und markets nennt deren Märkte.

Ein Programm, das neue Alarme abholt, fragt etwa jede Minute mit since gleich der Zeit des letzten Alarms und überspringt Alarme, deren id es schon kennt.

GET /api/v1/alerts/{id} liefert einen Alarm mit why, wie Warum? auf der Seite Alarme: je Bedingung auf dem Weg zur Aktion den Satz, ob sie wahr war (state), und die Werte, die hineinliefen (inputs). Gerechnet wird mit der Fassung, die heute läuft; consistent: false heißt, dass die Chain seitdem geändert wurde.

Grenzen

• Höchstens 120 Anfragen pro Minute je Schlüssel; darüber kommt 429 mit Retry-After: 60. Davon höchstens 10 Replays pro Minute und 30 neue Chains pro Stunde.
• Bis zu fünf Schlüssel je Konto.
• Alarme reichen 90 Tage zurück, wie auf der Seite Alarme.
• Die API ist für Programme auf deinem Rechner oder Server gedacht. Aus dem Browser einer anderen Seite geht sie nicht (kein CORS).

Fehler

Status	error	Bedeutung
400	bad_body, bad_since, bad_pair	Anfrage unvollständig, Text in message
401	unauthorized	Schlüssel fehlt, ist falsch oder widerrufen
403	plan_no_api	ohne Trader
403	read_only_key	der Schlüssel darf nur lesen
404	not_found, template_not_found	die Chain, der Alarm oder die Vorlage gibt es nicht (mehr)
409	conflict	die Revision passt nicht; die aktuelle Chain steht in chain
413	too_large	der Body ist größer als 64 KB
422	not_activatable	aktivieren geht nicht, Gründe in problems
422	invalid_setting, unknown_node, unknown_setting, secret_setting, invalid_chain …	ein Wert für die neue Chain passt nicht; bei invalid_chain die Prüfmeldungen in issues
422	no_channel, channel_not_ready	für den Preisalarm ist der Kanal noch nicht eingerichtet
429	rate_limited	zu viele Anfragen
503	no_data, busy	Replay: keine Kurse oder gerade zu viele lange Replays

message ist ein Satz für Menschen in der Sprache deines Kontos; dein Programm entscheidet am besten anhand von Status und error.