pytr: a terminal client for the Trade Republic private API, with a WAF token problem attached

The command set and what each one does

pytr is a library for the private API of the Trade Republic online brokerage, and the command line is the main way to use it. The usage output lists the subcommands and what they do.

The login command checks whether a credentials file exists, creates it and asks for input if not, then tries to log in and asks for a device reset if needed. The accounts command lists accounts of the login, for example company accounts or child accounts, to be used with the account option. The portfolio command shows the current portfolio. The rates command fetches current prices for a list of ISINs given directly or as CSV input, and details gets details for a single ISIN.

The command with the most weight is dl_docs, which downloads all PDF documents from the timeline and sorts them into folders, and also exports account transactions as account_transactions.csv plus JSON files with all events, named events_with_documents.json and other_events.json. The export_transactions command overlaps with part of that, reading the timeline and exporting transactions into a file such as a CSV.

The rest cover the broker's other features: get_price_alarms and set_price_alarms for price alarms, get_savings_plans for savings plans, completion for shell tab completion, and help. There are global options too, a verbosity flag with warning, info and debug levels, and a debug logfile option with a log type filter.

That is a complete client rather than a narrow script, and the structure of the output, sorting documents into folders and writing both a CSV and JSON sidecars, shows it is aimed at people who want the data as files.

Running it with uv and no local Python

The quickstart is written for people who have never run code before, and the recommendation is to use uv to run pytr, because uv installs an appropriate Python version if you do not already have one.

On macOS and Linux, uv installs with:

 curl -LsSf https://astral.sh/uv/install.sh | sh

On Windows:

 powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

And then the released version runs with:

 uvx pytr@latest

The development version from the repository is a slightly longer invocation:

 uvx --with git+https://github.com/pytr-org/pytr.git pytr

The package is published on PyPI as pytr, is MIT licensed, and the project metadata puts the version at 0.4.11 with requires-python of 3.10 or newer. It is classified as Development Status 3, Alpha, and the classifiers name the topic as financial and investment.

The runtime dependencies are a compact list that mostly says what the tool does. cryptography and certifi are for TLS, curl_cffi is for impersonating browser TLS fingerprints, requests_futures for the async calls, websockets for the realtime channel, pygments and coloredlogs for terminal output, shtab for the completion command, and babel with a build hook for translations. There is a single console script entry point, pytr, pointing at pytr.main:main.

Two login variants and why one of them needs a browser

Authentication is the hard part of this project, and the README spends most of its length on it.

Web login uses the public web login endpoints at api.traderepublic.com, and there are two variants. Version 1 is the default, `pytr login`, where you receive a four-digit code in the Trade Republic app, or by SMS as a fallback, and type it into the terminal. Version 1 requires passing an AWS WAF token with the login request, and by default pytr fetches one automatically through Playwright, which needs the optional playwright extra installed with `pip install 'pytr[playwright]' && playwright install chromium`. A pure-Python alternative, `--waf-token awswaf`, exists but has been reported to no longer work reliably.

Version 2 is opt-in with `pytr login --v2` and mirrors what the web app currently does. Instead of typing a code, you confirm the login from a push notification in the mobile app, and accounts secured with an authenticator app are asked for a code from that app instead. The README positions it as useful if your account no longer issues a code via the app or by SMS. Version 2 needs no WAF token, and pytr skips it automatically when the flag is used. One consequence is that Trade Republic removed the SMS resend endpoint along with the v1 web login, so there is no SMS fallback under version 2. The flag works on any subcommand that logs in, for example `pytr portfolio --v2` or `pytr dl_docs --v2`.

Both variants keep you logged in on your primary device, and the README warns that you may need to re-authenticate every so often when running pytr.

The fragility of a pinned browser identity

The section on what to do when web login suddenly stops working is the most instructive part of the documentation, because it explains the architectural weakness of the whole approach.

The web login identifies itself to Trade Republic as their own web frontend, using a build version, a platform name and a browser User-Agent that are pinned in pytr. Trade Republic can invalidate any of them at any time, and when they do, login fails for everyone until a new release goes out. Three environment variables let you fix it yourself in the meantime.

That is a genuinely important property of the project and worth understanding before you rely on it. A pinned User-Agent and build version is a fingerprint, and it is a fingerprint the server side can revoke in one move. When that happens, every user of pytr breaks simultaneously, and the fix requires a release from a small team.

The Playwright dependency exists to solve a related problem. The AWS WAF token challenge is normally solved by running a real browser, which is why the optional extra exists, and the comment in the project metadata is candid about the cost: the playwright path drags in a package of about 130 MB plus a Chromium download of about 630 MB that the install command fetches separately. The pure-Python awswaf path solves the same challenge without either, so the comment says deployments that use it, or that find their IP is not challenged at all, should not have to carry the browser at all.

The dependency footprint and the build setup

The package metadata shows a small but carefully chosen dependency set, and the comments in it are unusually informative for a project of this size.

The build backend is hatchling with hatch-babel, and there is a build hook that sets the locale directory to pytr/locale, which is how the translations are compiled. The dev dependency group pins ruff at 0.9.6, pytest at 8.3.4 or newer, mypy at 1.15.0 or newer, and type stubs for babel, requests and pygments.

The linting configuration uses ruff with a line length of 120 and the isort rules enabled through an extend-select of I, and mypy is configured for Python 3.10, matching the requires-python floor.

The repository layout is small: a pytr package directory, a tests directory, a conftest.py at the root, a .github directory for the publish workflow, and a .vscode directory. The README has a Development section covering how to set up a development environment, linting and code formatting, the release process, and a note to keep the readme updated. The release process is automated to PyPI through a GitHub Actions workflow, and the version tags follow the usual pattern, with v0.4.10 in August 2026, v0.4.9 in April 2026 and v0.4.8 a few days earlier.

One detail in the usage output is worth noting: it is generated by a runcmd block, with a comment marking a command that produces the help text and another marking the end. The usage text in the README is therefore produced by running the tool rather than written by hand, which is the right way to keep it accurate.

Where pytr is the wrong choice

The first limitation is the one the project states itself. It is a library for a private API, it is not affiliated with Trade Republic Bank GmbH, and it works by impersonating the broker's own web frontend. A private API has no stability contract, so every feature here is contingent on the broker choosing to keep the endpoint behaving the same way. The pinned User-Agent and build version are the clearest expression of that, since they can be invalidated at any time and take the tool down with them until a release ships.

The second is the credential handling. To use the tool you authenticate with your real brokerage account, and the default path involves a headless browser downloading a WAF token. Running a browser on a machine that holds your trading credentials is a real operational cost, and the pure-Python fallback for it has been reported to be unreliable, so the choice is between a large dependency and a path that may not work.

The third is scope. This is a read and download tool for one broker. It does not place orders, there is no portfolio analytics beyond the current value, and there is no multi-broker support. If your investments are spread across several platforms, the practical answer is to run it once per broker and reconcile the files yourself, and if you need performance analysis, the data it exports is a starting point rather than an answer.

The fair comparison is with the official app and the PDF statements. What pytr gives you is the same documents the app produces, as files on disk, in a format you can script, and that is a real convenience for anyone building their own records. What it does not give you is support, and the maintenance risk of an unmaintained private API client is the price of the convenience.

Editorial conclusion

pytr fits a self-directed investor who wants their Trade Republic statements and portfolio data in files they can script against, and who accepts that a private API can change or vanish without notice. It does not fit anyone who needs a supported interface, or a portfolio with institutional custody requirements. Before installing, understand that the default login path downloads a browser to fetch a WAF token, that the account is only kept logged in on your primary device and may need re-authentication, and that the tool is MIT licensed but unaffiliated with Trade Republic Bank GmbH, so there is nobody behind it if the API changes.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. pytr-org/pytr on GitHub
4. README
5. Releases