Watching the account
Trading 212’s API cannot tell you when something changes: there are no webhooks and no live updates. A watcher asks for you, every few seconds, and reports only what changed since the last time, such as an order filling or cash arriving.
| Watcher | Reports | Permission |
|---|---|---|
watch.orders() |
Orders placed, updated, filled, cancelled, rejected, replaced |
orders:read, history:orders |
watch.positions() |
Positions opened, changed in size, or closed |
portfolio |
watch.cash() |
Cash available, reserved for orders or held in pies changed |
account |
Each reports changes made anywhere, including in the Trading 212 app. The first check only records where things stand, so events start from the second.
With callbacks
Section titled “With callbacks”import { Trading212 } from "@kkkermit/trading212.js";
const t212 = Trading212.fromEnv();const orders = t212.watch.orders();
orders.on("filled", ({ order, fill }) => { console.log( `${order.side} ${order.quantity} ${order.ticker} filled at ${fill?.price ?? "?"}`, );});orders.on("cancelled", ({ order }) => console.log(`Order ${order.id} was cancelled`));orders.on("error", ({ error, willRetry }) => console.error(error.message, willRetry ? "(retrying)" : "(stopped)"),);
// Stop watching after an hour.setTimeout(() => orders.stop(), 60 * 60_000);const { Trading212 } = require("@kkkermit/trading212.js");
const t212 = Trading212.fromEnv();const orders = t212.watch.orders();
orders.on("filled", ({ order, fill }) => { console.log( `${order.side} ${order.quantity} ${order.ticker} filled at ${fill?.price ?? "?"}`, );});orders.on("cancelled", ({ order }) => console.log(`Order ${order.id} was cancelled`));orders.on("error", ({ error, willRetry }) => console.error(error.message, willRetry ? "(retrying)" : "(stopped)"),);
// Stop watching after an hour.setTimeout(() => orders.stop(), 60 * 60_000);on(type, listener) calls listener for every event of that type and returns a function that removes it. The
listener may be async; one that throws is logged and skipped, and the watcher carries on. stop() ends the watcher,
and stopped says whether it has ended.
A filled, cancelled, rejected or replaced event comes from Trading 212’s history, with the fill (its price
and quantity) when there is one. A market order usually fills before any check sees it pending, so it is reported
only as filled. An order that leaves the pending list without the history saying how it ended is reported as
gone after five checks.
Each check reads the newest 50 orders in the history, so orders that settle without ever being seen pending are found only if Trading 212 lists the history newest first. The spec does not say it does; an order that was seen pending is looked up by its ticker either way.
With a loop
Section titled “With a loop”import { Trading212 } from "@kkkermit/trading212.js";
const t212 = Trading212.fromEnv();
// Stops when the signal aborts, here after ten minutes. Leaving the loop with break stops it too.for await (const event of t212.watch.positions({ signal: AbortSignal.timeout(10 * 60_000),})) { if (event.type === "error") console.error(event.error.message); else if (event.type === "opened") console.log(`Opened ${event.position.instrument?.ticker}`); else if (event.type === "closed") console.log(`Closed ${event.position.instrument?.ticker}`); else console.log( `${event.position.instrument?.ticker}: ${event.previous.quantity} -> ${event.position.quantity}`, );}const { Trading212 } = require("@kkkermit/trading212.js");
async function main() { const t212 = Trading212.fromEnv();
// Stops when the signal aborts, here after ten minutes. Leaving the loop with break stops it too. for await (const event of t212.watch.positions({ signal: AbortSignal.timeout(10 * 60_000), })) { if (event.type === "error") console.error(event.error.message); else if (event.type === "opened") console.log(`Opened ${event.position.instrument?.ticker}`); else if (event.type === "closed") console.log(`Closed ${event.position.instrument?.ticker}`); else console.log( `${event.position.instrument?.ticker}: ${event.previous.quantity} -> ${event.position.quantity}`, ); }}
main().catch((error) => { console.error(error); process.exitCode = 1;});A for await loop receives every event in order. Leaving the loop, with break or return, stops the watcher, and so
does aborting the signal you passed, which ends the loop without an error.
Errors
Section titled “Errors”A check that fails is reported as an error event, { type: "error", error, willRetry }:
willRetry: true: a network failure, a timeout, a 5xx or a rate limit. The next check goes ahead as usual.willRetry: false: an error that needs you, such as a missing permission or a key Trading 212 refused. The watcher stops, logs a warning, and a loop over it throws the error.
Every failed request also reaches the client’s onError hook, if you set one; see
Logging and hooks.
How often it checks
Section titled “How often it checks”intervalMs sets the time between checks, 5 s by default. Each check is one request, two for orders, and counts
against the same per-endpoint rate limits as the rest of your program; asking
for a shorter interval than an endpoint allows just makes the client wait for budget.