Finatic Logo
Sign Up

Sandbox Environment

Learn how to use Finatic's sandbox environment for safe development and testing.

The Finatic sandbox environment provides a safe, isolated testing environment where you can develop and test your integrations without affecting real broker accounts or data. This guide explains how to use the sandbox and what to expect.

What is the Sandbox?

The sandbox is a fully functional replica of the Finatic production environment that uses generated mock data instead of real broker connections. It provides:

  • Safe Testing: Test your integration without connecting to real broker accounts
  • Realistic Data: Generated data that matches the structure and format of production data
  • Full API Compatibility: All production APIs work identically in sandbox mode
  • No Risk: No real trades, real accounts, or real money involved

Getting Your Sandbox API Key

Sandbox API keys are separate from production keys and use the fntc_sandbox_ prefix instead of fntc_live_.

For Server SDK

  1. Navigate to your API Keys page in the Finatic dashboard
  2. Locate the Sandbox API Key section
  3. Generate or copy your sandbox API key (starts with fntc_sandbox_)

For Client SDK

Use the Server SDK's getToken() method with your sandbox API key to generate one-time tokens for client applications:

1// Server-side (Node.js) 2import { FinaticServer } from '@finatic/server-node'; 3 4// Initialize with your SANDBOX API key 5const finatic = new FinaticServer('fntc_sandbox_your_api_key'); 6 7// Get a one-time token for client 8const oneTimeToken = await finatic.getToken(); 9 10// Send this token to your client

Using the Sandbox

Using the sandbox is identical to using production—simply replace your production API key with your sandbox API key. All SDK methods, API calls, and workflows work exactly the same.

Initialize with Sandbox API Key

1// TypeScript (Client) 2import { FinaticConnect } from '@finatic/client'; 3 4// Initialize with a one-time token generated from sandbox API key 5const finatic = await FinaticConnect.init('your-sandbox-one-time-token', 'optional-user-id'); 6 7// All methods work identically to production 8const accounts = await finatic.brokers.getAccounts();

Important: The only difference between sandbox and production is the API key prefix. All code, methods, and workflows remain identical.

Portal Authentication in Sandbox

When using the sandbox portal, you can use any credentials for testing:

  • Email: Any email address (e.g., test@example.com, dev@myapp.com)
  • OTP/Password: Any value will be accepted
  • Broker Credentials: Any credentials will work—no real broker authentication required

This allows you to test the complete authentication flow without needing real broker accounts.

1// Open portal in sandbox mode 2await finatic.openPortal({ 3 onSuccess: (userId) => { 4 console.log('User authenticated:', userId); 5 // Use any email/credentials in the portal 6 }, 7 onError: (error) => { 8 console.error('Portal error:', error); 9 } 10});

Generated Data

The sandbox environment generates realistic mock data that matches production data structures:

Data Characteristics

  • Accounts: Generated account numbers, balances, and metadata
  • Orders: Mock orders with various statuses (filled, pending, cancelled)
  • Positions: Generated positions with realistic quantities and values
  • Balances: Mock account balances and cash positions
  • Instruments: Realistic symbols, tickers, and instrument metadata

Data Consistency

  • Data is generated deterministically based on connection and account IDs
  • The same connection will return consistent data across requests
  • Data relationships (orders → positions, accounts → balances) are maintained

Data Limitations

  • No Real Market Data: Prices and values are generated, not real-time market data
  • No Real Trading: All trading operations are simulated
  • No Real Broker APIs: No actual calls to broker APIs are made

Data Wiping

Important: Sandbox data is periodically wiped to maintain a clean testing environment.

What Gets Wiped

  • All broker connections
  • All accounts, orders, positions, and balances
  • All user sessions and authentication data

When Data is Wiped

  • Data wipes occur occasionally (typically during maintenance windows)
  • You will receive advance notice when possible
  • Plan your testing accordingly—don't rely on sandbox data persisting indefinitely

Best Practices

  • Don't Store Critical Test Data: Use sandbox for integration testing, not long-term data storage
  • Recreate Connections: After a wipe, simply reconnect through the portal to regenerate data
  • Use Version Control: Keep your test scenarios and data setup scripts in version control

Next Steps

Now that you understand the sandbox environment:

  1. Quick Start - Initialize the SDK with your sandbox API key
  2. Connecting Brokers - Connect brokers in sandbox mode (use any credentials)
  3. Getting Data - Retrieve generated mock data
  4. Error Handling - Test error scenarios safely
  5. API Reference - Explore all available methods (work identically in sandbox)

Best Practices

  • Separate Environments: Use sandbox for development/testing, production for live applications
  • Environment Variables: Store sandbox and production keys in separate environment variables
  • Don't Mix Keys: Never use a production key in sandbox or vice versa
  • Test Regularly: Regularly test your integration in sandbox before deploying to production
  • Plan for Wipes: Design your tests to be resilient to data wipes