# 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.1",
"maintainer_email": null,
"keywords": "finatic, trading, finance, api, sdk",
"author": null,
"author_email": "Finatic <support@finatic.dev>",
"download_url": "https://files.pythonhosted.org/packages/93/ff/75b7c983b792680bf0f67208054464ec1f8dd543b5898b61b985ed4485d1/finatic_server_python-0.1.2.tar.gz",
"platform": null,
"description": "# Finatic Server Python SDK\n\nA Python SDK for integrating with Finatic's server-side trading and portfolio management APIs.\n\n## Installation\n\n```bash\npip install finatic-server-python\n```\n\n## Quick Start\n\n```python\nimport asyncio\nfrom finatic_server import FinaticServerClient\n\nasync def main():\n # Initialize with API key\n client = FinaticServerClient(\"your-api-key\")\n \n # Option 1: Portal Authentication\n await client.start_session()\n portal_url = await client.get_portal_url()\n print(f\"User should visit: {portal_url}\")\n \n # After user completes authentication in portal, get user info\n user_info = await client.get_session_user()\n print(f\"Authenticated user: {user_info['user_id']}\")\n \n # Option 2: Direct Authentication (if you know the user ID)\n # client = FinaticServerClient(\"your-api-key\", user_id=\"user123\")\n # await client.start_session()\n \n # Now you can access broker data\n brokers = await client.get_broker_list()\n print(f\"Available brokers: {len(brokers)}\")\n \n # Get all orders across all pages\n all_orders = await client.get_all_broker_orders()\n print(f\"Total orders: {len(all_orders)}\")\n\n# Run the example\nasyncio.run(main())\n```\n\n## Authentication Flow\n\nThe SDK supports two authentication methods:\n\n### 1. Portal Authentication (User completes auth in browser)\n\n```python\nclient = FinaticServerClient(\"your-api-key\")\n\n# Start session\nawait client.start_session()\n\n# Get portal URL for user authentication\nportal_url = await client.get_portal_url()\nprint(f\"User should visit: {portal_url}\")\n\n# After user completes authentication in portal\nuser_info = await client.get_session_user()\nprint(f\"User ID: {user_info['user_id']}\")\nprint(f\"Access Token: {user_info['access_token']}\")\n\n# Now you can make authenticated requests\nbrokers = await client.get_broker_list()\n```\n\n### 2. Direct Authentication (Server-side with known user ID)\n\n```python\nclient = FinaticServerClient(\"your-api-key\", user_id=\"user123\")\n\n# Start session (automatically authenticates with user ID)\nawait client.start_session()\n\n# Now you can make authenticated requests immediately\nbrokers = await client.get_broker_list()\n```\n\n## Core Features\n\n- **API Key Authentication**: Secure server-side authentication\n- **Portal Integration**: Get portal URLs for user authentication\n- **Automatic Token Management**: Handles access/refresh tokens automatically\n- **Pagination Support**: Built-in pagination for large datasets\n- **Type-safe API**: Full Pydantic model support\n- **Async/await Support**: Non-blocking operations\n- **Comprehensive Error Handling**: Detailed error types\n\n## API Reference\n\n### Initialization\n\n```python\nclient = FinaticServerClient(\n api_key=\"your-api-key\",\n user_id=\"user123\", # Optional - for direct authentication\n)\n```\n\n### Authentication Methods\n\n- `start_session()` - Start a new session (authenticates directly if user_id provided)\n- `get_portal_url()` - Get portal URL for user authentication (portal flow only)\n- `get_session_user()` - Get user info and tokens after portal completion (portal flow only)\n\n### Broker Data Methods\n\n#### Basic Methods (with pagination support)\n- `get_broker_list()` - Get list of available brokers\n- `get_broker_connections()` - Get broker connections\n- `get_broker_accounts(page=1, per_page=100, options=None, filters=None)` - Get broker accounts\n- `get_broker_orders(page=1, per_page=100, options=None, filters=None)` - Get broker orders\n- `get_broker_positions(page=1, per_page=100, options=None, filters=None)` - Get broker positions\n\n#### Get All Methods (automatically handles pagination)\n- `get_all_broker_accounts(options=None, filters=None)` - Get all broker accounts across all pages\n- `get_all_broker_orders(options=None, filters=None)` - Get all broker orders across all pages\n- `get_all_broker_positions(options=None, filters=None)` - Get all broker positions across all pages\n\n### Filter Options\n\n```python\nfrom finatic_server.types.broker import BrokerDataOptions, OrdersFilter, PositionsFilter, AccountsFilter\n\n# Basic filtering\noptions = BrokerDataOptions(\n broker_name=\"robinhood\",\n account_id=\"123456\",\n symbol=\"AAPL\"\n)\n\n# Advanced filtering for orders\norder_filters = OrdersFilter(\n status=\"filled\",\n side=\"buy\",\n asset_type=\"stock\",\n created_after=\"2024-01-01T00:00:00Z\"\n)\n\n# Advanced filtering for positions\nposition_filters = PositionsFilter(\n symbol=\"AAPL\",\n side=\"long\",\n asset_type=\"stock\"\n)\n\n# Advanced filtering for accounts\naccount_filters = AccountsFilter(\n account_type=\"margin\",\n status=\"active\",\n currency=\"USD\"\n)\n```\n\n## Usage Examples\n\n### Get All Orders with Filtering\n\n```python\n# Get all filled orders for a specific symbol\nall_filled_orders = await client.get_all_broker_orders(\n filters=OrdersFilter(\n status=\"filled\",\n symbol=\"AAPL\"\n )\n)\nprint(f\"Found {len(all_filled_orders)} filled AAPL orders\")\n```\n\n### Pagination Example\n\n```python\n# Get first page of 10 orders\nfirst_page = await client.get_broker_orders(page=1, per_page=10)\nprint(f\"First page: {len(first_page)} orders\")\n\n# Get second page\nsecond_page = await client.get_broker_orders(page=2, per_page=10)\nprint(f\"Second page: {len(second_page)} orders\")\n```\n\n### Get All Data for Analysis\n\n```python\n# Get all accounts, orders, and positions\nall_accounts = await client.get_all_broker_accounts()\nall_orders = await client.get_all_broker_orders()\nall_positions = await client.get_all_broker_positions()\n\nprint(f\"Total accounts: {len(all_accounts)}\")\nprint(f\"Total orders: {len(all_orders)}\")\nprint(f\"Total positions: {len(all_positions)}\")\n```\n\n### Filter by Broker\n\n```python\n# Get all orders from Robinhood\nrobinhood_orders = await client.get_all_broker_orders(\n options=BrokerDataOptions(broker_name=\"robinhood\")\n)\n\n# Get all positions from Tasty Trade\ntasty_positions = await client.get_all_broker_positions(\n options=BrokerDataOptions(broker_name=\"tasty_trade\")\n)\n```\n\n## Error Handling\n\nThe SDK provides comprehensive error handling:\n\n```python\nfrom finatic_server import AuthenticationError, ApiError, NetworkError\n\ntry:\n orders = await client.get_broker_orders()\nexcept AuthenticationError as e:\n print(f\"Authentication failed: {e}\")\nexcept NetworkError as e:\n print(f\"Network error: {e}\")\nexcept ApiError as e:\n print(f\"API error: {e}\")\n```\n\n## Complete Example\n\n```python\nimport asyncio\nfrom finatic_server import FinaticServerClient\nfrom finatic_server.types.broker import OrdersFilter, BrokerDataOptions\n\nasync def main():\n # Option 1: Portal Authentication (user completes auth in browser)\n client = FinaticServerClient(\"your-api-key\")\n \n try:\n # Start session\n await client.start_session()\n \n # Get portal URL\n portal_url = await client.get_portal_url()\n print(f\"Please visit: {portal_url}\")\n \n # Wait for user to complete authentication\n input(\"Press Enter after completing authentication...\")\n \n # Get user info\n user_info = await client.get_session_user()\n print(f\"Authenticated as: {user_info['user_id']}\")\n \n # Option 2: Direct Authentication (if you know the user ID)\n # client = FinaticServerClient(\"your-api-key\", user_id=\"user123\")\n # await client.start_session()\n # print(\"Directly authenticated!\")\n \n # Get broker information\n brokers = await client.get_broker_list()\n print(f\"Available brokers: {[b.name for b in brokers]}\")\n \n # Get all filled orders\n filled_orders = await client.get_all_broker_orders(\n filters=OrdersFilter(status=\"filled\")\n )\n print(f\"Total filled orders: {len(filled_orders)}\")\n \n # Get all positions\n positions = await client.get_all_broker_positions()\n print(f\"Total positions: {len(positions)}\")\n \n # Get accounts with cash balance\n accounts = await client.get_all_broker_accounts()\n for account in accounts:\n cash = account.cash_balance or 0.0\n print(f\"{account.account_name}: ${cash:,.2f}\")\n \n except Exception as e:\n print(f\"Error: {e}\")\n finally:\n await client.close()\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n```\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details. \n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python SDK for Finatic Server API",
"version": "0.1.2",
"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": "d58d36ae6c3e6fa0bc2fa42ba27a5b189076bf0aa2dd50a211ceca8e09129596",
"md5": "9f3367211bebe8fba1d7439b0a32ddc6",
"sha256": "b60aa111f9210c345c160f699e283310ca88b60e3f62038a4a27a3343d1b0266"
},
"downloads": -1,
"filename": "finatic_server_python-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9f3367211bebe8fba1d7439b0a32ddc6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8.1",
"size": 27416,
"upload_time": "2025-08-31T16:46:48",
"upload_time_iso_8601": "2025-08-31T16:46:48.674636Z",
"url": "https://files.pythonhosted.org/packages/d5/8d/36ae6c3e6fa0bc2fa42ba27a5b189076bf0aa2dd50a211ceca8e09129596/finatic_server_python-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "93ff75b7c983b792680bf0f67208054464ec1f8dd543b5898b61b985ed4485d1",
"md5": "879096f93c65377ec7f5647d854c35d8",
"sha256": "4f6cea29cf2f16830f7410d1844ae9ad6abdd570e6f9d962dd73e68a687d2a41"
},
"downloads": -1,
"filename": "finatic_server_python-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "879096f93c65377ec7f5647d854c35d8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8.1",
"size": 26496,
"upload_time": "2025-08-31T16:46:49",
"upload_time_iso_8601": "2025-08-31T16:46:49.842065Z",
"url": "https://files.pythonhosted.org/packages/93/ff/75b7c983b792680bf0f67208054464ec1f8dd543b5898b61b985ed4485d1/finatic_server_python-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-31 16:46:49",
"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
