Skip to content

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 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.

find-instrument.mts
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");

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 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:

redis-cache.mts
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();

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.mts
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"}`,
);
}

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.

market-wait.mts
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 });

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.