Set up a sandbox environment

Bridge has a sandbox environment for you to quickly begin testing your integration without having to move real money. To access this sandbox, you must first reach out to support@bridge.xyz to get onboarded with a Developer account within Bridge. Afterwards, you’ll be able to generate sandbox API keys

Step 1: Generate a Sandbox Key

Note that only dashboard admins have access to both sandbox and prod API keys.
Please ask your dashboard admin for access if you don’t have it

Go to https://dashboard.bridge.xyz/ and log in with your email.
Then, ensure the “Sandbox” toggle is turned on (blue).
Then, hit the button to generate a sandbox key.
Sandbox keys should be prefixed with sk-test.

Step 2: Hit an API

You can begin testing in Sandbox by creating a Bridge customer.

Note that the sandbox base url is https://api.sandbox.bridge.xyz

curl --location --request POST 'https://api.sandbox.bridge.xyz/v0/customers' \
--header 'Content-Type: application/json' \
--header 'Api-Key: <API Key>' \
--header 'Idempotency-Key: <generate a uuid>' \
--data-raw '{
  "first_name": "John",
  "last_name": "Doe",
  "email": "johndoe@johndoe.com",
  "address": {
    "street_line_1": "123 Washington St",
    "street_line_2": "Apt 2F",
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "10001",
    "country": "USA"
  },
  "birth_date": "1989-09-09",
  "tax_identification_number": "111-11-1111",
  "phone": "+15555555555",
  "signed_agreement_id": "<generate a uuid>",
  "type": "individual"
}'

We recommend the following steps to get a sense of how to use Bridge:

Create a customer
Call POST /v0/customers/{customer_id}/simulate_kyc_approval to approve them
Fetch that customer and verify kyc_status is approved
Create fake liquidation addresses, transfers and fiat deposit instructions (Note: there is no real money movement in Sandbox)

Differences from production and testing in Sandbox

Sandbox is API-onlyThe Bridge Dashboard lets you generate and manage Sandbox API keys, but it does not provide a UI for viewing or managing Sandbox customers, external accounts, wallets, balances, transfers, virtual accounts, liquidation addresses, drains, or webhook activity.Create, retrieve, and manage Sandbox resources through the Bridge API. Save the IDs returned by API responses and use GET endpoints and webhooks to observe state changes. If you lose a resource ID, use the applicable list endpoint to retrieve it.

Sandbox uses the same API conventions and resource model as production, but replaces real compliance checks, bank activity, and blockchain transactions with simulated behavior. No real funds move in Sandbox. Use Sandbox to develop and validate your integration, including resource creation, supported lifecycle transitions, and webhook handling. Sandbox is not intended for load testing or for validating the behavior, timing, or availability of live banks, blockchain networks, compliance providers, or other external services.

Environment and configuration

Send requests to https://api.sandbox.bridge.xyz/v0 using an API key beginning with sk-test.
Use the Bridge Dashboard only to generate and manage Sandbox API keys. All other Sandbox testing is performed through the API.
Sandbox and production data are isolated. Resources created in one environment are not available in the other.
Sandbox users can be associated with separate Sandbox developer profiles. Configuration, endorsements, and feature access might not automatically match your production developer account.
Configure separate webhook endpoints and use separate idempotency keys for Sandbox and production.

The examples below use these shell variables:

export BRIDGE_SANDBOX_API_KEY="sk-test-..."
export BASE_URL="https://api.sandbox.bridge.xyz/v0"

Replace values such as {customer_id} and {wallet_id} with IDs returned by earlier API calls.

Recommended Sandbox workflow

Generate a Sandbox API key in the Bridge Dashboard.
Create and activate a Sandbox webhook endpoint.
Create a customer through the API.
Simulate KYC or KYB approval.
Create the resources required by your integration, such as external accounts, wallets, virtual accounts, or liquidation addresses.
Call the applicable Sandbox simulation endpoint.
Use retrieval, list, history, and webhook endpoints to verify the resulting state.

Because there is no Dashboard UI for Sandbox resources, your integration or API client should retain the IDs returned at every step.

Configure webhooks before simulating activity

Create a Sandbox webhook endpoint before running simulations so you can test event handling and reconciliation. Include only the event categories used by your integration.

curl --request POST \
  --url "$BASE_URL/webhooks" \
  --header "Api-Key: $BRIDGE_SANDBOX_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $(uuidgen)" \
  --data '{
    "url": "https://example.com/webhooks/bridge-sandbox",
    "event_categories": [
      "customer",
      "liquidation_address.drain",
      "virtual_account.activity",
      "bridge_wallet.activity",
      "transfer"
    ],
    "event_epoch": "webhook_creation"
  }'

Save the returned webhook ID, then activate the endpoint:

curl --request PUT \
  --url "$BASE_URL/webhooks/{webhook_id}" \
  --header "Api-Key: $BRIDGE_SANDBOX_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "status": "active"
  }'

Supported Sandbox simulations can generate webhook events. Event coverage and lifecycle timing can differ from production because Sandbox does not receive events from live providers.

Simulate customer approval

Sandbox does not perform real KYC or KYB verification. Create a customer through the API, then call the Sandbox-only approval endpoint.

1. Create a customer

curl --request POST \
  --url "$BASE_URL/customers" \
  --header "Api-Key: $BRIDGE_SANDBOX_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $(uuidgen)" \
  --data '{
    "type": "individual",
    "first_name": "Jane",
    "last_name": "Sandbox",
    "email": "jane.sandbox@example.com",
    "residential_address": {
      "street_line_1": "123 Test Street",
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94111",
      "country": "USA"
    },
    "nationality": "USA",
    "birth_date": "1980-09-10",
    "signed_agreement_id": "00000000-0000-0000-0000-000000000001",
    "identifying_information": [
      {
        "type": "ssn",
        "number": "111-11-1111",
        "issuing_country": "USA"
      }
    ],
    "phone": "+15555550100"
  }'

Save the id from the response as the customer ID.

2. Simulate KYC or KYB approval

curl --request POST \
  --url "$BASE_URL/customers/{customer_id}/simulate_kyc_approval" \
  --header "Api-Key: $BRIDGE_SANDBOX_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $(uuidgen)"

This endpoint simulates approval, populates required Sandbox entity data when necessary, and approves pending endorsements used by supported Sandbox flows. It does not reproduce document verification, manual review, rejection, requests for information, or other production compliance outcomes. Retrieve the customer to verify its resulting status:

curl --request GET \
  --url "$BASE_URL/customers/{customer_id}" \
  --header "Api-Key: $BRIDGE_SANDBOX_API_KEY"

Simulate a Liquidation Address deposit

First create a Liquidation Address through the standard API and save its id. Then simulate an incoming crypto deposit:

curl --request POST \
  --url "$BASE_URL/customers/{customer_id}/liquidation_addresses/{liquidation_address_id}/simulate_deposit" \
  --header "Api-Key: $BRIDGE_SANDBOX_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $(uuidgen)" \
  --data '{
    "currency": "usdc",
    "amount": "100.00"
  }'

The currency must be compatible with the Liquidation Address. For a successful simulation, the response includes success: true and the created drain_id. Sandbox then advances the simulated deposit and drain through the supported processing flow. Retrieve the resulting drains through the API:

curl --request GET \
  --url "$BASE_URL/customers/{customer_id}/liquidation_addresses/{liquidation_address_id}/drains" \
  --header "Api-Key: $BRIDGE_SANDBOX_API_KEY"

Also listen for liquidation_address.drain webhook events.

Simulate a Virtual Account deposit

First create a Virtual Account through the standard API and save its id. Then simulate an incoming fiat deposit:

curl --request POST \
  --url "$BASE_URL/customers/{customer_id}/virtual_accounts/{virtual_account_id}/simulate_deposit" \
  --header "Api-Key: $BRIDGE_SANDBOX_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $(uuidgen)" \
  --data '{
    "currency": "usd",
    "amount": "250.00"
  }'

The currency must match the Virtual Account’s source currency. Sandbox creates a representative incoming bank event and advances the resulting deposit through the supported processing flow. Retrieve the Virtual Account history through the API:

curl --request GET \
  --url "$BASE_URL/customers/{customer_id}/virtual_accounts/{virtual_account_id}/history" \
  --header "Api-Key: $BRIDGE_SANDBOX_API_KEY"

Also listen for virtual_account.activity and resulting transfer webhook events, as applicable to the configured destination.

Simulate a Bridge Wallet deposit

Create a Bridge Wallet and save its id:

curl --request POST \
  --url "$BASE_URL/customers/{customer_id}/wallets" \
  --header "Api-Key: $BRIDGE_SANDBOX_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $(uuidgen)" \
  --data '{
    "chain": "base"
  }'

Simulate a deposit into the wallet:

curl --request POST \
  --url "$BASE_URL/customers/{customer_id}/wallets/{wallet_id}/simulate_deposit" \
  --header "Api-Key: $BRIDGE_SANDBOX_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $(uuidgen)" \
  --data '{
    "currency": "usdc",
    "amount": "245.67"
  }'

The amount must be positive, and the currency must be supported by the wallet’s chain. The response contains the updated wallet resource. Sandbox does not submit a transaction to a blockchain; it creates and processes a representative deposit internally. Retrieve the wallet or its history to verify the updated balance:

curl --request GET \
  --url "$BASE_URL/customers/{customer_id}/wallets" \
  --header "Api-Key: $BRIDGE_SANDBOX_API_KEY"

curl --request GET \
  --url "$BASE_URL/customers/{customer_id}/wallets/{wallet_id}/history" \
  --header "Api-Key: $BRIDGE_SANDBOX_API_KEY"

Also listen for bridge_wallet.activity webhook events.

Card simulations

Test your card integration using the Stripe Sandbox and Bridge sandbox environment. Cards have additional Sandbox-only endpoints for funding and transaction testing, including simulations for balance top-ups, authorizations, settlements, and incremental authorizations. Card testing has product-specific setup requirements. Follow the Cards Sandbox guide instead of treating the general orchestration examples above as card-testing instructions.

External services and networks

Plaid Link is not currently supported in Bridge Sandbox. Create test external accounts directly through the External Accounts API.
Bridge Wallet and orchestration simulations do not submit transactions to live bank or blockchain networks.
Do not assume that a blockchain testnet is used unless the product-specific documentation explicitly identifies one.
Responses can contain generated account numbers, wallet addresses, transaction identifiers, and other representative data. Do not use Sandbox values in production.
Supported rails and lifecycle behavior can differ by product, route, currency, and enabled feature. Sandbox does not guarantee parity for every production route.

Before going live

Before enabling production traffic, validate with controlled production tests:

Live KYC or KYB onboarding and exception handling.
External-account linking and provider behavior.
The payment rails and currencies used by your integration.
Webhook delivery, retries, ordering, and reconciliation.
Production configuration, endorsements, limits, and feature access.

Introduction

Guides

Set up a sandbox environment

Step 1: Generate a Sandbox Key

Step 2: Hit an API

Differences from production and testing in Sandbox

Environment and configuration

Recommended Sandbox workflow

Configure webhooks before simulating activity

Simulate customer approval

1. Create a customer

2. Simulate KYC or KYB approval

Simulate a Liquidation Address deposit

Simulate a Virtual Account deposit

Simulate a Bridge Wallet deposit

Card simulations

External services and networks

Before going live

​Step 1: Generate a Sandbox Key

​Step 2: Hit an API

​Differences from production and testing in Sandbox

​Environment and configuration

​Recommended Sandbox workflow

​Configure webhooks before simulating activity

​Simulate customer approval

​1. Create a customer

​2. Simulate KYC or KYB approval

​Simulate a Liquidation Address deposit

​Simulate a Virtual Account deposit

​Simulate a Bridge Wallet deposit

​Card simulations

​External services and networks

​Before going live

Step 1: Generate a Sandbox Key

Step 2: Hit an API

Differences from production and testing in Sandbox

Environment and configuration

Recommended Sandbox workflow

Configure webhooks before simulating activity

Simulate customer approval

1. Create a customer

2. Simulate KYC or KYB approval

Simulate a Liquidation Address deposit

Simulate a Virtual Account deposit

Simulate a Bridge Wallet deposit

Card simulations

External services and networks

Before going live