# Finatic Server Python SDK
A Python SDK for integrating with Finatic's server-side trading and portfolio management APIs.
## Installation
```bash
pip install finatic-server-python
```
## Quick Start
```python
import asyncio
from finatic_server import FinaticServerClient
async def main():
# Initialize with API key
client = FinaticServerClient("your-api-key")
# Option 1: Portal Authentication
await client.start_session()
portal_url = await client.get_portal_url()
print(f"User should visit: {portal_url}")
# After user completes authentication in portal, get user info
user_info = await client.get_session_user()
print(f"Authenticated user: {user_info['user_id']}")
# Option 2: Direct Authentication (if you know the user ID)
# client = FinaticServerClient("your-api-key", user_id="user123")
# await client.start_session()
# Now you can access broker data
brokers = await client.get_broker_list()
print(f"Available brokers: {len(brokers)}")
# Get all orders across all pages
all_orders = await client.get_all_broker_orders()
print(f"Total orders: {len(all_orders)}")
# Run the example
asyncio.run(main())
```
## Authentication Flow
The SDK supports two authentication methods:
### 1. Portal Authentication (User completes auth in browser)
```python
client = FinaticServerClient("your-api-key")
# Start session
await client.start_session()
# Get portal URL for user authentication
portal_url = await client.get_portal_url()
print(f"User should visit: {portal_url}")
# After user completes authentication in portal
user_info = await client.get_session_user()
print(f"User ID: {user_info['user_id']}")
print(f"Access Token: {user_info['access_token']}")
# Now you can make authenticated requests
brokers = await client.get_broker_list()
```
### 2. Direct Authentication (Server-side with known user ID)
```python
client = FinaticServerClient("your-api-key", user_id="user123")
# Start session (automatically authenticates with user ID)
await client.start_session()
# Now you can make authenticated requests immediately
brokers = await client.get_broker_list()
```
## Core Features
- **API Key Authentication**: Secure server-side authentication
- **Portal Integration**: Get portal URLs for user authentication
- **Automatic Token Management**: Handles access/refresh tokens automatically
- **Pagination Support**: Built-in pagination for large datasets
- **Type-safe API**: Full Pydantic model support
- **Async/await Support**: Non-blocking operations
- **Comprehensive Error Handling**: Detailed error types
## API Reference
### Initialization
```python
client = FinaticServerClient(
api_key="your-api-key",
user_id="user123", # Optional - for direct authentication
)
```
### Authentication Methods
- `start_session()` - Start a new session (authenticates directly if user_id provided)
- `get_portal_url()` - Get portal URL for user authentication (portal flow only)
- `get_session_user()` - Get user info and tokens after portal completion (portal flow only)
### Broker Data Methods
#### Basic Methods (with pagination support)
- `get_broker_list()` - Get list of available brokers
- `get_broker_connections()` - Get broker connections
- `get_broker_accounts(page=1, per_page=100, options=None, filters=None)` - Get broker accounts
- `get_broker_orders(page=1, per_page=100, options=None, filters=None)` - Get broker orders
- `get_broker_positions(page=1, per_page=100, options=None, filters=None)` - Get broker positions
#### Get All Methods (automatically handles pagination)
- `get_all_broker_accounts(options=None, filters=None)` - Get all broker accounts across all pages
- `get_all_broker_orders(options=None, filters=None)` - Get all broker orders across all pages
- `get_all_broker_positions(options=None, filters=None)` - Get all broker positions across all pages
### Filter Options
```python
from finatic_server.types.broker import BrokerDataOptions, OrdersFilter, PositionsFilter, AccountsFilter
# Basic filtering
options = BrokerDataOptions(
broker_name="robinhood",
account_id="123456",
symbol="AAPL"
)
# Advanced filtering for orders
order_filters = OrdersFilter(
status="filled",
side="buy",
asset_type="stock",
created_after="2024-01-01T00:00:00Z"
)
# Advanced filtering for positions
position_filters = PositionsFilter(
symbol="AAPL",
side="long",
asset_type="stock"
)
# Advanced filtering for accounts
account_filters = AccountsFilter(
account_type="margin",
status="active",
currency="USD"
)
```
## Usage Examples
### Get All Orders with Filtering
```python
# Get all filled orders for a specific symbol
all_filled_orders = await client.get_all_broker_orders(
filters=OrdersFilter(
status="filled",
symbol="AAPL"
)
)
print(f"Found {len(all_filled_orders)} filled AAPL orders")
```
### Pagination Example
```python
# Get first page of 10 orders
first_page = await client.get_broker_orders(page=1, per_page=10)
print(f"First page: {len(first_page)} orders")
# Get second page
second_page = await client.get_broker_orders(page=2, per_page=10)
print(f"Second page: {len(second_page)} orders")
```
### Get All Data for Analysis
```python
# Get all accounts, orders, and positions
all_accounts = await client.get_all_broker_accounts()
all_orders = await client.get_all_broker_orders()
all_positions = await client.get_all_broker_positions()
print(f"Total accounts: {len(all_accounts)}")
print(f"Total orders: {len(all_orders)}")
print(f"Total positions: {len(all_positions)}")
```
### Filter by Broker
```python
# Get all orders from Robinhood
robinhood_orders = await client.get_all_broker_orders(
options=BrokerDataOptions(broker_name="robinhood")
)
# Get all positions from Tasty Trade
tasty_positions = await client.get_all_broker_positions(
options=BrokerDataOptions(broker_name="tasty_trade")
)
```
## Error Handling
The SDK provides comprehensive error handling:
```python
from finatic_server import AuthenticationError, ApiError, NetworkError
try:
orders = await client.get_broker_orders()
except AuthenticationError as e:
print(f"Authentication failed: {e}")
except NetworkError as e:
print(f"Network error: {e}")
except ApiError as e:
print(f"API error: {e}")
```
## Complete Example
```python
import asyncio
from finatic_server import FinaticServerClient
from finatic_server.types.broker import OrdersFilter, BrokerDataOptions
async def main():
# Option 1: Portal Authentication (user completes auth in browser)
client = FinaticServerClient("your-api-key")
try:
# Start session
await client.start_session()
# Get portal URL
portal_url = await client.get_portal_url()
print(f"Please visit: {portal_url}")
# Wait for user to complete authentication
input("Press Enter after completing authentication...")
# Get user info
user_info = await client.get_session_user()
print(f"Authenticated as: {user_info['user_id']}")
# Option 2: Direct Authentication (if you know the user ID)
# client = FinaticServerClient("your-api-key", user_id="user123")
# await client.start_session()
# print("Directly authenticated!")
# Get broker information
brokers = await client.get_broker_list()
print(f"Available brokers: {[b.name for b in brokers]}")
# Get all filled orders
filled_orders = await client.get_all_broker_orders(
filters=OrdersFilter(status="filled")
)
print(f"Total filled orders: {len(filled_orders)}")
# Get all positions
positions = await client.get_all_broker_positions()
print(f"Total positions: {len(positions)}")
# Get accounts with cash balance
accounts = await client.get_all_broker_accounts()
for account in accounts:
cash = account.cash_balance or 0.0
print(f"{account.account_name}: ${cash:,.2f}")
except Exception as e:
print(f"Error: {e}")
finally:
await client.close()
if __name__ == "__main__":
asyncio.run(main())
```
## License
MIT License - see [LICENSE](LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "finatic-server-python",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "finatic, trading, finance, api, sdk",
"author": null,
"author_email": "Finatic <support@finatic.dev>",
"download_url": "https://files.pythonhosted.org/packages/60/af/dfd37fcd9a3cef53ebdf9e40f639d9d20e0adedb763ec6908722ebde7688/finatic_server_python-0.1.0.tar.gz",
"platform": null,
"description": "# Finatic Server Python SDK\r\n\r\nA Python SDK for integrating with Finatic's server-side trading and portfolio management APIs.\r\n\r\n## Installation\r\n\r\n```bash\r\npip install finatic-server-python\r\n```\r\n\r\n## Quick Start\r\n\r\n```python\r\nimport asyncio\r\nfrom finatic_server import FinaticServerClient\r\n\r\nasync def main():\r\n # Initialize with API key\r\n client = FinaticServerClient(\"your-api-key\")\r\n \r\n # Option 1: Portal Authentication\r\n await client.start_session()\r\n portal_url = await client.get_portal_url()\r\n print(f\"User should visit: {portal_url}\")\r\n \r\n # After user completes authentication in portal, get user info\r\n user_info = await client.get_session_user()\r\n print(f\"Authenticated user: {user_info['user_id']}\")\r\n \r\n # Option 2: Direct Authentication (if you know the user ID)\r\n # client = FinaticServerClient(\"your-api-key\", user_id=\"user123\")\r\n # await client.start_session()\r\n \r\n # Now you can access broker data\r\n brokers = await client.get_broker_list()\r\n print(f\"Available brokers: {len(brokers)}\")\r\n \r\n # Get all orders across all pages\r\n all_orders = await client.get_all_broker_orders()\r\n print(f\"Total orders: {len(all_orders)}\")\r\n\r\n# Run the example\r\nasyncio.run(main())\r\n```\r\n\r\n## Authentication Flow\r\n\r\nThe SDK supports two authentication methods:\r\n\r\n### 1. Portal Authentication (User completes auth in browser)\r\n\r\n```python\r\nclient = FinaticServerClient(\"your-api-key\")\r\n\r\n# Start session\r\nawait client.start_session()\r\n\r\n# Get portal URL for user authentication\r\nportal_url = await client.get_portal_url()\r\nprint(f\"User should visit: {portal_url}\")\r\n\r\n# After user completes authentication in portal\r\nuser_info = await client.get_session_user()\r\nprint(f\"User ID: {user_info['user_id']}\")\r\nprint(f\"Access Token: {user_info['access_token']}\")\r\n\r\n# Now you can make authenticated requests\r\nbrokers = await client.get_broker_list()\r\n```\r\n\r\n### 2. Direct Authentication (Server-side with known user ID)\r\n\r\n```python\r\nclient = FinaticServerClient(\"your-api-key\", user_id=\"user123\")\r\n\r\n# Start session (automatically authenticates with user ID)\r\nawait client.start_session()\r\n\r\n# Now you can make authenticated requests immediately\r\nbrokers = await client.get_broker_list()\r\n```\r\n\r\n## Core Features\r\n\r\n- **API Key Authentication**: Secure server-side authentication\r\n- **Portal Integration**: Get portal URLs for user authentication\r\n- **Automatic Token Management**: Handles access/refresh tokens automatically\r\n- **Pagination Support**: Built-in pagination for large datasets\r\n- **Type-safe API**: Full Pydantic model support\r\n- **Async/await Support**: Non-blocking operations\r\n- **Comprehensive Error Handling**: Detailed error types\r\n\r\n## API Reference\r\n\r\n### Initialization\r\n\r\n```python\r\nclient = FinaticServerClient(\r\n api_key=\"your-api-key\",\r\n user_id=\"user123\", # Optional - for direct authentication\r\n)\r\n```\r\n\r\n### Authentication Methods\r\n\r\n- `start_session()` - Start a new session (authenticates directly if user_id provided)\r\n- `get_portal_url()` - Get portal URL for user authentication (portal flow only)\r\n- `get_session_user()` - Get user info and tokens after portal completion (portal flow only)\r\n\r\n### Broker Data Methods\r\n\r\n#### Basic Methods (with pagination support)\r\n- `get_broker_list()` - Get list of available brokers\r\n- `get_broker_connections()` - Get broker connections\r\n- `get_broker_accounts(page=1, per_page=100, options=None, filters=None)` - Get broker accounts\r\n- `get_broker_orders(page=1, per_page=100, options=None, filters=None)` - Get broker orders\r\n- `get_broker_positions(page=1, per_page=100, options=None, filters=None)` - Get broker positions\r\n\r\n#### Get All Methods (automatically handles pagination)\r\n- `get_all_broker_accounts(options=None, filters=None)` - Get all broker accounts across all pages\r\n- `get_all_broker_orders(options=None, filters=None)` - Get all broker orders across all pages\r\n- `get_all_broker_positions(options=None, filters=None)` - Get all broker positions across all pages\r\n\r\n### Filter Options\r\n\r\n```python\r\nfrom finatic_server.types.broker import BrokerDataOptions, OrdersFilter, PositionsFilter, AccountsFilter\r\n\r\n# Basic filtering\r\noptions = BrokerDataOptions(\r\n broker_name=\"robinhood\",\r\n account_id=\"123456\",\r\n symbol=\"AAPL\"\r\n)\r\n\r\n# Advanced filtering for orders\r\norder_filters = OrdersFilter(\r\n status=\"filled\",\r\n side=\"buy\",\r\n asset_type=\"stock\",\r\n created_after=\"2024-01-01T00:00:00Z\"\r\n)\r\n\r\n# Advanced filtering for positions\r\nposition_filters = PositionsFilter(\r\n symbol=\"AAPL\",\r\n side=\"long\",\r\n asset_type=\"stock\"\r\n)\r\n\r\n# Advanced filtering for accounts\r\naccount_filters = AccountsFilter(\r\n account_type=\"margin\",\r\n status=\"active\",\r\n currency=\"USD\"\r\n)\r\n```\r\n\r\n## Usage Examples\r\n\r\n### Get All Orders with Filtering\r\n\r\n```python\r\n# Get all filled orders for a specific symbol\r\nall_filled_orders = await client.get_all_broker_orders(\r\n filters=OrdersFilter(\r\n status=\"filled\",\r\n symbol=\"AAPL\"\r\n )\r\n)\r\nprint(f\"Found {len(all_filled_orders)} filled AAPL orders\")\r\n```\r\n\r\n### Pagination Example\r\n\r\n```python\r\n# Get first page of 10 orders\r\nfirst_page = await client.get_broker_orders(page=1, per_page=10)\r\nprint(f\"First page: {len(first_page)} orders\")\r\n\r\n# Get second page\r\nsecond_page = await client.get_broker_orders(page=2, per_page=10)\r\nprint(f\"Second page: {len(second_page)} orders\")\r\n```\r\n\r\n### Get All Data for Analysis\r\n\r\n```python\r\n# Get all accounts, orders, and positions\r\nall_accounts = await client.get_all_broker_accounts()\r\nall_orders = await client.get_all_broker_orders()\r\nall_positions = await client.get_all_broker_positions()\r\n\r\nprint(f\"Total accounts: {len(all_accounts)}\")\r\nprint(f\"Total orders: {len(all_orders)}\")\r\nprint(f\"Total positions: {len(all_positions)}\")\r\n```\r\n\r\n### Filter by Broker\r\n\r\n```python\r\n# Get all orders from Robinhood\r\nrobinhood_orders = await client.get_all_broker_orders(\r\n options=BrokerDataOptions(broker_name=\"robinhood\")\r\n)\r\n\r\n# Get all positions from Tasty Trade\r\ntasty_positions = await client.get_all_broker_positions(\r\n options=BrokerDataOptions(broker_name=\"tasty_trade\")\r\n)\r\n```\r\n\r\n## Error Handling\r\n\r\nThe SDK provides comprehensive error handling:\r\n\r\n```python\r\nfrom finatic_server import AuthenticationError, ApiError, NetworkError\r\n\r\ntry:\r\n orders = await client.get_broker_orders()\r\nexcept AuthenticationError as e:\r\n print(f\"Authentication failed: {e}\")\r\nexcept NetworkError as e:\r\n print(f\"Network error: {e}\")\r\nexcept ApiError as e:\r\n print(f\"API error: {e}\")\r\n```\r\n\r\n## Complete Example\r\n\r\n```python\r\nimport asyncio\r\nfrom finatic_server import FinaticServerClient\r\nfrom finatic_server.types.broker import OrdersFilter, BrokerDataOptions\r\n\r\nasync def main():\r\n # Option 1: Portal Authentication (user completes auth in browser)\r\n client = FinaticServerClient(\"your-api-key\")\r\n \r\n try:\r\n # Start session\r\n await client.start_session()\r\n \r\n # Get portal URL\r\n portal_url = await client.get_portal_url()\r\n print(f\"Please visit: {portal_url}\")\r\n \r\n # Wait for user to complete authentication\r\n input(\"Press Enter after completing authentication...\")\r\n \r\n # Get user info\r\n user_info = await client.get_session_user()\r\n print(f\"Authenticated as: {user_info['user_id']}\")\r\n \r\n # Option 2: Direct Authentication (if you know the user ID)\r\n # client = FinaticServerClient(\"your-api-key\", user_id=\"user123\")\r\n # await client.start_session()\r\n # print(\"Directly authenticated!\")\r\n \r\n # Get broker information\r\n brokers = await client.get_broker_list()\r\n print(f\"Available brokers: {[b.name for b in brokers]}\")\r\n \r\n # Get all filled orders\r\n filled_orders = await client.get_all_broker_orders(\r\n filters=OrdersFilter(status=\"filled\")\r\n )\r\n print(f\"Total filled orders: {len(filled_orders)}\")\r\n \r\n # Get all positions\r\n positions = await client.get_all_broker_positions()\r\n print(f\"Total positions: {len(positions)}\")\r\n \r\n # Get accounts with cash balance\r\n accounts = await client.get_all_broker_accounts()\r\n for account in accounts:\r\n cash = account.cash_balance or 0.0\r\n print(f\"{account.account_name}: ${cash:,.2f}\")\r\n \r\n except Exception as e:\r\n print(f\"Error: {e}\")\r\n finally:\r\n await client.close()\r\n\r\nif __name__ == \"__main__\":\r\n asyncio.run(main())\r\n```\r\n\r\n## License\r\n\r\nMIT License - see [LICENSE](LICENSE) file for details. \r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python SDK for Finatic Server API",
"version": "0.1.0",
"project_urls": {
"Documentation": "https://docs.finatic.com/python",
"Homepage": "https://github.com/finatic/finatic-server-python",
"Issues": "https://github.com/finatic/finatic-server-python/issues",
"Repository": "https://github.com/finatic/finatic-server-python"
},
"split_keywords": [
"finatic",
" trading",
" finance",
" api",
" sdk"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "4c3fd83b1d7d1f6ffd864ca13dd37a45b84cb64c493b46c0b23cb7a7e0a69453",
"md5": "906543e298d3544bf70638d84aa18b90",
"sha256": "4566505d0d3da5361a5d7346f9fc4275c5aceaed39b759d34e8d259d1301cfcc"
},
"downloads": -1,
"filename": "finatic_server_python-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "906543e298d3544bf70638d84aa18b90",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 23173,
"upload_time": "2025-07-25T00:12:26",
"upload_time_iso_8601": "2025-07-25T00:12:26.873274Z",
"url": "https://files.pythonhosted.org/packages/4c/3f/d83b1d7d1f6ffd864ca13dd37a45b84cb64c493b46c0b23cb7a7e0a69453/finatic_server_python-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "60afdfd37fcd9a3cef53ebdf9e40f639d9d20e0adedb763ec6908722ebde7688",
"md5": "dab3933659e0eff2bfa8e0a0ce519098",
"sha256": "b44fb4f1f794ad3a18fa515518a052677654868e5385b17b8f32501a51d09454"
},
"downloads": -1,
"filename": "finatic_server_python-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "dab3933659e0eff2bfa8e0a0ce519098",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 21814,
"upload_time": "2025-07-25T00:12:28",
"upload_time_iso_8601": "2025-07-25T00:12:28.295038Z",
"url": "https://files.pythonhosted.org/packages/60/af/dfd37fcd9a3cef53ebdf9e40f639d9d20e0adedb763ec6908722ebde7688/finatic_server_python-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-25 00:12:28",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "finatic",
"github_project": "finatic-server-python",
"github_not_found": true,
"lcname": "finatic-server-python"
}
JSON
