Sandbox and testing

OMS runs in two isolated environments: sandbox and production. Sandbox is a full copy of the API for building and testing against, with no real money and no mainnet settlement. You select an environment by its base URL and the credentials you send. The request and response shapes are identical, so code you build against sandbox runs unchanged in production.

​

Environments

Credentials are scoped to one environment, and the key prefix tells you which. A sandbox key never authenticates against production, and the reverse holds too. Request keys for both from the OMS Dashboard. See Get started for the full authentication flow. Two things to know before you start:

• Customer onboarding runs the same checks as production. Sandbox applies your project’s verification rules to every customer, so a request that would fail in production fails in sandbox too. Use synthetic customer data that matches production formats.
• Blockchain activity settles on testnets. Every onchain transaction executes on the equivalent testnet rather than mainnet, described below.

​

Synthetic customer data

Sandbox customers do not need to be real people, but their data must be well formed, because sandbox validates it the way production does:

• Send every field your project requires. On a project that verifies individuals for custodial wallets, that is firstName, lastName, email, birthDate (YYYY-MM-DD), phone (US E.164, +1 and 10 digits), an identifyingInformation entry of { "type": "ssn", "issuingCountry": "US", "number": "..." }, and a US residentialAddress with line1, city, a two-letter state, zipCode, and country: "US".
• Use an address in a supported state. On those projects, New York, Texas, and Vermont addresses are not supported.
• Do not put “test” in names or email addresses. Fraud screening rejects them.
• Invent a fresh identity for each customer instead of reusing one example payload.

A rejected request returns error code 2001 (invalid argument) with the specific reason in cause. Every response carries a Request-Id header; include it when you contact support. Creation can also return 202 while onboarding finishes in the background. See Customer onboarding for the full flow.

​

Networks map to testnets

In sandbox, keep using the standard network enum values in your requests. You do not change the network field between environments. Under the hood, OMS routes every blockchain transaction to that network’s testnet. A wallet you create with "network": "polygon" in sandbox holds funds on Polygon Amoy. Your code still sends and reads polygon. The mapping is automatic and applies everywhere a network appears: wallet provisioning, quotes, transactions, deposit addresses, and virtual accounts. Because these are testnet addresses, a sandbox wallet’s address resolves on the testnet’s block explorer, not on the mainnet explorer. Sandbox has no simulation endpoint for inbound onchain activity: to fund a wallet or deposit address, send testnet assets to its address.

​

Simulating inbound events

Many OMS flows complete only when money arrives from outside the API: cash deposited at a retail location or a bank transfer landing in a virtual account. Sandbox has no real counterparty to send those funds, so OMS exposes simulation endpoints that trigger the inbound leg on demand. Each simulation drives the same downstream behavior as the real event. It auto-creates the transaction, advances the transaction lifecycle, and fires the same webhook events. That lets you test reconciliation and webhook handling end to end without waiting on an external deposit.

​

What’s next