Skip to content
Finatic
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. Sandbox mode uses Finatic-generated synthetic data. Broker paper or simulated accounts still use the live environment because they call real broker systems.

What is the Sandbox?

The sandbox exposes production-compatible public API shapes backed by 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
  • API Compatibility: Account, grant, session, data, trading, and webhook test flows use the same API shapes
  • 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. Sign in to the Finatic dashboard, open API keys, and copy a sandbox key (fntc_sandbox_)
  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 token method with your sandbox API key to generate one-time tokens for client applications:

Using the Sandbox

Use the same supported public SDK and API shapes with a sandbox API key. Data, provider authentication, sync timing, Background workers, and webhook delivery are synthetic, so sandbox behavior is not operationally identical to live.

Initialize with Sandbox API Key

Important: Use sandbox for Finatic synthetic data only. Broker paper accounts are not Finatic sandbox accounts; call them through live with the broker's paper/sim account selected.

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). Each email is associated with a generated user; that user is linked to the email you provide. The same email always links to the same user. There is no limit on how many distinct users you can create.
  • OTP/Password: Any value will be accepted
  • Broker Credentials: Any credentials will work - no real broker authentication required

To test multiple users on your system, use different emails (e.g., random addresses like user1@test.local, user2@test.local). If you want to return to the same connections and portal interface for a given user, keep track of the email you used for that user; reusing that email will always sign you in as the same generated user.

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
  • No live Background workers: Sandbox sync and webhook behavior is synthetic and should not be treated as production delivery evidence.

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 the public methods and shapes supported 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