Instruments and market hours
| Method | Returns | Permission | Limit |
|---|---|---|---|
instruments.list() |
Every instrument the account can trade | metadata |
1 / 50 s |
instruments.search(query) |
The best matches, best first | metadata |
cached |
instruments.resolve(query) |
Exactly one instrument, or InstrumentNotFoundError |
metadata |
cached |
instruments.find(ticker) |
The instrument with that exact ticker, or undefined |
metadata |
cached |
exchanges.list() |
Every exchange and its working schedules | metadata |
1 / 30 s |
exchanges.status(ticker) |
Whether its market is open, and when that changes | metadata |
cached |
Tickers
Section titled “Tickers”Tickers are Trading 212’s own: AAPL_US_EQ, VODl_EQ (a lowercase l means London), SXR8d_EQ (d means
Germany). Do not build them by hand; look them up.
import { InstrumentNotFoundError, Trading212 } from "@kkkermit/trading212.js";
const t212 = Trading212.fromEnv();
// The best matches first, from the cached instrument list.const results = await t212.instruments.search("vanguard s&p", { type: "ETF", limit: 5 });for (const instrument of results) console.log(instrument.ticker, instrument.name);
// Exactly one instrument, or an error listing the closest matches.try { const apple = await t212.instruments.resolve("AAPL", { currency: "USD" }); console.log(`AAPL is ${apple.ticker}, traded in ${apple.currencyCode}`);} catch (error) { if (!(error instanceof InstrumentNotFoundError)) throw error; console.log( "Did you mean:", error.suggestions.map((suggestion) => suggestion.ticker), );}
// When you already have the Trading 212 ticker.const exact = await t212.instruments.find("AAPL_US_EQ");console.log(exact?.name ?? "No such ticker");const { InstrumentNotFoundError, Trading212 } = require("@kkkermit/trading212.js");
async function main() { const t212 = Trading212.fromEnv();
// The best matches first, from the cached instrument list. const results = await t212.instruments.search("vanguard s&p", { type: "ETF", limit: 5, }); for (const instrument of results) console.log(instrument.ticker, instrument.name);
// Exactly one instrument, or an error listing the closest matches. try { const apple = await t212.instruments.resolve("AAPL", { currency: "USD" }); console.log(`AAPL is ${apple.ticker}, traded in ${apple.currencyCode}`); } catch (error) { if (!(error instanceof InstrumentNotFoundError)) throw error; console.log( "Did you mean:", error.suggestions.map((suggestion) => suggestion.ticker), ); }
// When you already have the Trading 212 ticker. const exact = await t212.instruments.find("AAPL_US_EQ"); console.log(exact?.name ?? "No such ticker");}
main().catch((error) => { console.error(error); process.exitCode = 1;});search() ranks by ticker, ISIN, short name and name, and takes limit (default 10), type (such as STOCK or
ETF) and currency (such as USD or GBX). resolve() turns what a person would type into exactly one
instrument: an exact ticker, ISIN, short name or full name, or a ticker without its suffix, such as AAPL for
AAPL_US_EQ. If nothing fits, or several fit equally well, it throws InstrumentNotFoundError with suggestions
and a hint on narrowing it down.
Every instrument these methods return has a ticker; entries without one cannot be traded and are left out.
The cached list
Section titled “The cached list”The full list is about 5 MB and limited to one request every 50 seconds, so it is cached (one hour by default,
metadataTtlMs) and callers at the same moment share one download. Trading 212 refreshes it every 10 minutes. Pass
{ refresh: true } to fetch it afresh. search(), resolve() and find() read the cached list, so they cost no
request after the first.
To share the cache between processes, pass a cache with get, set and optionally delete. Each may return a
promise, and get returning undefined or null counts as a miss:
import { type CacheStore, Trading212 } from "@kkkermit/trading212.js";
// Any client with get and set works; this is the shape of node-redis and ioredis.interface RedisLike { get(key: string): Promise<string | null>; set(key: string, value: string, mode: "PX", ttlMs: number): Promise<unknown>; del(key: string): Promise<unknown>;}declare const redis: RedisLike;
// redis is your connected node-redis or ioredis client.const redisCache: CacheStore = { // A null from Redis counts as a miss. get: async (key) => { const text = await redis.get(key); return text === null ? undefined : (JSON.parse(text) as unknown); }, set: (key, value, ttlMs) => redis.set(key, JSON.stringify(value), "PX", ttlMs), delete: (key) => redis.del(key),};
// Every process now shares one copy of the 5 MB instrument list.const t212 = Trading212.fromEnv({ cache: redisCache });await t212.instruments.list();const { Trading212 } = require("@kkkermit/trading212.js");
async function main() { // redis is your connected node-redis or ioredis client. const redisCache = { // A null from Redis counts as a miss. get: async (key) => { const text = await redis.get(key); return text === null ? undefined : JSON.parse(text); }, set: (key, value, ttlMs) => redis.set(key, JSON.stringify(value), "PX", ttlMs), delete: (key) => redis.del(key), };
// Every process now shares one copy of the 5 MB instrument list. const t212 = Trading212.fromEnv({ cache: redisCache }); await t212.instruments.list();}
main().catch((error) => { console.error(error); process.exitCode = 1;});A cache that fails is logged at warn and bypassed, so a broken Redis costs a download rather than the call. A
cached value that is not a list is treated the same way.
Market hours
Section titled “Market hours”import { Trading212 } from "@kkkermit/trading212.js";
const t212 = Trading212.fromEnv();
const status = await t212.exchanges.status("AAPL_US_EQ");
if (status.open) { console.log( `${status.exchange} is open; next change: ${status.next?.event} at ${status.next?.at.toISOString()}`, );} else { console.log( `Market is ${status.session}; it next opens ${status.nextOpen?.toISOString() ?? "later"}`, );}const { Trading212 } = require("@kkkermit/trading212.js");
async function main() { const t212 = Trading212.fromEnv();
const status = await t212.exchanges.status("AAPL_US_EQ");
if (status.open) { console.log( `${status.exchange} is open; next change: ${status.next?.event} at ${status.next?.at.toISOString()}`, ); } else { console.log( `Market is ${status.session}; it next opens ${status.nextOpen?.toISOString() ?? "later"}`, ); }}
main().catch((error) => { console.error(error); process.exitCode = 1;});status() returns:
| Field | Holds |
|---|---|
session |
"regular", "preMarket", "afterHours", "overnight", "closed" or "unknown" |
open |
true during regular trading hours |
extendedHours |
true during a pre-market, after-hours or overnight session |
since |
When the current session began |
next |
{ event, at }: the next scheduled change, such as the close |
nextOpen |
When regular trading next starts, including the end of a midday break |
exchange |
The exchange’s name |
It reads Trading 212’s working schedules, which cover a limited window ahead, so nextOpen can be undefined. Pass
a Date as the second argument to ask about another moment. sessionAt(timeEvents, date) is the same calculation as
a pure function, for schedules you already have.
Waiting for the open
Section titled “Waiting for the open”import { Trading212 } from "@kkkermit/trading212.js";
const t212 = Trading212.fromEnv();const ticker = "AAPL_US_EQ";
if (!(await t212.exchanges.isOpen(ticker))) { console.log("Closed. Waiting for the open…"); // Sleeps until the scheduled opening, up to four days so a weekend fits; extendedHours: true counts pre-market too. await t212.exchanges.waitUntilOpen(ticker, { timeoutMs: 4 * 24 * 60 * 60_000 });}await t212.orders.buy({ ticker, quantity: 1 });const { Trading212 } = require("@kkkermit/trading212.js");
async function main() { const t212 = Trading212.fromEnv(); const ticker = "AAPL_US_EQ";
if (!(await t212.exchanges.isOpen(ticker))) { console.log("Closed. Waiting for the open…"); // Sleeps until the scheduled opening, up to four days so a weekend fits; extendedHours: true counts pre-market too. await t212.exchanges.waitUntilOpen(ticker, { timeoutMs: 4 * 24 * 60 * 60_000 }); } await t212.orders.buy({ ticker, quantity: 1 });}
main().catch((error) => { console.error(error); process.exitCode = 1;});isOpen(ticker) says whether the market is open now, and waitUntilOpen(ticker) resolves with its status once it
opens. Both count only regular hours unless you pass extendedHours: true. waitUntilOpen() sleeps until the
opening the schedule gives rather than checking over and over, and checks again when it wakes. Pass timeoutMs to
give up with a TimeoutError, straight away if the market opens later than that, or signal to stop it.