Methods
Every method that talks to Trading 212 returns a promise, so put await in front of it. Each also takes a last
argument of call options, { signal?, timeoutMs? }, to cancel it or give it its own timeout; see
Configuration. Any method can also throw the
errors every request can: AuthenticationError, MissingScopeError, RateLimitError, TimeoutError,
NetworkError and ServerError.
Signatures are written in TypeScript; in JavaScript, leave out everything after a :.
Account
Section titled “Account”account.summary()
Section titled “account.summary()”summary(options?: CallOptions): Promise<AccountSummary>Cash, investments, profit and loss, and total value, in the account’s primary currency. Permission account, limit
1 per 5 s.
Positions
Section titled “Positions”positions.list()
Section titled “positions.list()”list(options?: CallOptions & { ticker?: string }): Promise<Position[]>Every open position, or just one ticker’s. Permission portfolio, limit 1 per second.
positions.get()
Section titled “positions.get()”get(ticker: string, options?: CallOptions): Promise<Position | undefined>One ticker’s position, or undefined when you hold none. Matches the ticker itself, so it never returns another
holding.
Portfolio
Section titled “Portfolio”portfolio.snapshot()
Section titled “portfolio.snapshot()”snapshot(options?: CallOptions): Promise<PortfolioSnapshot>The account’s totals and every holding’s value, profit and weight, from two requests. Needs account and
portfolio. See Account and portfolio for the
fields.
Instruments
Section titled “Instruments”instruments.list()
Section titled “instruments.list()”list(options?: { refresh?: boolean; signal?: AbortSignal }): Promise<Instrument[]>Every instrument the account can trade: about 5 MB, cached for metadataTtlMs (one hour by default) and shared by
callers at the same moment. Permission metadata, limit 1 per 50 s.
instruments.search()
Section titled “instruments.search()”search( query: string, options?: { limit?: number; type?: string; currency?: string; refresh?: boolean; signal?: AbortSignal },): Promise<Instrument[]>Instruments matching a ticker, ISIN, short name or name, best first; limit defaults to 10. Reads the cached list.
Throws ValidationError for an empty query.
instruments.resolve()
Section titled “instruments.resolve()”resolve( query: string, options?: { type?: string; currency?: string; refresh?: boolean; signal?: AbortSignal },): Promise<Instrument>Exactly one instrument for what a person would type (AAPL, Apple, an ISIN). Throws InstrumentNotFoundError,
with suggestions, when none or several fit.
instruments.find()
Section titled “instruments.find()”find(ticker: string, options?: { refresh?: boolean; signal?: AbortSignal }): Promise<Instrument | undefined>The instrument with exactly this Trading 212 ticker, or undefined.
Exchanges
Section titled “Exchanges”exchanges.list()
Section titled “exchanges.list()”list(options?: { refresh?: boolean; signal?: AbortSignal }): Promise<Exchange[]>Every exchange and its working schedules, cached like the instrument list. Permission metadata, limit 1 per 30 s.
exchanges.status()
Section titled “exchanges.status()”status( ticker: string | TradableInstrument, at?: Date, options?: { refresh?: boolean; signal?: AbortSignal },): Promise<MarketStatus>Whether an instrument’s market is open at at (default now), and when that next changes. Throws
InstrumentNotFoundError for an unknown ticker. See
Market hours for the fields.
exchanges.isOpen()
Section titled “exchanges.isOpen()”isOpen(ticker: string | TradableInstrument, options?: OpenOptions): Promise<boolean>Whether the market is open now. OpenOptions is { extendedHours?, refresh?, signal? }: with
extendedHours: true, pre-market, after-hours and overnight sessions count as open too.
exchanges.waitUntilOpen()
Section titled “exchanges.waitUntilOpen()”waitUntilOpen(ticker: string | TradableInstrument, options?: WaitUntilOpenOptions): Promise<MarketStatus>Resolves with the market’s status once it opens, or straight away if it is open now. It sleeps until the opening the
schedule gives rather than checking over and over. WaitUntilOpenOptions adds timeoutMs to OpenOptions: with
one, it throws TimeoutError straight away if the market opens after that, and there is no limit without one. When
the schedule does not say when it opens, it checks again every hour until the timeout. Stop it early with signal.
Orders
Section titled “Orders”Placing, cancelling and changing orders needs orders:execute; on live, also trading: "enabled", or it throws
TradingDisabledError. None of these is ever retried.
orders.buy()
Section titled “orders.buy()”buy(order: OrderInput, options?: PlaceOptions): Promise<Order>Buys. order is { ticker, quantity, type?, limitPrice?, stopPrice?, timeValidity?, extendedHours? }; type is
"market" (the default), "limit", "stop" or "stopLimit", and the quantity is positive. With
{ dryRun: true } it returns a DryRunResult instead and sends nothing. Throws ValidationError before sending,
OrderRejectedError when refused, or OrderOutcomeUnknownError when it may have gone through.
orders.sell()
Section titled “orders.sell()”sell(order: OrderInput, options?: PlaceOptions): Promise<Order>Sells. The same as buy(), with a positive quantity: the client sets the sign.
orders.sellAll()
Section titled “orders.sellAll()”sellAll(ticker: string, options?: { extendedHours?: boolean; dryRun?: boolean }): Promise<Order>Sells the position’s quantityAvailableForTrading, cut to 4 decimal places, at market. Also needs portfolio.
Throws ValidationError when nothing can be sold.
orders.market()
Section titled “orders.market()”market(order: { ticker: string; quantity: number; extendedHours?: boolean }, options?: PlaceOptions): Promise<Order>A market order, sent as given: a negative quantity sells. Limit 50 per minute.
orders.limit()
Section titled “orders.limit()”limit( order: { ticker: string; quantity: number; limitPrice: number; timeValidity: "DAY" | "GOOD_TILL_CANCEL" }, options?: PlaceOptions,): Promise<Order>A limit order: fills at limitPrice or better. Limit 1 per 2 s.
orders.stop()
Section titled “orders.stop()”stop( order: { ticker: string; quantity: number; stopPrice: number; timeValidity: "DAY" | "GOOD_TILL_CANCEL" }, options?: PlaceOptions,): Promise<Order>A stop order: places a market order once the price reaches stopPrice. Limit 1 per 2 s.
orders.stopLimit()
Section titled “orders.stopLimit()”stopLimit( order: { ticker: string; quantity: number; stopPrice: number; limitPrice: number; timeValidity: "DAY" | "GOOD_TILL_CANCEL"; }, options?: PlaceOptions,): Promise<Order>A stop-limit order: places a limit order at limitPrice once the price reaches stopPrice. Limit 1 per 2 s.
orders.waitFor()
Section titled “orders.waitFor()”waitFor( order: Order | number, options?: { timeoutMs?: number; intervalMs?: number; signal?: AbortSignal },): Promise<Order>Waits until an order is filled, cancelled, rejected or replaced (FINAL_ORDER_STATUSES), checking every
intervalMs (default 1 s), and returns it in that state. Once the order has left the pending list it looks in the
history, which needs history:orders. Throws TimeoutError after timeoutMs (default 60 s).
orders.list()
Section titled “orders.list()”list(options?: CallOptions): Promise<Order[]>Orders that are still working: not yet filled, cancelled or expired. Permission orders:read, limit 1 per 5 s.
orders.get()
Section titled “orders.get()”get(id: number, options?: CallOptions): Promise<Order>One working order. Throws NotFoundError once it has filled or been cancelled. Permission orders:read, limit 1 per
second.
orders.cancel()
Section titled “orders.cancel()”cancel(id: number, options?: CallOptions): Promise<void>Asks Trading 212 to cancel a working order; it may still fill first. Throws NotFoundError when it has already gone.
Limit 50 per minute.
orders.cancelAll()
Section titled “orders.cancelAll()”cancelAll(options?: CancelAllOptions): Promise<CancelResult[]>Cancels every working order, or one ticker’s with { ticker }, one request each in turn, and returns a
CancelResult per order: requested when Trading 212 accepted the cancellation (it may still fill first), gone
when the order had already filled or been cancelled, unknown with an OrderOutcomeUnknownError when it may or may
not have arrived, or failed with the error. A failure does not stop the rest. Throws TradingDisabledError
before cancelling anything when trading is off, and the signal’s reason when it aborts, before the next order.
orders.findAfterUnknown()
Section titled “orders.findAfterUnknown()”findAfterUnknown(error: OrderOutcomeUnknownError, options?: FindAfterUnknownOptions): Promise<OrderSearchResult>After placing an order threw OrderOutcomeUnknownError, looks for it among the working orders and the recent
history, and never sends anything. The OrderSearchResult is one of:
{ status: "found", order, where }: it reached Trading 212, so do not send it again.whereispendingorhistory; checkorder.status, as it may have been rejected.{ status: "not-found" }: nothing like it is working or in the recent history.{ status: "unclear", reason, matches }: several orders match, one is like it but differs in a detail, or nothing matches in the 200 newest orders for the ticker but its history goes further back, so it cannot say.
An order matches when its ticker, direction, type, quantity and prices are those sent, and it was created within
windowMs (default 5 minutes) of the error’s sentAt. One with the same ticker, direction and time that differs in
another detail makes the answer unclear, never not-found. Throws ValidationError for an error that did not come
from placing an order. Needs orders:read and history:orders.
History
Section titled “History”history.orders, history.dividends and history.transactions each have the same two methods. Permissions
history:orders, history:dividends and history:transactions; each allows 20 requests a minute.
history.*.list()
Section titled “history.*.list()”list(options?: { limit?: number; cursor?: string; ticker?: string; time?: Date | string } & CallOptions): Promise<Page<T>>One page, newest first: { items, nextCursor, hasMore, next() }. limit is 1 to 50. ticker filters orders and
dividends; time starts transactions from that moment.
history.*.all()
Section titled “history.*.all()”all(options?: { pageSize?: number; maxPages?: number; maxItems?: number; cursor?: string } & filters & CallOptions): AsyncGenerator<T>Every item, fetching pages as a for await loop asks for them. A failure part-way carries resumeCursor.
history.dividends.total()
Section titled “history.dividends.total()”total(options?: DividendTotalOptions): Promise<DividendTotals>Adds up the dividends paid from since (inclusive) to until (exclusive), both optional, for every ticker or one
with ticker. Returns { total, count, currency, byTicker }, where byTicker lists each ticker’s total, largest
first. It reads every page of the dividend history, one request per 50 payments, because the spec does not say the
history is sorted.
Each watcher checks the account every intervalMs (default 5 s) and returns a Watcher. Its first check only
records where things stand; events start from the second. See Watching the account.
watch.orders()
Section titled “watch.orders()”orders(options?: WatchOptions): Watcher<OrderEvent>Reports placed, updated, filled, cancelled, rejected, replaced and gone events, including for orders
placed elsewhere. Each check reads the working orders and the newest page of the history, so it needs orders:read
and history:orders.
watch.positions()
Section titled “watch.positions()”positions(options?: WatchOptions): Watcher<PositionEvent>Reports opened, changed (the quantity held changed) and closed events. Price moves alone are not reported.
Needs portfolio.
watch.cash()
Section titled “watch.cash()”cash(options?: WatchOptions): Watcher<CashEvent>Reports a changed event when cash available to trade, reserved for orders or held in pies changes. Needs
account.
Reports
Section titled “Reports”The spec names no permission for these.
reports.export()
Section titled “reports.export()”export( request: ReportRequest, options?: { timeoutMs?: number; intervalMs?: number; onStatus?: (report: Report) => void; signal?: AbortSignal },): Promise<{ report: Report; csv: string }>Requests a report, waits for it and downloads it. A ReportRequest is { from, to, include? }: from and to are a
Date or a date string, and include takes dividends, interest, orders and transactions, all true unless you
say otherwise.
reports.request()
Section titled “reports.request()”request(request: ReportRequest, options?: CallOptions): Promise<number>Asks Trading 212 to build a report and returns its ID. Throws ValidationError when from is not before to. Limit
1 per 30 s.
reports.list()
Section titled “reports.list()”list(options?: CallOptions): Promise<Report[]>Every report you have asked for, with its status and, once finished, its download link. Limit 1 per minute.
reports.waitFor()
Section titled “reports.waitFor()”waitFor( reportId: number, options?: { timeoutMs?: number; intervalMs?: number; onStatus?: (report: Report) => void; signal?: AbortSignal },): Promise<Report>Checks a report every intervalMs (default 60 s) until it is finished. Throws UnexpectedResponseError if it failed
or was cancelled, and TimeoutError after timeoutMs (default 10 minutes).
reports.download()
Section titled “reports.download()”download(report: Report | string, options?: CallOptions): Promise<string>Downloads a finished report’s CSV, from its signed link, without your credentials.
Deprecated by Trading 212, but still working. Reading needs pies:read, changing needs pies:write and, on live,
trading: "enabled".
pies.list()
Section titled “pies.list()”list(options?: CallOptions): Promise<Pie[]>Every pie, with its progress. Limit 1 per 30 s.
pies.get()
Section titled “pies.get()”get(id: number, options?: CallOptions): Promise<PieDetails>One pie with its instruments and settings. Limit 1 per 5 s.
pies.create()
Section titled “pies.create()”create(pie: PieInput, options?: CallOptions): Promise<PieDetails>Makes a pie from { name, icon, goal, endDate, dividendCashAction, instrumentShares }. Limit 1 per 5 s.
pies.update()
Section titled “pies.update()”update(id: number, pie: PieInput, options?: CallOptions): Promise<PieDetails>Changes a pie’s settings or instruments. Limit 1 per 5 s.
pies.duplicate()
Section titled “pies.duplicate()”duplicate(id: number, copy?: { name?: string; icon?: string }, options?: CallOptions): Promise<PieDetails>Copies a pie, optionally with a new name and icon. Limit 1 per 5 s.
pies.delete()
Section titled “pies.delete()”delete(id: number, options?: CallOptions): Promise<void>Deletes a pie. Limit 1 per 5 s.