Skip to content

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

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.

list(options?: CallOptions & { ticker?: string }): Promise<Position[]>

Every open position, or just one ticker’s. Permission portfolio, limit 1 per second.

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.

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.

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.

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.

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.

find(ticker: string, options?: { refresh?: boolean; signal?: AbortSignal }): Promise<Instrument | undefined>

The instrument with exactly this Trading 212 ticker, or undefined.

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.

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.

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.

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.

Placing, cancelling and changing orders needs orders:execute; on live, also trading: "enabled", or it throws TradingDisabledError. None of these is ever retried.

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.

sell(order: OrderInput, options?: PlaceOptions): Promise<Order>

Sells. The same as buy(), with a positive quantity: the client sets the sign.

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.

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.

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.

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.

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.

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

list(options?: CallOptions): Promise<Order[]>

Orders that are still working: not yet filled, cancelled or expired. Permission orders:read, limit 1 per 5 s.

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.

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.

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.

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. where is pending or history; check order.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.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.

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.

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.

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.

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.

positions(options?: WatchOptions): Watcher<PositionEvent>

Reports opened, changed (the quantity held changed) and closed events. Price moves alone are not reported. Needs portfolio.

cash(options?: WatchOptions): Watcher<CashEvent>

Reports a changed event when cash available to trade, reserved for orders or held in pies changes. Needs account.

The spec names no permission for these.

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.

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.

list(options?: CallOptions): Promise<Report[]>

Every report you have asked for, with its status and, once finished, its download link. Limit 1 per minute.

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

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

list(options?: CallOptions): Promise<Pie[]>

Every pie, with its progress. Limit 1 per 30 s.

get(id: number, options?: CallOptions): Promise<PieDetails>

One pie with its instruments and settings. Limit 1 per 5 s.

create(pie: PieInput, options?: CallOptions): Promise<PieDetails>

Makes a pie from { name, icon, goal, endDate, dividendCashAction, instrumentShares }. Limit 1 per 5 s.

update(id: number, pie: PieInput, options?: CallOptions): Promise<PieDetails>

Changes a pie’s settings or instruments. Limit 1 per 5 s.

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.

delete(id: number, options?: CallOptions): Promise<void>

Deletes a pie. Limit 1 per 5 s.