# Finatic Server Python SDK
A comprehensive 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")
# 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 is now authenticated
print(f"Authenticated user: {client.get_user_id()}")
# Get portfolio 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_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 is now authenticated
print(f"User ID: {client.get_user_id()}")
# 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")
# Start session with user ID (automatically authenticates)
await client.start_session(user_id="user123")
# 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 with optional theming
- **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
- **Convenience Methods**: Helper methods for common data filtering
- **Asset-Specific Orders**: Simplified order placement for different asset types
## API Reference
### Initialization
```python
client = FinaticServerClient(
api_key="your-api-key",
base_url="https://api.finatic.dev", # Optional
device_info={ # Optional
"ip_address": "192.168.1.100",
"user_agent": "MyApp/1.0.0",
},
timeout=30 # Optional
)
```
### Authentication
```python
# Start session
await client.start_session()
# Start session with user ID (direct auth)
await client.start_session(user_id="user123")
# Check authentication status
is_authenticated = client.is_authenticated()
# Get user information
user_id = client.get_user_id()
session_id = client.get_session_id()
company_id = client.get_company_id()
```
### Portal Management
```python
# Get basic portal URL
portal_url = await client.get_portal_url()
# Get portal URL with theming
portal_url = await client.get_portal_url(
theme={"primary_color": "#007bff", "logo_url": "https://example.com/logo.png"},
brokers=["robinhood", "tasty_trade"],
email="user@example.com"
)
```
### Broker Data Access
```python
# Get broker information
brokers = await client.get_broker_list()
connections = await client.get_broker_connections()
# Get accounts with pagination
accounts = await client.get_accounts(page=1, per_page=100)
all_accounts = await client.get_all_accounts()
# Get orders with pagination
orders = await client.get_orders(page=1, per_page=100)
all_orders = await client.get_all_orders()
# Get positions with pagination
positions = await client.get_positions(page=1, per_page=100)
all_positions = await client.get_all_positions()
# Get balances with pagination
balances = await client.get_balances(page=1, per_page=100)
all_balances = await client.get_all_balances()
```
### Convenience Filter Methods
```python
# Get filtered data
open_positions = await client.get_open_positions()
filled_orders = await client.get_filled_orders()
pending_orders = await client.get_pending_orders()
active_accounts = await client.get_active_accounts()
# Get data by symbol
aapl_orders = await client.get_orders_by_symbol("AAPL")
aapl_positions = await client.get_positions_by_symbol("AAPL")
# Get data by broker
robinhood_orders = await client.get_orders_by_broker("robinhood")
robinhood_positions = await client.get_positions_by_broker("robinhood")
```
### Trading Operations
#### General Order Placement
```python
from finatic_server.types.orders import BrokerOrderParams
# Place a market order
order_params = BrokerOrderParams(
broker="robinhood",
order_type="Market",
asset_type="equity",
action="Buy",
time_in_force="day",
account_number="123456789",
symbol="AAPL",
order_qty=10
)
response = await client.place_order(order_params)
```
#### Asset-Specific Order Methods
##### Stock Orders
```python
# Stock market order
response = await client.place_stock_market_order(
symbol="AAPL",
quantity=10,
side="buy",
broker="robinhood",
account_number="123456789"
)
# Stock limit order
response = await client.place_stock_limit_order(
symbol="AAPL",
quantity=10,
side="buy",
price=150.00,
time_in_force="gtc",
broker="robinhood",
account_number="123456789"
)
# Stock stop order
response = await client.place_stock_stop_order(
symbol="AAPL",
quantity=10,
side="sell",
stop_price=140.00,
time_in_force="gtc",
broker="robinhood",
account_number="123456789"
)
```
##### Crypto Orders
```python
# Crypto market order
response = await client.place_crypto_market_order(
symbol="BTC-USD",
quantity=0.1,
side="buy",
broker="coinbase",
account_number="123456789"
)
# Crypto limit order
response = await client.place_crypto_limit_order(
symbol="BTC-USD",
quantity=0.1,
side="buy",
price=50000.00,
time_in_force="gtc",
broker="coinbase",
account_number="123456789"
)
```
##### Options Orders
```python
# Options market order
response = await client.place_options_market_order(
symbol="AAPL240315C00150000",
quantity=1,
side="buy",
broker="tasty_trade",
account_number="123456789"
)
# Options limit order
response = await client.place_options_limit_order(
symbol="AAPL240315C00150000",
quantity=1,
side="buy",
price=5.00,
time_in_force="gtc",
broker="tasty_trade",
account_number="123456789"
)
```
##### Futures Orders
```python
# Futures market order
response = await client.place_futures_market_order(
symbol="ES",
quantity=1,
side="buy",
broker="ninja_trader",
account_number="123456789"
)
# Futures limit order
response = await client.place_futures_limit_order(
symbol="ES",
quantity=1,
side="buy",
price=4500.00,
time_in_force="gtc",
broker="ninja_trader",
account_number="123456789"
)
```
#### Order Management
```python
# Cancel an order
response = await client.cancel_order(
order_id="order-123",
broker="robinhood",
connection_id="connection-456"
)
# Modify an order
response = await client.modify_order(
order_id="order-123",
modifications={"price": 155.00, "quantity": 5},
broker="robinhood",
connection_id="connection-456"
)
```
### Broker Management
```python
# Disconnect a company from broker
response = await client.disconnect_company("connection-123")
```
### Error Handling
```python
from finatic_server.utils.errors import AuthenticationError, ApiError, ValidationError
try:
orders = await client.get_orders()
except AuthenticationError as e:
print(f"Authentication failed: {e}")
except ValidationError as e:
print(f"Invalid request: {e}")
except ApiError as e:
print(f"API error: {e}")
```
### Context Manager Usage
```python
async with FinaticServerClient("your-api-key") as client:
await client.start_session()
brokers = await client.get_broker_list()
# Client automatically closes when exiting context
```
### Cleanup
```python
# Close the client and cleanup resources
await client.close()
```
## Advanced Usage
### Custom Filters
```python
from finatic_server.types import BrokerDataOptions, OrdersFilter
# Get orders with custom filters
orders = await client.get_orders(
page=1,
per_page=50,
options=BrokerDataOptions(
broker_name="robinhood",
account_id="123456789"
),
filters=OrdersFilter(
status="filled",
symbol="AAPL"
)
)
```
### Pagination Navigation
```python
# Get paginated results with navigation
orders_page = await client.get_orders(page=1, per_page=100)
# Navigate through pages
if orders_page.has_next:
next_page = await orders_page.next_page()
if orders_page.has_previous:
prev_page = await orders_page.previous_page()
```
## Type Definitions
The SDK includes comprehensive type definitions for all data structures:
- `BrokerOrder`: Order information
- `BrokerPosition`: Position information
- `BrokerAccount`: Account information
- `BrokerBalance`: Balance information
- `BrokerInfo`: Broker information
- `BrokerConnection`: Connection information
- `OrderResponse`: Order operation responses
- `PaginatedResult`: Paginated data responses
## Error Types
- `AuthenticationError`: Authentication failures
- `ApiError`: API request failures
- `ValidationError`: Invalid request parameters
- `ConnectionError`: Network connectivity issues
## Requirements
- Python 3.8+
- aiohttp
- pydantic
## License
MIT License
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/b1/0a/9207fa10622db36f6265b83d837184b2940e1462b94aa79c86057252281d/finatic_server_python-0.1.6.tar.gz",
"platform": null,
"description": "# Finatic Server Python SDK\n\nA comprehensive 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 # Start session\n await client.start_session()\n\n # Get portal URL for user authentication\n portal_url = await client.get_portal_url()\n print(f\"User should visit: {portal_url}\")\n\n # After user completes authentication in portal\n # User is now authenticated\n print(f\"Authenticated user: {client.get_user_id()}\")\n\n # Get portfolio 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_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\n# User is now authenticated\nprint(f\"User ID: {client.get_user_id()}\")\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\")\n\n# Start session with user ID (automatically authenticates)\nawait client.start_session(user_id=\"user123\")\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 with optional theming\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- **Convenience Methods**: Helper methods for common data filtering\n- **Asset-Specific Orders**: Simplified order placement for different asset types\n\n## API Reference\n\n### Initialization\n\n```python\nclient = FinaticServerClient(\n api_key=\"your-api-key\",\n base_url=\"https://api.finatic.dev\", # Optional\n device_info={ # Optional\n \"ip_address\": \"192.168.1.100\",\n \"user_agent\": \"MyApp/1.0.0\",\n },\n timeout=30 # Optional\n)\n```\n\n### Authentication\n\n```python\n# Start session\nawait client.start_session()\n\n# Start session with user ID (direct auth)\nawait client.start_session(user_id=\"user123\")\n\n# Check authentication status\nis_authenticated = client.is_authenticated()\n\n# Get user information\nuser_id = client.get_user_id()\nsession_id = client.get_session_id()\ncompany_id = client.get_company_id()\n```\n\n### Portal Management\n\n```python\n# Get basic portal URL\nportal_url = await client.get_portal_url()\n\n# Get portal URL with theming\nportal_url = await client.get_portal_url(\n theme={\"primary_color\": \"#007bff\", \"logo_url\": \"https://example.com/logo.png\"},\n brokers=[\"robinhood\", \"tasty_trade\"],\n email=\"user@example.com\"\n)\n```\n\n### Broker Data Access\n\n```python\n# Get broker information\nbrokers = await client.get_broker_list()\nconnections = await client.get_broker_connections()\n\n# Get accounts with pagination\naccounts = await client.get_accounts(page=1, per_page=100)\nall_accounts = await client.get_all_accounts()\n\n# Get orders with pagination\norders = await client.get_orders(page=1, per_page=100)\nall_orders = await client.get_all_orders()\n\n# Get positions with pagination\npositions = await client.get_positions(page=1, per_page=100)\nall_positions = await client.get_all_positions()\n\n# Get balances with pagination\nbalances = await client.get_balances(page=1, per_page=100)\nall_balances = await client.get_all_balances()\n```\n\n### Convenience Filter Methods\n\n```python\n# Get filtered data\nopen_positions = await client.get_open_positions()\nfilled_orders = await client.get_filled_orders()\npending_orders = await client.get_pending_orders()\nactive_accounts = await client.get_active_accounts()\n\n# Get data by symbol\naapl_orders = await client.get_orders_by_symbol(\"AAPL\")\naapl_positions = await client.get_positions_by_symbol(\"AAPL\")\n\n# Get data by broker\nrobinhood_orders = await client.get_orders_by_broker(\"robinhood\")\nrobinhood_positions = await client.get_positions_by_broker(\"robinhood\")\n```\n\n### Trading Operations\n\n#### General Order Placement\n\n```python\nfrom finatic_server.types.orders import BrokerOrderParams\n\n# Place a market order\norder_params = BrokerOrderParams(\n broker=\"robinhood\",\n order_type=\"Market\",\n asset_type=\"equity\",\n action=\"Buy\",\n time_in_force=\"day\",\n account_number=\"123456789\",\n symbol=\"AAPL\",\n order_qty=10\n)\n\nresponse = await client.place_order(order_params)\n```\n\n#### Asset-Specific Order Methods\n\n##### Stock Orders\n\n```python\n# Stock market order\nresponse = await client.place_stock_market_order(\n symbol=\"AAPL\",\n quantity=10,\n side=\"buy\",\n broker=\"robinhood\",\n account_number=\"123456789\"\n)\n\n# Stock limit order\nresponse = await client.place_stock_limit_order(\n symbol=\"AAPL\",\n quantity=10,\n side=\"buy\",\n price=150.00,\n time_in_force=\"gtc\",\n broker=\"robinhood\",\n account_number=\"123456789\"\n)\n\n# Stock stop order\nresponse = await client.place_stock_stop_order(\n symbol=\"AAPL\",\n quantity=10,\n side=\"sell\",\n stop_price=140.00,\n time_in_force=\"gtc\",\n broker=\"robinhood\",\n account_number=\"123456789\"\n)\n```\n\n##### Crypto Orders\n\n```python\n# Crypto market order\nresponse = await client.place_crypto_market_order(\n symbol=\"BTC-USD\",\n quantity=0.1,\n side=\"buy\",\n broker=\"coinbase\",\n account_number=\"123456789\"\n)\n\n# Crypto limit order\nresponse = await client.place_crypto_limit_order(\n symbol=\"BTC-USD\",\n quantity=0.1,\n side=\"buy\",\n price=50000.00,\n time_in_force=\"gtc\",\n broker=\"coinbase\",\n account_number=\"123456789\"\n)\n```\n\n##### Options Orders\n\n```python\n# Options market order\nresponse = await client.place_options_market_order(\n symbol=\"AAPL240315C00150000\",\n quantity=1,\n side=\"buy\",\n broker=\"tasty_trade\",\n account_number=\"123456789\"\n)\n\n# Options limit order\nresponse = await client.place_options_limit_order(\n symbol=\"AAPL240315C00150000\",\n quantity=1,\n side=\"buy\",\n price=5.00,\n time_in_force=\"gtc\",\n broker=\"tasty_trade\",\n account_number=\"123456789\"\n)\n```\n\n##### Futures Orders\n\n```python\n# Futures market order\nresponse = await client.place_futures_market_order(\n symbol=\"ES\",\n quantity=1,\n side=\"buy\",\n broker=\"ninja_trader\",\n account_number=\"123456789\"\n)\n\n# Futures limit order\nresponse = await client.place_futures_limit_order(\n symbol=\"ES\",\n quantity=1,\n side=\"buy\",\n price=4500.00,\n time_in_force=\"gtc\",\n broker=\"ninja_trader\",\n account_number=\"123456789\"\n)\n```\n\n#### Order Management\n\n```python\n# Cancel an order\nresponse = await client.cancel_order(\n order_id=\"order-123\",\n broker=\"robinhood\",\n connection_id=\"connection-456\"\n)\n\n# Modify an order\nresponse = await client.modify_order(\n order_id=\"order-123\",\n modifications={\"price\": 155.00, \"quantity\": 5},\n broker=\"robinhood\",\n connection_id=\"connection-456\"\n)\n```\n\n### Broker Management\n\n```python\n# Disconnect a company from broker\nresponse = await client.disconnect_company(\"connection-123\")\n```\n\n### Error Handling\n\n```python\nfrom finatic_server.utils.errors import AuthenticationError, ApiError, ValidationError\n\ntry:\n orders = await client.get_orders()\nexcept AuthenticationError as e:\n print(f\"Authentication failed: {e}\")\nexcept ValidationError as e:\n print(f\"Invalid request: {e}\")\nexcept ApiError as e:\n print(f\"API error: {e}\")\n```\n\n### Context Manager Usage\n\n```python\nasync with FinaticServerClient(\"your-api-key\") as client:\n await client.start_session()\n brokers = await client.get_broker_list()\n # Client automatically closes when exiting context\n```\n\n### Cleanup\n\n```python\n# Close the client and cleanup resources\nawait client.close()\n```\n\n## Advanced Usage\n\n### Custom Filters\n\n```python\nfrom finatic_server.types import BrokerDataOptions, OrdersFilter\n\n# Get orders with custom filters\norders = await client.get_orders(\n page=1,\n per_page=50,\n options=BrokerDataOptions(\n broker_name=\"robinhood\",\n account_id=\"123456789\"\n ),\n filters=OrdersFilter(\n status=\"filled\",\n symbol=\"AAPL\"\n )\n)\n```\n\n### Pagination Navigation\n\n```python\n# Get paginated results with navigation\norders_page = await client.get_orders(page=1, per_page=100)\n\n# Navigate through pages\nif orders_page.has_next:\n next_page = await orders_page.next_page()\n\nif orders_page.has_previous:\n prev_page = await orders_page.previous_page()\n```\n\n## Type Definitions\n\nThe SDK includes comprehensive type definitions for all data structures:\n\n- `BrokerOrder`: Order information\n- `BrokerPosition`: Position information\n- `BrokerAccount`: Account information\n- `BrokerBalance`: Balance information\n- `BrokerInfo`: Broker information\n- `BrokerConnection`: Connection information\n- `OrderResponse`: Order operation responses\n- `PaginatedResult`: Paginated data responses\n\n## Error Types\n\n- `AuthenticationError`: Authentication failures\n- `ApiError`: API request failures\n- `ValidationError`: Invalid request parameters\n- `ConnectionError`: Network connectivity issues\n\n## Requirements\n\n- Python 3.8+\n- aiohttp\n- pydantic\n\n## License\n\nMIT License\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Python SDK for Finatic Server API",
"version": "0.1.6",
"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": "1a257947b8f85ba30a84b69393ed4e7423c1b28b59ebbdf955fbd9cbe2fef9b1",
"md5": "696c27197faf51c82b4a6995cca33f68",
"sha256": "d1e04c81665bde634695c4ea12a8579bab0ed649b840389281b33c81af381b35"
},
"downloads": -1,
"filename": "finatic_server_python-0.1.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "696c27197faf51c82b4a6995cca33f68",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8.1",
"size": 31134,
"upload_time": "2025-10-26T20:53:04",
"upload_time_iso_8601": "2025-10-26T20:53:04.523474Z",
"url": "https://files.pythonhosted.org/packages/1a/25/7947b8f85ba30a84b69393ed4e7423c1b28b59ebbdf955fbd9cbe2fef9b1/finatic_server_python-0.1.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "b10a9207fa10622db36f6265b83d837184b2940e1462b94aa79c86057252281d",
"md5": "a74a30bcaae333ed6014f7c348170bfd",
"sha256": "e426019afd200b7a7f0b9b5c0e1772ecff41e4e196b3330e13724544e5cbd00b"
},
"downloads": -1,
"filename": "finatic_server_python-0.1.6.tar.gz",
"has_sig": false,
"md5_digest": "a74a30bcaae333ed6014f7c348170bfd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8.1",
"size": 30417,
"upload_time": "2025-10-26T20:53:05",
"upload_time_iso_8601": "2025-10-26T20:53:05.814616Z",
"url": "https://files.pythonhosted.org/packages/b1/0a/9207fa10622db36f6265b83d837184b2940e1462b94aa79c86057252281d/finatic_server_python-0.1.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-26 20:53:05",
"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
