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)
