wealthsim 0.1.0__tar.gz

wealthsim-0.1.0/.gitignore

@@ -0,0 +1,21 @@
+# Credentials — NEVER commit. Holds live Wealthsimple access/refresh tokens.
+.env
+.env.*
+*.token
+tokens.json
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+
+# Tooling
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.vscode/
+.idea/

wealthsim-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eugene Wang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

wealthsim-0.1.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.5
+Name: wealthsim
+Version: 0.1.0
+Summary: Unofficial Python client for Wealthsimple: quotes, accounts, positions, activity.
+Project-URL: Homepage, https://github.com/eugland/wealthsim
+Project-URL: Source, https://github.com/eugland/wealthsim
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: curl-cffi>=0.7
+Provides-Extra: browser
+Requires-Dist: playwright>=1.40; extra == 'browser'
+Description-Content-Type: text/markdown
+
+# wealthsim
+
+**Unofficial Python client for Wealthsimple** — quotes, accounts, positions, activity. Read-only.
+
+> Not affiliated with or endorsed by Wealthsimple. Uses the private GraphQL API behind the web app. Automated access may violate Wealthsimple's terms — use at your own risk. No order placement, by design.
+
+```python
+from wealthsim import login_via_browser, load_cached
+
+ws = login_via_browser()          # opens Chrome; you complete the passkey / 2FA
+# next runs: ws = load_cached()   # reuse the cached token, no re-login
+
+ws.quote("AAPL")                  # {'symbol': 'AAPL', 'price': '319.9', 'bid': ..., ...}
+ws.accounts()                     # every account + balance
+ws.positions()                    # holdings: qty, market value, unrealized P&L
+ws.activities(10)                 # recent feed items
+ws.security("AAPL")               # fundamentals: P/E, market cap, yield, 52wk range
+ws.historical_quotes("AAPL", "1m")# daily price history
+ws.identity_id                    # your identity id (decoded from the token)
+```
+
+```bash
+pip install curl_cffi playwright
+```
+
+## Auth
+
+Wealthsimple has no public API and (for passkey/2FA accounts) can't be logged into headlessly.
+`login_via_browser()` opens your real Chrome, **you** complete the passkey, and it captures the
+access token from the first post-login request — then caches it to `.env` for reuse.
+
+- `curl_cffi` (Chrome impersonation) is required — WS is behind Cloudflare TLS fingerprinting.
+- Access tokens expire (~1h); rerun `login_via_browser()` to refresh.
+- **`.env` holds a live account token in plaintext — never commit it.**
+
+## API reference
+
+All methods are read-only and return plain dicts/lists. Create a client with
+`login_via_browser()` (interactive passkey) or `load_cached()` (reuse `.env`).
+
+### Profile & session
+| Method | Returns |
+|---|---|
+| `me()` | name, email, identity id, ownership, token scope, token expiry |
+| `identity_id` | your `identity-...` id (decoded from the JWT) |
+| `token_claims` | raw decoded JWT claims (sub, scope, client_id, iat, exp) |
+
+### Market data
+| Method | Returns |
+|---|---|
+| `quote(symbol)` | price, bid/ask, OHLC, close, prev close, volume, `change_pct`, market status |
+| `security(symbol)` | core fundamentals (market cap, P/E, EPS, yield, 52wk range) |
+| `security_info(symbol)` | full: + beta, margin rate, MER, allowed order subtypes, revenue, shares |
+| `security_dividend(symbol)` | yield, frequency, ex-div / record / payable dates |
+| `historical_quotes(symbol, timerange="1m")` | price series; `timerange` ∈ `1d 1w 1m 3m 1y 5y` |
+
+### Accounts & portfolio
+| Method | Returns |
+|---|---|
+| `accounts()` | every account: id, type, nickname, currency, status, value |
+| `positions(currency="CAD")` | holdings: symbol, quantity, book/market value, unrealized P&L |
+| `net_worth(currency="CAD")` | combined value, net deposits, simple return (amount + rate) |
+| `realized_returns(currency="CAD")` | total realized P&L + per-security breakdown |
+| `dividends(currency="CAD")` | total dividend income + per-security breakdown |
+| `portfolio_history(days=90, currency="CAD")` | daily net-worth series for charting |
+| `activities(limit=10)` | recent feed items (deposits, trades, card, interest, dividends) |
+| `credit_card()` | credit-card limit, balances, cards (or `None`) |
+
+All methods raise `WSError` on failure (`UNAUTHENTICATED` → token expired, re-login).
+
+## CLI
+
+```bash
+python run_env.py quote AAPL
+python run_env.py accounts
+python run_env.py positions
+python run_env.py activities 10
+python run_env.py security TSLA
+python run_env.py history AAPL 3m
+python automate.py            # full end-to-end: login -> quote -> accounts -> activity
+```
+
+## Prior art
+
+Endpoint shapes referenced from [`ws-api`](https://github.com/gboudreau/ws-api-python) (Guillaume Boudreau). This is a clean, focused reimplementation of the read-only path.
+
+## License
+
+MIT

wealthsim-0.1.0/README.md

@@ -0,0 +1,89 @@
+# wealthsim
+
+**Unofficial Python client for Wealthsimple** — quotes, accounts, positions, activity. Read-only.
+
+> Not affiliated with or endorsed by Wealthsimple. Uses the private GraphQL API behind the web app. Automated access may violate Wealthsimple's terms — use at your own risk. No order placement, by design.
+
+```python
+from wealthsim import login_via_browser, load_cached
+
+ws = login_via_browser()          # opens Chrome; you complete the passkey / 2FA
+# next runs: ws = load_cached()   # reuse the cached token, no re-login
+
+ws.quote("AAPL")                  # {'symbol': 'AAPL', 'price': '319.9', 'bid': ..., ...}
+ws.accounts()                     # every account + balance
+ws.positions()                    # holdings: qty, market value, unrealized P&L
+ws.activities(10)                 # recent feed items
+ws.security("AAPL")               # fundamentals: P/E, market cap, yield, 52wk range
+ws.historical_quotes("AAPL", "1m")# daily price history
+ws.identity_id                    # your identity id (decoded from the token)
+```
+
+```bash
+pip install curl_cffi playwright
+```
+
+## Auth
+
+Wealthsimple has no public API and (for passkey/2FA accounts) can't be logged into headlessly.
+`login_via_browser()` opens your real Chrome, **you** complete the passkey, and it captures the
+access token from the first post-login request — then caches it to `.env` for reuse.
+
+- `curl_cffi` (Chrome impersonation) is required — WS is behind Cloudflare TLS fingerprinting.
+- Access tokens expire (~1h); rerun `login_via_browser()` to refresh.
+- **`.env` holds a live account token in plaintext — never commit it.**
+
+## API reference
+
+All methods are read-only and return plain dicts/lists. Create a client with
+`login_via_browser()` (interactive passkey) or `load_cached()` (reuse `.env`).
+
+### Profile & session
+| Method | Returns |
+|---|---|
+| `me()` | name, email, identity id, ownership, token scope, token expiry |
+| `identity_id` | your `identity-...` id (decoded from the JWT) |
+| `token_claims` | raw decoded JWT claims (sub, scope, client_id, iat, exp) |
+
+### Market data
+| Method | Returns |
+|---|---|
+| `quote(symbol)` | price, bid/ask, OHLC, close, prev close, volume, `change_pct`, market status |
+| `security(symbol)` | core fundamentals (market cap, P/E, EPS, yield, 52wk range) |
+| `security_info(symbol)` | full: + beta, margin rate, MER, allowed order subtypes, revenue, shares |
+| `security_dividend(symbol)` | yield, frequency, ex-div / record / payable dates |
+| `historical_quotes(symbol, timerange="1m")` | price series; `timerange` ∈ `1d 1w 1m 3m 1y 5y` |
+
+### Accounts & portfolio
+| Method | Returns |
+|---|---|
+| `accounts()` | every account: id, type, nickname, currency, status, value |
+| `positions(currency="CAD")` | holdings: symbol, quantity, book/market value, unrealized P&L |
+| `net_worth(currency="CAD")` | combined value, net deposits, simple return (amount + rate) |
+| `realized_returns(currency="CAD")` | total realized P&L + per-security breakdown |
+| `dividends(currency="CAD")` | total dividend income + per-security breakdown |
+| `portfolio_history(days=90, currency="CAD")` | daily net-worth series for charting |
+| `activities(limit=10)` | recent feed items (deposits, trades, card, interest, dividends) |
+| `credit_card()` | credit-card limit, balances, cards (or `None`) |
+
+All methods raise `WSError` on failure (`UNAUTHENTICATED` → token expired, re-login).
+
+## CLI
+
+```bash
+python run_env.py quote AAPL
+python run_env.py accounts
+python run_env.py positions
+python run_env.py activities 10
+python run_env.py security TSLA
+python run_env.py history AAPL 3m
+python automate.py            # full end-to-end: login -> quote -> accounts -> activity
+```
+
+## Prior art
+
+Endpoint shapes referenced from [`ws-api`](https://github.com/gboudreau/ws-api-python) (Guillaume Boudreau). This is a clean, focused reimplementation of the read-only path.
+
+## License
+
+MIT

wealthsim-0.1.0/automate.py

@@ -0,0 +1,106 @@
+"""Demo every wealthsim client method using the cached .env token (no login).
+
+Run:  python automate.py
+If the token expired, refresh it once with:  python browser_auth.py
+"""
+
+import sys
+
+from wealthsim import WSError, load_cached
+
+sys.stdout.reconfigure(encoding="utf-8")  # Windows console: allow emoji nicknames
+
+
+def main() -> None:
+    try:
+        ws = load_cached(".env")
+    except (FileNotFoundError, ValueError, KeyError):
+        print("No cached token in .env. Run: python browser_auth.py")
+        sys.exit(1)
+
+    print("=== me() ===")
+    for k, v in ws.me().items():
+        print(f"  {k:<16} {v}")
+
+    print("\n=== quote(sym) ===")
+    for sym in ("AAPL", "TSLA", "VFV"):
+        q = ws.quote(sym)
+        print(f"  {q['symbol']:<6} {q['price']} {q['currency']}  "
+              f"bid {q['bid']}/ask {q['ask']}  [{q['market_status']}]")
+
+    print("\n=== security('AAPL') fundamentals ===")
+    s = ws.security("AAPL")
+    for k in ("marketCap", "peRatio", "eps", "yield", "high52Week", "low52Week"):
+        print(f"  {k:<12} {s.get(k)}")
+
+    print("\n=== historical_quotes('AAPL', '1m') ===")
+    hq = ws.historical_quotes("AAPL", "1m")
+    print(f"  {len(hq)} points; last: {hq[-1]['timestamp'][:10]} = {hq[-1]['price']} {hq[-1]['currency']}")
+
+    print("\n=== accounts() (open only) ===")
+    for a in ws.accounts():
+        if a["status"] != "open":
+            continue
+        nick = a.get("nickname") or "-"
+        print(f"  {a['type']:<40} {nick:<14} {a['value'] or '0':>18} {a['currency']}")
+
+    print("\n=== positions() ===")
+    for p in ws.positions():
+        print(f"  {p['symbol'] or '?':<6} qty {str(p['quantity']):<12} "
+              f"mkt {p['market_value'] or '0':>16} {p['currency'] or ''}  pnl {p['unrealized_pnl'] or '0'}")
+
+    print("\n=== activities(5) ===")
+    for act in ws.activities(5):
+        print(f"  {act.get('occurredAt', '')[:10]}  {act.get('type'):<16} "
+              f"{act.get('subType') or '':<14} "
+              f"{act.get('amountSign') or ''}{act.get('amount') or ''} {act.get('currency') or ''} "
+              f"{act.get('assetSymbol') or ''}")
+
+    print("\n=== net_worth() ===")
+    n = ws.net_worth()
+    print(f"  value {n['net_value']} {n['currency']}  deposits {n['net_deposits']}  "
+          f"return {n['return_amount']} ({n['return_rate']})")
+
+    print("\n=== realized_returns() top 5 ===")
+    r = ws.realized_returns(limit=5)
+    print(f"  total {r['total']} {r['currency']}")
+    for b in r["by_security"]:
+        print(f"    {b['symbol'] or '?':<10} {b['amount']}")
+
+    print("\n=== dividends() top 5 ===")
+    d = ws.dividends()
+    print(f"  total {d['total']} {d['currency']}")
+    for b in d["by_security"][:5]:
+        print(f"    {b['symbol'] or '?':<10} {b['amount']}")
+
+    print("\n=== security_info('AAPL') ===")
+    si = ws.security_info("AAPL")
+    for k in ("beta", "margin_rate", "mer", "dividend_frequency", "allowed_order_subtypes"):
+        print(f"  {k:<22} {si.get(k)}")
+
+    print("\n=== security_dividend('AAPL') ===")
+    print(" ", ws.security_dividend("AAPL"))
+
+    print("\n=== portfolio_history(30 days) ===")
+    h = ws.portfolio_history(days=30)
+    print(f"  {len(h)} days; {h[0]['date']}={h[0]['value'][:8]} -> {h[-1]['date']}={h[-1]['value'][:8]}")
+
+    print("\n=== credit_card() ===")
+    cc = ws.credit_card()
+    if cc:
+        print(f"  limit {cc['creditLimit']}  balance {cc['balance']['current']}  "
+              f"available {cc['balance']['availableCreditLimit']}")
+    else:
+        print("  (no credit card account)")
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except WSError as e:
+        msg = str(e)
+        if "UNAUTHENTICATED" in msg or "Not Authorized" in msg:
+            print("\nToken expired — refresh with: python browser_auth.py")
+        else:
+            print("\nERROR:", msg)
+        sys.exit(1)

wealthsim-0.1.0/browser_auth.py

@@ -0,0 +1,85 @@
+"""Browser-assisted login for passkey accounts.
+
+Opens your real Chrome to the Wealthsimple login page. YOU log in with your passkey
+(Windows Hello / phone). The script watches the network, captures the access token
+(and refresh token if seen), saves them to .env, then quotes a symbol.
+
+    pip install playwright
+    python -m playwright install chromium   # or rely on channel="chrome" below
+    python browser_auth.py AAPL
+
+Nothing is typed by the script — it only reads the tokens the browser already obtained.
+"""
+
+import json
+import sys
+
+from playwright.sync_api import sync_playwright
+
+from wealthsim import Session
+from curl_cffi import requests as cffi_requests
+
+symbol = sys.argv[1] if len(sys.argv) > 1 else "AAPL"
+captured: dict[str, str] = {}
+
+
+def _is_user_graphql(req) -> bool:
+    # Only /graphql carries the real user token, and only after login succeeds.
+    # (WS sends an anonymous Bearer on pre-login bootstrap calls — ignore those.)
+    return "/graphql" in req.url and req.headers.get("authorization", "").lower().startswith(
+        "bearer "
+    )
+
+
+def on_request(req):
+    if _is_user_graphql(req) and "access_token" not in captured:
+        captured["access_token"] = req.headers["authorization"][7:]
+        dev = req.headers.get("x-ws-device-id")
+        if dev:
+            captured["device_id"] = dev
+        print("captured user access token from a graphql request.")
+
+
+def on_response(resp):
+    if resp.url.endswith("/token") and resp.request.method == "POST":
+        try:
+            body = resp.json()
+        except Exception:
+            return
+        if "refresh_token" in body:
+            captured["refresh_token"] = body["refresh_token"]
+            captured.setdefault("access_token", body.get("access_token", ""))
+            print("captured refresh token from token response.")
+
+
+with sync_playwright() as p:
+    # channel="chrome" uses your installed Chrome so the OS passkey prompt works.
+    browser = p.chromium.launch(channel="chrome", headless=False)
+    page = browser.new_page()
+    page.on("request", on_request)
+    page.on("response", on_response)
+    page.goto("https://my.wealthsimple.com/app/login")
+
+    print("\n>>> Log in with your passkey in the browser window.")
+    print(">>> Waiting for a token... (up to 3 min)\n")
+    try:
+        page.wait_for_event("request", predicate=_is_user_graphql, timeout=180_000)
+    except Exception:
+        pass
+    browser.close()
+
+if "access_token" not in captured:
+    print("No token captured. Did login complete?")
+    sys.exit(1)
+
+# Persist whatever we got (access + refresh if present) for reuse.
+with open(".env", "w") as f:
+    json.dump(captured, f, indent=2)
+print("saved tokens to .env")
+
+ws = Session(
+    cffi_requests.Session(),
+    access_token=captured["access_token"],
+    device_id=captured.get("device_id", ""),
+)
+print(ws.quote(symbol))

wealthsim-0.1.0/example.py

@@ -0,0 +1,25 @@
+"""Run the quote path against a real account.
+
+Credentials come from env vars / interactive prompt so they never get hard-coded.
+Run it yourself:  python example.py   (or in Claude Code:  ! python example.py)
+
+    set WS_EMAIL=you@example.com
+    set WS_PASSWORD=...
+    python example.py
+"""
+
+import getpass
+import os
+
+from wealthsim import OTPRequired, login
+
+email = os.environ.get("WS_EMAIL") or input("Wealthsimple email: ")
+password = os.environ.get("WS_PASSWORD") or getpass.getpass("Password: ")
+
+try:
+    ws = login(email, password)
+except OTPRequired:
+    code = input("2FA code: ")
+    ws = login(email, password, otp=code)
+
+print(ws.quote("AAPL"))

wealthsim-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "wealthsim"
+version = "0.1.0"
+description = "Unofficial Python client for Wealthsimple: quotes, accounts, positions, activity."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+dependencies = ["curl_cffi>=0.7"]
+
+[project.optional-dependencies]
+browser = ["playwright>=1.40"]
+
+[project.urls]
+Homepage = "https://github.com/eugland/wealthsim"
+Source = "https://github.com/eugland/wealthsim"
+
+[tool.hatch.build.targets.wheel]
+packages = ["wealthsim"]

wealthsim-0.1.0/quote_refresh.py

@@ -0,0 +1,33 @@
+"""Quote a symbol using a browser-grabbed REFRESH token (mints fresh access tokens).
+
+Values read from prompt/env so they never get hard-coded or pasted anywhere shared:
+
+    python quote_refresh.py AAPL
+
+Refresh token: the `refresh_token` value from the OAuth response in DevTools
+(Network -> the `token` request -> Response), the long JWT.
+Device id: the `x-ws-device-id` request header value.
+"""
+
+import os
+import sys
+
+from wealthsim import WSError, from_refresh_token
+
+
+def clean(v: str) -> str:
+    v = v.strip().strip('"').strip("'").strip()
+    if v.lower().startswith("bearer "):
+        v = v[7:].strip()
+    return v
+
+
+refresh = clean(os.environ.get("WS_REFRESH") or input("Refresh token: "))
+device_id = clean(os.environ.get("WS_DEVICE_ID") or input("x-ws-device-id: "))
+symbol = sys.argv[1] if len(sys.argv) > 1 else "AAPL"
+
+try:
+    ws = from_refresh_token(refresh, device_id=device_id)
+    print(ws.quote(symbol))
+except WSError as e:
+    print("ERROR:", e)

wealthsim-0.1.0/quote_token.py

@@ -0,0 +1,38 @@
+"""Quote a symbol using a browser-grabbed access token (for passkey accounts).
+
+Token + device id are read from env vars or an interactive prompt, so they never
+get hard-coded or pasted anywhere shared. Run it yourself:
+
+    python quote_token.py                # prompts for both
+    # or set them first:
+    $env:WS_TOKEN="eyJhbGci..."          # value AFTER "Bearer ", no "Bearer " prefix
+    $env:WS_DEVICE_ID="226d18b3-...."    # the x-ws-device-id header value
+    python quote_token.py AAPL
+
+Token format: the raw JWT from the `authorization: Bearer <THIS>` header.
+Do NOT include the word "Bearer". Device id: the `x-ws-device-id` header value.
+"""
+
+import os
+import sys
+
+from curl_cffi import requests
+
+from wealthsim import Session
+
+token = os.environ.get("WS_TOKEN") or input("Bearer access token: ").strip()
+device_id = os.environ.get("WS_DEVICE_ID") or input("x-ws-device-id: ").strip()
+symbol = sys.argv[1] if len(sys.argv) > 1 else "AAPL"
+
+# sanitize a copy/pasted header value: surrounding quotes, an "authorization:"
+# label, and/or a leading "Bearer " — keep only the raw JWT.
+token = token.strip().strip('"').strip("'").strip()
+if ":" in token.split(".")[0]:  # e.g. "authorization: Bearer eyJ..."
+    token = token.split(":", 1)[1].strip()
+if token.lower().startswith("bearer "):
+    token = token[7:].strip()
+token = token.strip().strip('"').strip("'").strip()
+device_id = device_id.strip().strip('"').strip("'").strip()
+
+ws = Session(requests.Session(), access_token=token, device_id=device_id)
+print(ws.quote(symbol))