finatic-server-python 1.0.3__tar.gz → 1.0.4__tar.gz

{finatic_server_python-1.0.3 → finatic_server_python-1.0.4}/.github/dependabot.yml

@@ -3,9 +3,9 @@ updates:
   - package-ecosystem: pip
     directory: /
     schedule:
-      interval: weekly
+      interval: monthly
     target-branch: develop
-    open-pull-requests-limit: 5
+    open-pull-requests-limit: 2
     reviewers:
       - founders
     assignees:
@@ -26,11 +26,10 @@ updates:
         update-types:
           - minor
           - patch
-
   - package-ecosystem: github-actions
     directory: /
     schedule:
-      interval: weekly
+      interval: monthly
     target-branch: develop
     reviewers:
       - founders
@@ -43,3 +42,4 @@ updates:
       ci-dependencies:
         patterns:
           - "*"
+    open-pull-requests-limit: 2

finatic_server_python-1.0.4/.github/workflows/ci.yml

@@ -0,0 +1,58 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [main, develop, staging, fdx-account-consent-v1]
+
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - name: Skip heavy CI for Dependabot / release PRs
+        if: github.actor == 'dependabot[bot]' || (github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository && startsWith(github.event.pull_request.title, 'chore(release):'))
+        run: echo "Skipping heavy product CI for Dependabot or chore(release) PRs (Actions cost control)."
+      - uses: actions/checkout@v7
+        if: github.actor != 'dependabot[bot]' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name != github.repository || startsWith(github.event.pull_request.title, 'chore(release):') == false)
+
+      - uses: actions/setup-python@v7
+        if: github.actor != 'dependabot[bot]' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name != github.repository || startsWith(github.event.pull_request.title, 'chore(release):') == false)
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - uses: astral-sh/setup-uv@v7
+        if: github.actor != 'dependabot[bot]' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name != github.repository || startsWith(github.event.pull_request.title, 'chore(release):') == false)
+        with:
+          enable-cache: true
+
+      - name: Install package with dev dependencies
+        if: github.actor != 'dependabot[bot]' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name != github.repository || startsWith(github.event.pull_request.title, 'chore(release):') == false)
+        run: |
+          uv venv
+          uv pip install -e ".[dev]"
+
+      - name: Compile package
+        if: github.actor != 'dependabot[bot]' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name != github.repository || startsWith(github.event.pull_request.title, 'chore(release):') == false)
+        run: uv run python -m compileall finatic_server_python src tests
+
+      - name: Run unit tests with coverage gate
+        if: github.actor != 'dependabot[bot]' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name != github.repository || startsWith(github.event.pull_request.title, 'chore(release):') == false)
+        run: >
+          uv run pytest -q -m "not integration"
+          --cov=src
+          --cov=finatic_server_python
+          --cov-report=term-missing:skip-covered
+          --cov-fail-under=50
+
+      - name: Build package
+        if: github.actor != 'dependabot[bot]' && (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name != github.repository || startsWith(github.event.pull_request.title, 'chore(release):') == false)
+        run: uv run python -m build

finatic_server_python-1.0.4/.github/workflows/dependabot-auto-merge.yml

@@ -0,0 +1,30 @@
+name: Dependabot auto-merge
+
+on:
+  pull_request:
+
+concurrency:
+  group: dependabot-auto-merge-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  dependabot:
+    runs-on: ubuntu-latest
+    if: github.actor == 'dependabot[bot]'
+    steps:
+      - name: Fetch Dependabot metadata
+        id: metadata
+        uses: dependabot/fetch-metadata@v3
+        with:
+          github-token: "${{ secrets.GITHUB_TOKEN }}"
+
+      - name: Enable auto-merge for minor and patch updates
+        if: contains(fromJSON('["version-update:semver-minor","version-update:semver-patch"]'), steps.metadata.outputs.update-type)
+        run: gh pr merge --auto --squash "$PR_URL"
+        env:
+          PR_URL: ${{ github.event.pull_request.html_url }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

{finatic_server_python-1.0.3 → finatic_server_python-1.0.4}/.github/workflows/release.yml

@@ -1,8 +1,7 @@
 name: Release
 
 on:
-  push:
-    branches: [main]
+  # Manual only: auto-publish on every main push re-bumps after version-sync PRs.
   workflow_dispatch:
     inputs:
       dry_run:
@@ -33,12 +32,12 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
         with:
           fetch-depth: 0
           token: ${{ secrets.GITHUB_TOKEN }}
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v7
         with:
           python-version: "3.12"
 
@@ -129,7 +128,7 @@ jobs:
         run: uv run python -m build
 
       - name: Upload release artifacts
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: finatic-server-python-${{ steps.version.outputs.version }}
           path: dist/*

finatic_server_python-1.0.4/.github/workflows/security.yml

@@ -0,0 +1,63 @@
+name: Security
+
+# Cost controls:
+# - PR: actionlint + gitleaks only (cheap)
+# - schedule / workflow_dispatch only: + osv, licenses, codeql
+# - PR cheap jobs run for Dependabot; heavy jobs still skip Dependabot
+# - cancel superseded runs on the same ref
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+  schedule:
+    - cron: "0 6 * * 1"
+  workflow_dispatch:
+
+concurrency:
+  group: security-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  security-events: write
+  actions: read
+
+jobs:
+  actionlint:
+    uses: FinaticORG/.github/.github/workflows/reusable-actionlint.yml@main
+    with:
+      strict: true
+
+  gitleaks:
+    uses: FinaticORG/.github/.github/workflows/reusable-gitleaks.yml@main
+    with:
+      strict: true
+      scan-mode: no-git
+
+  osv:
+    if: >-
+      github.actor != 'dependabot[bot]' &&
+      (github.event_name == 'schedule' ||
+       github.event_name == 'workflow_dispatch')
+    uses: FinaticORG/.github/.github/workflows/reusable-osv.yml@main
+    with:
+      strict: true
+
+  licenses:
+    if: >-
+      github.actor != 'dependabot[bot]' &&
+      (github.event_name == 'schedule' ||
+       github.event_name == 'workflow_dispatch')
+    uses: FinaticORG/.github/.github/workflows/reusable-licenses-pip.yml@main
+    with:
+      strict: true
+
+  codeql:
+    if: >-
+      github.actor != 'dependabot[bot]' &&
+      (github.event_name == 'schedule' ||
+       github.event_name == 'workflow_dispatch')
+    uses: FinaticORG/.github/.github/workflows/reusable-codeql.yml@main
+    with:
+      languages: '["python"]'

{finatic_server_python-1.0.3 → finatic_server_python-1.0.4}/CHANGELOG.md

@@ -1,8 +1,12 @@
 # Changelog
 
+## 1.0.4
+
+- Release from 1f12f4e6b4f0eba77d315913d338d90aef8adfd9.
+
 ## 1.0.3
 
-- Release from bdc237bcfc54837c641e52e28b7883f7c51ec4b6.
+- Release sync after PyPI publish.
 
 ## 1.0.2
 

finatic_server_python-1.0.4/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.5
+Name: finatic-server-python
+Version: 1.0.4
+Summary: Python SDK for Finatic Server API
+Project-URL: Homepage, https://github.com/FinaticORG/FinaticServerSDK-Python
+Project-URL: Documentation, https://docs.finatic.com/python
+Project-URL: Repository, https://github.com/FinaticORG/FinaticServerSDK-Python
+Project-URL: Issues, https://github.com/FinaticORG/FinaticServerSDK-Python/issues
+Author-email: Finatic <support@finatic.dev>
+License: PROPRIETARY
+License-File: LICENSE
+Keywords: api,finance,finatic,sdk,trading
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: aiohttp-retry>=2.9.1
+Requires-Dist: aiohttp>=3.14.3
+Requires-Dist: cachetools>=7.1.7
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: python-dateutil>=2.9.0.post0
+Requires-Dist: structlog>=25.5.0
+Requires-Dist: tenacity>=9.1.2
+Requires-Dist: typing-extensions>=4.16.0
+Requires-Dist: urllib3>=2.7.0
+Provides-Extra: dev
+Requires-Dist: black>=23.0.0; extra == 'dev'
+Requires-Dist: build>=1.5.0; extra == 'dev'
+Requires-Dist: flake8>=7.3.0; extra == 'dev'
+Requires-Dist: isort>=8.0.1; extra == 'dev'
+Requires-Dist: mypy>=2.3.0; extra == 'dev'
+Requires-Dist: pre-commit>=3.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: types-cachetools>=5.3.0; extra == 'dev'
+Requires-Dist: types-python-dateutil>=2.9.0.20260716; extra == 'dev'
+Provides-Extra: integration
+Requires-Dist: psycopg[binary]>=3.3.4; extra == 'integration'
+Description-Content-Type: text/markdown
+
+# Finatic Server SDK (Python)
+
+Python SDK for embedding Finatic in **your backend**. Keep the company API key on the server. Mint a 90-second one-time token for the browser Client SDK, or start a session and redirect to Connect.
+
+## Install
+
+```bash
+pip install finatic-server-python
+```
+
+## Quick start
+
+```python
+import asyncio
+import os
+
+from finatic_server_python import FinaticServer
+
+
+async def main() -> None:
+    finatic = FinaticServer(
+        api_key=os.environ["FINATIC_API_KEY"],
+        sdk_config={"environment": "sandbox"},
+    )
+
+    # Client iframe: 90-second token. Never send the API key to the browser.
+    one_time_token = await finatic.v1.get_token()
+
+    # Redirect flow: start a session first (get_portal_url requires it).
+    session = await finatic.v1.start_session()
+    if not session.get("session_id"):
+        raise RuntimeError(session.get("error") or "Session start failed")
+    portal_url = await finatic.v1.get_portal_url(mode="dark")
+
+    # After account.grant.created, start a session for that portal user, then read.
+    portal_user_id = "user-from-connect-onSuccess"
+    authed = await finatic.v1.start_session(user_id=portal_user_id)
+    if not authed.get("session_id"):
+        raise RuntimeError(authed.get("error") or "Authenticated session start failed")
+    accounts = await finatic.v1.list_accounts(include_sync_status=True)
+    if accounts.get("errors"):
+        raise RuntimeError(accounts["errors"])
+    if not accounts.get("data"):
+        raise RuntimeError("No granted accounts yet")
+    account_id = accounts["data"][0]["accountId"]
+    positions = await finatic.v1.list_positions(account_id)
+
+
+asyncio.run(main())
+```
+
+Server `v1` data methods return `{ "traceId", "data", "warnings", "errors" }`. Check `errors` before using `data`.
+
+Use `sdk_config={"environment": "sandbox"}` for Finatic synthetic data (`fntc_sandbox_` keys). Broker paper/sim accounts stay `live`.
+
+`FinaticServer.init(...)` is a shortcut that calls `start_session`. Use the constructor + `get_token()` when you only need to hand a token to the browser.
+
+## Embed Connect
+
+Connect UI lives in **FinaticConnect**. This SDK does not open an iframe.
+
+1. `v1.get_token()` → pass the token to `@finatic/client` `FinaticConnect.init(token)` in the browser (token TTL is 90 seconds).
+2. Or `v1.start_session()` then `v1.get_portal_url(...)` → redirect. Treat the full URL as secret.
+
+Wait for HTTPS webhook `account.grant.created` (or poll `list_accounts` on an ACTIVE session) before account-scoped reads.
+
+## Trading
+
+Fetch the broker schema, then send an idempotent command:
+
+```python
+schema = await finatic.v1.get_account_order_schema(account_id, "place")
+created = await finatic.v1.create_account_order(
+    account_id,
+    {"symbol": "AAPL", "quantity": 1, "side": "BUY", "type": "MARKET"},
+    idempotency_key="partner-order-123",
+)
+```
+
+Python wraps the dict as `{"order": ...}` on the wire. `idempotency_key` is required.
+
+## Package layout
+
+| Name | Role |
+|------|------|
+| `finatic-server-python` | PyPI package |
+| `finatic_server_python` | Public import |
+| `src` | Hand-written `FinaticServer` and `v1.V1Client` |
+| `finatic_server` | Generated OpenAPI transport — prefer `FinaticServer.v1` |
+
+## Common commands
+
+| Task | Command |
+|------|---------|
+| Test | `pytest` |
+| Type check | `mypy` |
+
+## Documentation
+
+This README is the Python SDK contract. Fetch the rest before writing a full integration:
+
+- Quick start: [https://finatic.dev/docs/quick-start/quick-start](https://finatic.dev/docs/quick-start/quick-start)
+- Client SDK README: [https://github.com/FinaticORG/FinaticClientSDK/blob/develop/README.md](https://github.com/FinaticORG/FinaticClientSDK/blob/develop/README.md)
+- Node SDK README: [https://github.com/FinaticORG/FinaticServerSDK-Node/blob/develop/README.md](https://github.com/FinaticORG/FinaticServerSDK-Node/blob/develop/README.md)
+- Embed Connect: [https://finatic.dev/docs/quick-start/account-grants](https://finatic.dev/docs/quick-start/account-grants)
+- Demo apps: [https://github.com/FinaticORG/FinaticDemoApps/blob/develop/README.md](https://github.com/FinaticORG/FinaticDemoApps/blob/develop/README.md)
+- API reference: [https://finatic.dev/docs/api-reference](https://finatic.dev/docs/api-reference)
+- OpenAPI: [https://finatic.dev/openapi.json](https://finatic.dev/openapi.json)
+- Agent index: [https://finatic.dev/llms.txt](https://finatic.dev/llms.txt)
+- Agent notes: [https://finatic.dev/AGENTS.md](https://finatic.dev/AGENTS.md)

finatic_server_python-1.0.4/README.md

@@ -0,0 +1,110 @@
+# Finatic Server SDK (Python)
+
+Python SDK for embedding Finatic in **your backend**. Keep the company API key on the server. Mint a 90-second one-time token for the browser Client SDK, or start a session and redirect to Connect.
+
+## Install
+
+```bash
+pip install finatic-server-python
+```
+
+## Quick start
+
+```python
+import asyncio
+import os
+
+from finatic_server_python import FinaticServer
+
+
+async def main() -> None:
+    finatic = FinaticServer(
+        api_key=os.environ["FINATIC_API_KEY"],
+        sdk_config={"environment": "sandbox"},
+    )
+
+    # Client iframe: 90-second token. Never send the API key to the browser.
+    one_time_token = await finatic.v1.get_token()
+
+    # Redirect flow: start a session first (get_portal_url requires it).
+    session = await finatic.v1.start_session()
+    if not session.get("session_id"):
+        raise RuntimeError(session.get("error") or "Session start failed")
+    portal_url = await finatic.v1.get_portal_url(mode="dark")
+
+    # After account.grant.created, start a session for that portal user, then read.
+    portal_user_id = "user-from-connect-onSuccess"
+    authed = await finatic.v1.start_session(user_id=portal_user_id)
+    if not authed.get("session_id"):
+        raise RuntimeError(authed.get("error") or "Authenticated session start failed")
+    accounts = await finatic.v1.list_accounts(include_sync_status=True)
+    if accounts.get("errors"):
+        raise RuntimeError(accounts["errors"])
+    if not accounts.get("data"):
+        raise RuntimeError("No granted accounts yet")
+    account_id = accounts["data"][0]["accountId"]
+    positions = await finatic.v1.list_positions(account_id)
+
+
+asyncio.run(main())
+```
+
+Server `v1` data methods return `{ "traceId", "data", "warnings", "errors" }`. Check `errors` before using `data`.
+
+Use `sdk_config={"environment": "sandbox"}` for Finatic synthetic data (`fntc_sandbox_` keys). Broker paper/sim accounts stay `live`.
+
+`FinaticServer.init(...)` is a shortcut that calls `start_session`. Use the constructor + `get_token()` when you only need to hand a token to the browser.
+
+## Embed Connect
+
+Connect UI lives in **FinaticConnect**. This SDK does not open an iframe.
+
+1. `v1.get_token()` → pass the token to `@finatic/client` `FinaticConnect.init(token)` in the browser (token TTL is 90 seconds).
+2. Or `v1.start_session()` then `v1.get_portal_url(...)` → redirect. Treat the full URL as secret.
+
+Wait for HTTPS webhook `account.grant.created` (or poll `list_accounts` on an ACTIVE session) before account-scoped reads.
+
+## Trading
+
+Fetch the broker schema, then send an idempotent command:
+
+```python
+schema = await finatic.v1.get_account_order_schema(account_id, "place")
+created = await finatic.v1.create_account_order(
+    account_id,
+    {"symbol": "AAPL", "quantity": 1, "side": "BUY", "type": "MARKET"},
+    idempotency_key="partner-order-123",
+)
+```
+
+Python wraps the dict as `{"order": ...}` on the wire. `idempotency_key` is required.
+
+## Package layout
+
+| Name | Role |
+|------|------|
+| `finatic-server-python` | PyPI package |
+| `finatic_server_python` | Public import |
+| `src` | Hand-written `FinaticServer` and `v1.V1Client` |
+| `finatic_server` | Generated OpenAPI transport — prefer `FinaticServer.v1` |
+
+## Common commands
+
+| Task | Command |
+|------|---------|
+| Test | `pytest` |
+| Type check | `mypy` |
+
+## Documentation
+
+This README is the Python SDK contract. Fetch the rest before writing a full integration:
+
+- Quick start: [https://finatic.dev/docs/quick-start/quick-start](https://finatic.dev/docs/quick-start/quick-start)
+- Client SDK README: [https://github.com/FinaticORG/FinaticClientSDK/blob/develop/README.md](https://github.com/FinaticORG/FinaticClientSDK/blob/develop/README.md)
+- Node SDK README: [https://github.com/FinaticORG/FinaticServerSDK-Node/blob/develop/README.md](https://github.com/FinaticORG/FinaticServerSDK-Node/blob/develop/README.md)
+- Embed Connect: [https://finatic.dev/docs/quick-start/account-grants](https://finatic.dev/docs/quick-start/account-grants)
+- Demo apps: [https://github.com/FinaticORG/FinaticDemoApps/blob/develop/README.md](https://github.com/FinaticORG/FinaticDemoApps/blob/develop/README.md)
+- API reference: [https://finatic.dev/docs/api-reference](https://finatic.dev/docs/api-reference)
+- OpenAPI: [https://finatic.dev/openapi.json](https://finatic.dev/openapi.json)
+- Agent index: [https://finatic.dev/llms.txt](https://finatic.dev/llms.txt)
+- Agent notes: [https://finatic.dev/AGENTS.md](https://finatic.dev/AGENTS.md)

{finatic_server_python-1.0.3 → finatic_server_python-1.0.4}/finatic_server_python/__init__.py

@@ -6,20 +6,21 @@ Import::
 
     from finatic_server_python import FinaticServer
 
-    finatic = FinaticServer(api_key="...")
-    await finatic.v1.create_session()
-    await finatic.v1.create_portal_link()
+    finatic = FinaticServer(
+        api_key="fntc_sandbox_your_key",
+        sdk_config={"environment": "sandbox"},
+    )
+    token = await finatic.v1.get_token()  # 90 seconds; send to the browser only
 
 Package layout:
 
 - ``finatic_server_python`` — stable public import name (this shim re-exports ``src``).
 - ``src`` — hand-written SDK: ``FinaticServer``, ``FinaticServerCore``, ``v1.V1Client``.
 - ``finatic_server`` — generated OpenAPI transport client (``src/openapi/finatic_server``).
-  Use ``finatic_server`` only for low-level generated APIs; prefer ``FinaticServer.v1``.
+  Prefer ``FinaticServer.v1``.
 
-Portal auth flows (institutions, auth-attempts, discovered accounts, grant consent UI)
-run in **FinaticConnect**, not the server SDK. The server SDK exposes session +
-``portal-links`` creation and post-consent account/grant/webhook APIs.
+Portal auth UX runs in **FinaticConnect**. This SDK mints one-time tokens and portal URLs
+and exposes post-grant account, order, grant, and webhook APIs.
 """
 
 from __future__ import annotations

{finatic_server_python-1.0.3 → finatic_server_python-1.0.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "finatic-server-python"
-version = "1.0.3"
+version = "1.0.4"
 description = "Python SDK for Finatic Server API"
 authors = [{ name = "Finatic", email = "support@finatic.dev" }]
 license = { text = "PROPRIETARY" }
@@ -24,14 +24,14 @@ classifiers = [
 keywords = ["finatic", "trading", "finance", "api", "sdk"]
 dependencies = [
     "aiohttp-retry>=2.9.1",
-    "aiohttp>=3.13.2",
-    "cachetools>=6.2.2",
+    "aiohttp>=3.14.3",
+    "cachetools>=7.1.7",
     "pydantic>=2.12.5",
     "python-dateutil>=2.9.0.post0",
     "structlog>=25.5.0",
     "tenacity>=9.1.2",
-    "typing-extensions>=4.15.0",
-    "urllib3>=2.6.1",
+    "typing-extensions>=4.16.0",
+    "urllib3>=2.7.0",
 ]
 
 [project.optional-dependencies]
@@ -40,15 +40,15 @@ dev = [
     "pytest-asyncio>=0.21.0",
     "pytest-cov>=4.0.0",
     "black>=23.0.0",
-    "isort>=5.12.0",
-    "flake8>=6.0.0",
-    "mypy>=1.0.0",
+    "isort>=8.0.1",
+    "flake8>=7.3.0",
+    "mypy>=2.3.0",
     "pre-commit>=3.0.0",
-    "build>=1.2.2",
+    "build>=1.5.0",
     "types-cachetools>=5.3.0",
-    "types-python-dateutil>=2.8.0",
+    "types-python-dateutil>=2.9.0.20260716",
 ]
-integration = ["psycopg[binary]>=3.2.0"]
+integration = ["psycopg[binary]>=3.3.4"]
 
 [project.urls]
 Homepage = "https://github.com/FinaticORG/FinaticServerSDK-Python"

{finatic_server_python-1.0.3 → finatic_server_python-1.0.4}/src/v1.py

@@ -130,6 +130,16 @@ class V1Client:
         )
 
     async def get_token(self, api_key: str | None = None) -> str:
+        """Mint a 90-second one-time token for the browser Client SDK.
+
+        Does not start a session. For redirect, call ``start_session()`` then
+        ``get_portal_url()``.
+
+        @example
+        ```python
+        token = await finatic.v1.get_token()
+        ```
+        """
         response = await self.init_session(api_key)
         if response.get("errors"):
             errors = response["errors"]
@@ -222,6 +232,14 @@ class V1Client:
         email: str | None = None,
         mode: Literal["light", "dark"] | None = None,
     ) -> str:
+        """Return a Connect redirect URL. Does not open a browser iframe.
+
+        @example
+        ```python
+        session = await finatic.v1.start_session()
+        portal_url = await finatic.v1.get_portal_url(mode='dark')
+        ```
+        """
         if not self.session_id:
             raise ValueError("Session not initialized. Call v1.start_session() first.")
 
@@ -289,6 +307,14 @@ class V1Client:
         offset: int | None = None,
         include_sync_status: bool | None = None,
     ) -> FinaticResponse:
+        """List granted financial accounts. Server envelope uses ``data`` / ``errors``.
+
+        @example
+        ```python
+        result = await finatic.v1.list_accounts()
+        print(result.get('data'), result.get('traceId'))
+        ```
+        """
         return await self._request(
             "GET",
             "/api/v1/accounts",
@@ -329,6 +355,13 @@ class V1Client:
     async def list_positions(
         self, account_id: str, *, limit: int | None = None, offset: int | None = None
     ) -> FinaticResponse:
+        """Positions for one financial account.
+
+        @example
+        ```python
+        result = await finatic.v1.list_positions('acct_123')
+        ```
+        """
         return await self.list_account_resource(
             account_id, "positions", limit=limit, offset=offset
         )