Finatic

Sandbox Mode

Sandbox mode allows you to test and develop your Finatic integration using mock data without connecting to real broker accounts. This is perfect for development, testing, and demos.

🧪 What is Sandbox Mode?

Sandbox mode provides a safe testing environment with realistic mock data. All API calls work exactly the same as in live mode, but use test data instead of real broker connections. This allows you to:

  • Test your integration without risk to real accounts
  • Develop and debug without waiting for real market data
  • Create demos and tutorials with consistent data
  • Test edge cases and error scenarios safely

Getting Sandbox API Keys

Sandbox mode uses a separate API key from your live/production key. You can obtain your sandbox API key from your Finatic dashboard.

⚠️ Important

Sandbox API keys are separate from live API keys. Make sure to use FINATIC_API_KEY_SANDBOX for sandbox mode and FINATIC_API_KEY_LIVE for production.

Using Sandbox Mode with Client SDK

The Client SDK works identically in sandbox mode. The only difference is using your sandbox API key when initializing the session.

Backend Setup

Use your sandbox API key when calling the session initialization endpoint:

Backend Session Initialization (Sandbox)

Frontend Usage

The frontend code remains exactly the same. The SDK automatically uses sandbox data when initialized with a sandbox token:

Client SDK Usage (Sandbox)

Using Sandbox Mode with Server SDK

The Server SDK also works identically in sandbox mode. Simply use your sandbox API key when initializing the client.

Server SDK Usage (Sandbox)

from finatic_server import FinaticServerClient

# Initialize with sandbox API key
client = FinaticServerClient("your-sandbox-api-key")

# Start a session - works the same as live mode
await client.start_session()

# Get portal URL - will use sandbox environment
portal_url = await client.get_portal_url()

# All methods work identically
user_id = await client.get_user_id()
orders = await client.get_orders()
positions = await client.get_positions()

# All data returned is mock/sandbox data

Environment Variables

We recommend using environment variables to manage your API keys and easily switch between sandbox and live modes:

Environment Variables Configuration

Sandbox Data

Sandbox mode provides realistic mock data including:

  • Mock Broker Connections: Simulated broker accounts with realistic data
  • Mock Orders: Sample order data with various statuses and types
  • Mock Positions: Simulated position data with realistic quantities and prices
  • Mock Balances: Sample account balances
  • Mock Order Events: Simulated order lifecycle events

✅ Benefits of Sandbox Mode

  • No risk to real trading accounts or capital
  • Consistent, predictable test data
  • Fast development and testing cycles
  • No rate limits or API costs for testing
  • Perfect for CI/CD pipelines and automated testing

Switching Between Sandbox and Live

To switch between sandbox and live modes, simply use the appropriate API key:

Switching Between Modes

import os

# Determine which mode to use based on environment
is_sandbox = os.getenv('NODE_ENV') == 'development' or os.getenv('USE_SANDBOX') == 'true'

# Select the appropriate API key
api_key = os.getenv('FINATIC_API_KEY_SANDBOX') if is_sandbox else os.getenv('FINATIC_API_KEY_LIVE')

# Initialize client with selected API key
client = FinaticServerClient(api_key)

Best Practices

1. Use Environment Variables

Never hardcode API keys. Always use environment variables to manage sandbox and live keys separately.

2. Test in Sandbox First

Always develop and test your integration in sandbox mode before switching to live mode.

3. Keep Keys Separate

Never mix sandbox and live API keys. Use clear naming conventions like FINATIC_API_KEY_SANDBOX and FINATIC_API_KEY_LIVE.

4. Use Feature Flags

Implement feature flags or environment-based configuration to easily switch between modes without code changes.

Next Steps

Client SDK Guide

Learn how to integrate the Finatic Client SDK into your application.

Server SDK Guide

Learn how to use the Finatic Server SDK for backend integrations.

Need Help?

If you have questions about sandbox mode or need assistance with your integration, please contact our support team at support@finatic.dev