Introducing the Upgraded Sandbox

See the new sandbox feature list for the release overview. This page provides the transition plan and integration guidance.

The upcoming sandbox release introduces streamlined onboarding, test-account funding, and on-chain payments on Base Sepolia. Production is unaffected. Sandbox balances and transfers use test assets with no monetary value.

Use the sandbox dashboard and https://orchestration.seismictest.net/api/v0 with sandbox credentials. The shared API reference also describes production capabilities; the staged network and asset restrictions on this page take precedence for sandbox.

Already using sandbox? Read Backward compatibility before the cutover: existing virtual crypto wallets need new addresses, while eligible account balances are preserved against the cutover snapshot.

Phase 1: Base Sepolia

What's new

• Onboarding: individual KYC and business KYB retain the profile, document, and explicit submit workflow. Eligible submissions are approved immediately by default and generate status webhooks. Creating a draft does not submit it. Customer sandbox_auto_approve_kyc: false selects randomized background progression instead; validation and eligibility checks still apply.
• Accounts: USD virtual accounts and external bank accounts, plus Base Sepolia virtual wallets and registered external crypto accounts. Read returned account requirements and supported rails rather than assuming every production route is available.
• Balances: new eligible crypto accounts receive test USDC and ETH gas funding, subject to limits and reserve availability. Sandbox fiat virtual accounts can receive simulated USD deposits through the dashboard or API. External bank accounts are destinations, not stored fiat balances.
• Payments: quotes, acceptance, funding, settlement, cancellation, balance refresh, deposit history, and signed status webhooks. Supported payments require a crypto source or destination; fiat-to-fiat is not supported. Quotes itemize a simulated processing fee under fees, and the quoted destination amount is already net of it. Sandbox exchange rates and fee amounts are test values, not production pricing.
• Testnet transfers: crypto funding must arrive on Base Sepolia before an order advances. A wallet's balance alone does not fund an order. For an external source, sign and send the requested token amount to the returned funding address. Follow the order's instructions and expiry, then verify terminal status.
• Recovery: overpayment refunds and late-deposit recovery are tracked separately from settlement. Verify the refund transaction; a completed payment does not by itself prove a refund completed.

Phase 1 supports Base Sepolia (chain ID 84532), standard ERC20 test USDC, and ETH for gas. Ethereum Sepolia is not Base Sepolia. Mainnet assets, Polygon, Solana, USDT, and Seismic transactions are not enabled in this phase. Use the token contract returned by the sandbox API, not production USDC or another faucet's token. ERC20 balance reads require no decryption key.

The payment flow

Request and accept a quote before funding either payment path. The diagram shows the successful flow for an eligible customer; validation and funding checks still apply. Account funding and order funding are separate steps.

API calls to get started

Use https://orchestration.seismictest.net/api as your base URL and send your sandbox key in the Api-Key header. Except for simulated fiat deposits, these are the existing API routes with sandbox-specific behavior, not new contracts.

Discover supported routes

• GET /v0/rails — discover available payment rails.
• GET /v0/currencies — discover supported currencies.
• GET /v0/eligible-rails — check eligibility using the parameters in the reference.

Onboard a customer

• POST /v0/customers — create a draft customer; set sandbox_auto_approve_kyc to false to test delayed approval.
• PUT /v0/customers/{id}/kyc/profile — save the completed individual or business profile.
• POST /v0/customers/{id}/kyc/submit — submit explicitly; eligible customers are approved immediately by default.
• GET /v0/customers/{id}/kyc/state — read the current verification state.

Attach the required synthetic documents before submitting. See the onboarding guide for document-upload and profile examples.

Create accounts

• POST /v0/customers/{id}/accounts/fiat/virtual — request a USD virtual account.
• POST /v0/customers/{id}/accounts/fiat/external — register an external bank account.
• POST /v0/customers/{id}/accounts/crypto/virtual — request a Base Sepolia virtual wallet.
• POST /v0/customers/{id}/accounts/crypto/external — register a Base Sepolia address whose signing key you control.
• GET /v0/customers/{id}/accounts/requests/{request_id} — follow asynchronous account creation.

Use the request bodies in the account reference. Preserve the same Idempotency-Key on retries. Eligible new crypto accounts receive test USDC and ETH gas automatically, subject to funding limits; verify the resulting balances rather than assuming account creation guarantees funding.

New: simulated fiat deposits

• POST /v0/sandbox/accounts/{id}/deposits — add a simulated deposit to an active sandbox virtual fiat account.

curl --fail-with-body \
  "https://orchestration.seismictest.net/api/v0/sandbox/accounts/$ACCOUNT_ID/deposits" \
  -H "Api-Key: $SANDBOX_API_KEY" \
  -H "Idempotency-Key: sandbox-usd-deposit-001" \
  -H "Content-Type: application/json" \
  --data '{
    "amount": "100.00",
    "currency": "USD"
  }'

Amounts are decimal strings in currency units, not token base units. Each deposit must be positive, at most 1,000,000, and have no more than two decimal places. The currency must match the account. Reuse the key and identical body when retrying; a different deposit needs a new key. Reusing a key with a different body returns 409. This endpoint is unavailable in production.

The response includes account_id, deposit_id, and payment_advanced. A true payment_advanced means a waiting payment matched, not that settlement completed. Deposits remain as balance unless matched to a payment or swept by configured automatic liquidation. External bank accounts cannot be funded through this endpoint.

Create and follow a payment

• POST /v0/quotes — request a quote for a supported crypto-to-fiat or fiat-to-crypto pair.
• POST /v0/quotes/{id}/accept — accept the quote and follow the returned funding instructions.
• GET /v0/orders/{id} — reconcile the order's current state with received webhooks.
• GET /v0/accounts/{id}/balance — read the recorded account balance.
• POST /v0/accounts/{id}/balance/refresh — request a fresh balance.
• GET /v0/deposits — inspect deposit history within your organization.

See quote acceptance for request examples and webhook verification for signature validation. For external crypto sources, send the specified test USDC on Base Sepolia to the order's funding address using your wallet. Do not use the simulated fiat-deposit endpoint to fund a crypto source.

From draft to approved

Create an individual or business customer, complete its profile, attach synthetic test documents, and submit explicitly. Saving a profile or uploading a document does not start verification: the customer stays draft until submission.

For eligible sandbox submissions, automatic approval is enabled by default. Approval happens on submit, and the corresponding status webhook is queued for delivery. You can move directly from onboarding into account creation without waiting for a manual review. Webhook delivery is asynchronous even when the approval itself is immediate; read the current state when you need confirmation.

To exercise a pending-verification experience, create the customer with sandbox_auto_approve_kyc set to false. This applies to individual KYC and business-customer KYB despite the field's name. After submission, status changes progress in the background with randomized timing and corresponding webhooks. Do not depend on a fixed delay or assume submission means approval. This customer setting is not an organization-wide review control.

Both modes still validate profiles, documents, and eligibility. Automatic approval is not a way to bypass required information or restricted jurisdictions. Use the returned validation errors to correct the saved profile before retrying. Follow the submission reference when resubmitting an already-approved customer; a normal repeat submit does not force re-review.

Funding and following a payment

You can set up accounts, request and accept a quote, follow the payment, inspect deposits, and refresh balances through the dashboard as well as the API. Nonterminal payment details refresh automatically, so an open payment page can show progress without a manual reload. Terminal states stop periodic refresh; check the latest API state when investigating a subsequent recovery transaction.

For fiat-to-crypto, select an eligible fiat source and crypto destination, then follow the accepted order's funding instructions. The sandbox deposit action adds a simulated deposit to an eligible fiat virtual account; it does not create a real bank transfer. Confirm that the intended order recognizes the deposit, then verify completion and the destination's on-chain receipt. A displayed fiat balance is not evidence that a particular order has been funded.

For crypto-to-fiat, use the returned network, token, amount, and funding address. With an external wallet, the address owner must sign the transfer. Merely registering the address does not authorize outgoing transactions. With a virtual wallet, follow the accepted order's account-specific flow and confirm the debit and on-chain transaction rather than sending a duplicate manual transfer. The fiat destination represents simulated settlement, not a real bank payout.

New-account gas funding reduces manual setup but is bounded by funding limits and available reserves. It is not an unlimited faucet or a guarantee that every future transaction has enough gas. Keep gas and payment-token balances separate, and confirm the actual transaction receipt when diagnosing a payment.

What carries over to production

The sandbox exercises the same public API contracts and integration patterns: authentication, profile validation, account requirements, quote acceptance, order states, balance reads, and signed webhook handling. Use the normal client and response schemas, preserve idempotency keys on retries, and reconcile events with current API state. This lets you test the application flow rather than maintaining a separate set of fabricated responses.

Parity does not mean identical operating conditions. Production has real review and verification requirements, different supported networks and routes, real funding, and settlement timing that cannot be predicted from sandbox simulations. Sandbox automatic approval, simulated fiat deposits, and test-asset funding are not production capabilities. Sandbox quotes and successful test payments do not guarantee production pricing, eligibility, liquidity, or settlement time.

Keep environment-specific credentials, account IDs, token addresses, and webhook signing secrets separate. Read the supported catalog and requirements in each environment; do not copy a sandbox address or assume a Base-only sandbox catalog describes production. Continue testing failures, expired quotes, insufficient funds, and duplicate or delayed webhooks, not just the successful path.

Backward compatibility

The transition is being prepared around your existing sandbox data, not a reset to empty customers and accounts. The migration plan covers verification status, customer identity, account details, and opening test balances. The checks below must complete before migrated accounts are made available; this announcement does not mean your accounts have already been migrated.

Things to keep in mind

• Base Sepolia only at launch (chain ID 84532). Seismic transactions and other networks are not enabled in Phase 1.
• ERC20 test USDC is the only supported crypto payment asset. ETH is for gas. Use the token contract returned by the sandbox API, not mainnet USDC, USDT, or a token from another faucet. Fiat accounts and simulated payouts use USD.
• Existing virtual crypto wallets in scope will migrate to new addresses. Their replacement wallets will have the same verified USDC balances captured at cutover, with separate ETH gas funding. Update stored account references and addresses before sending funds or creating new payments.
• Eligible external crypto accounts keep their addresses and receive the exact snapshot-equivalent test USDC balance. Funding tops up to that balance, accounting for target-token USDC already present; it is not a flat allowance or an additional copy of the full balance. ETH gas is funded separately.
• Eligible fiat virtual accounts retain their IDs, banking details, and exact snapshot USD balances. External bank accounts retain beneficiary details but do not acquire a simulated bank balance.
• Approved customers do not need to repeat onboarding solely for this release. Existing verification restrictions and outstanding information requests remain subject to reconciliation, not blanket approval.
• Do not fund retired wallet addresses. They must not be assumed to forward deposits. Unsupported networks, unresolved balances, and incomplete wallet replacements require confirmation before those accounts can be used.

Before and after the cutover

These examples illustrate the planned result for eligible, verified accounts; they are not fixed funding amounts.

Customers and verification

Existing customer identities, saved profiles, uploaded documents, and historical verification records are retained. Eligible approved individual KYC and business KYB decisions are carried over without requiring a new customer or a repeat submission solely because of the release. Organization verification and linked business-person verification are checked as part of the same reconciliation.

Migration is not blanket approval. Draft, pending, rejected, paused, and action-required states are not silently promoted to approved. Outstanding information requests and conflicting decisions require reconciliation; the automatic-approval setting for new submissions does not override those checks. Account eligibility is reconciled with the retained customer identity and verification state before account migration proceeds.

Fiat virtual accounts

Eligible existing USD virtual accounts retain their account IDs, customer association, and banking details. Their opening simulated USD balance is imported from a verified cutover snapshot, rather than replaced with a default allowance. For example, a verified USD 1,250.50 balance becomes an opening simulated balance of USD 1,250.50.

The opening balance is a migration adjustment, not a new incoming payment. Do not expect a fresh deposit webhook for the imported balance or replay old deposit events to recreate it. Check the account balance after migration; subsequent simulated deposits follow the normal sandbox funding flow.

External bank accounts

Eligible external bank accounts retain their account IDs, customer associations, and beneficiary details. They remain payment destinations: no stored USD balance is invented or credited to an external bank account during migration. Its bank balance is not represented by the sandbox virtual-account balance API.

External crypto accounts

Eligible Base Sepolia external accounts retain their registered addresses and customer associations. You continue to control the signing keys; registration or migration does not grant permission to sign outgoing transfers on your behalf.

The verified snapshot determines the target balance of the release's ERC20 test USDC. Funding accounts for any balance already present in that same target token: if the snapshot target is 1,250 USDC and the address already holds 250 of the target test USDC, the migration adds 1,000, not another 1,250. If the target balance exceeds the snapshot or changes unexpectedly, it requires reconciliation instead of an automatic debit or blind repeat credit. ETH gas funding is checked separately from USDC funding.

This is test-balance reconciliation, not a bridge or redemption of real assets. An address on an unsupported chain, an unsupported asset, or an unverified balance requires separate treatment; sharing the same EVM address does not by itself make an account eligible for Phase 1.

Virtual crypto wallet migration

Some older virtual wallets cannot be reused because their signing keys are not available to the new sandbox. Crediting such an address would preserve a displayed balance without making it spendable.

Affected existing virtual crypto accounts will be replaced with new wallet addresses on Base Sepolia, preserving their verified cutover USDC balances. Each replacement requires an explicit link to the previous account and separate ETH gas funding. Replacement-wallet integration and verification remain release prerequisites; these wallets must not be treated as ready merely because other accounts have migrated.

Keep the previous account reference for historical reconciliation. Wait for confirmed replacement details, then update saved account IDs and deposit addresses before creating new payments. Do not send deposits to retired addresses or assume that they automatically forward to the replacement wallet.

Cutover checks and partner actions

Before capture, in-flight payments, deposits, refunds, and liquidation obligations must be resolved and account activity paused for a consistent snapshot. The migration checks account ownership, customer association, currency, chain, token, and source and destination balances. Unverifiable entries block completion rather than being silently omitted or reset to zero.

Migration steps are recorded so retries can reconcile completed work instead of issuing duplicate credits. On-chain funding receipts and resulting balances are checked separately from database updates. A database restore alone cannot undo an on-chain transfer.

Before resuming activity after the announced cutover:

1. Retrieve customer verification states and account details again; do not rebuild already-retained customers or resubmit approved profiles just to trigger migration.
2. Compare fiat and crypto balances with the confirmed snapshot, and verify ETH gas separately. Report discrepancies before making new payments.
3. Replace cached IDs and addresses only for accounts identified as replacements; use the returned network and token contract, not a hardcoded production asset.
4. Confirm any excluded or unresolved accounts have an agreed treatment. Do not assume every legacy network or asset is supported by the Base-only release.
5. Exercise a small payment in each supported direction and verify the current order state, signed webhooks, and relevant on-chain receipts.

Phase 2: Seismic testnet with ERC20 USDC

After a separate announcement, Seismic testnet will be enabled with standard ERC20 test USDC as the payment asset and sUSDC as the gas token. Base support will not be withdrawn without notice. Read chain availability from the API; Phase 1 does not activate this phase.

ERC20 token reads remain ordinary reads. Integrations must accommodate the Seismic network, its transaction tooling, and sUSDC gas funding. Chain-specific configuration and examples will be published before activation.

Phase 3: SRC20 transition

A later, separately announced phase introduces SRC20 payment assets on Seismic. SRC20 is Seismic's shielded equivalent of the ERC20 standard, with balances, transfer amounts, and allowances hidden from external observers. Authorized users can access their balances through signed reads.

Partners will receive documentation, sample code, and an integration window before activation. SRC20 balance access requires signed reads and the appropriate viewing/decryption flow; it is not interchangeable with an unsigned ERC20 balanceOf call. Do not change current integrations to SRC20 yet.

Before activation

1. Keep sandbox credentials and webhook endpoints separate from production.
2. Read supported rails, currencies, contract addresses, and account details from the API. Refresh saved details after migration.
3. Keep signing keys private. Use only synthetic documents and test funds.
4. Verify webhook signatures with your endpoint's signing secret. Handle retries idempotently and reconcile delayed or out-of-order events using API reads.
5. Confirm migration results and exercise crypto-to-fiat and fiat-to-crypto with small test amounts before larger scenarios. Funding limits still apply.

See account creation, quotes, acceptance, and webhook verification for the shared API workflows.