Sandbox Environment

Overview

The CDP Payments API sandbox environment provides a safe, isolated testing space where you can develop and test your payment integrations without affecting production data or processing real transactions. The sandbox mirrors production functionality while using test data and simulated payment flows.

All API endpoints, authentication methods, and response formats in sandbox are identical to production, making it easy to transition your code when ready.

Key Differences: Sandbox vs Production

Feature	Sandbox	Production
API Endpoint	`sandbox.cdp.coinbase.com`	`api.cdp.coinbase.com`
API Keys	Sandbox-specific credentials	Production credentials
Transactions	Simulated (no real value)	Real payment processing
Test Accounts	Unlimited test accounts	Real user accounts
Rate Limits	Same as production	Standard production limits
Data Persistence	Permanent	Permanent
Webhooks	Supported	Supported

Getting Started

1. Create Sandbox API Credentials

To access the sandbox environment, you’ll need to create sandbox-specific API credentials:

Access CDP Portal

Navigate to the CDP Portal

Select Your Project

Choose the project you want to create sandbox credentials for

Create Sandbox API Key

Go to API Keys section
Click Create API Key
Select Sandbox as the environment
Choose appropriate permissions (Accounts, Transfers, Payment Methods, etc.)
Save your API key name and private key securely

Configure Your Application

Update your application to use the sandbox endpoint and credentials

Important:

Never commit API keys to version control. Store them securely in environment variables or a secrets manager.
Real personal data must not be used in the sandbox environment.

2. Testing Workflows

Use following Postman Collection and Environment with the key created in previous step to test CDP Sandbox.

Best Practices

Isolate Sandbox Configuration

Keep sandbox configuration completely separate from production:

// config.ts
const config = {
  sandbox: {
    apiUrl: 'https://sandbox.cdp.coinbase.com',
    apiKey: process.env.CDP_SANDBOX_API_KEY,
  },
  production: {
    apiUrl: 'https://api.cdp.coinbase.com',
    apiKey: process.env.CDP_PRODUCTION_API_KEY,
  }
};

export const getConfig = () => {
  return process.env.NODE_ENV === 'production' 
    ? config.production 
    : config.sandbox;
};

Test Error Handling

Use sandbox to thoroughly test error scenarios:

Invalid authentication
Malformed requests
Rate limiting
Network timeouts
Insufficient funds
Invalid account details

Automate Integration Tests

Create automated test suites that run against sandbox:

// tests/integration/payments.test.ts
describe('Payments API Integration', () => {
  beforeAll(() => {
    // Set up sandbox client
  });
  
  test('should create account', async () => {
    const account = await createAccount({
      name: 'Test Account',
      currency: 'USD'
    });
    
    expect(account.id).toBeDefined();
    expect(account.currency).toBe('USD');
  });
  
  test('should process transfer', async () => {
    const transfer = await createTransfer({
      amount: '100.00',
      currency: 'USD'
    });
    
    expect(transfer.status).toBe('pending');
  });
});

Monitor API Usage

Track your API usage patterns in sandbox to understand production requirements:

Request volumes
Response times
Error rates
Rate limit consumption

Test data for transfers

When testing email-based transfers in the sandbox environment, only specific whitelisted email addresses will return successful validation responses. This approach prevents privacy concerns while providing predictable test behavior.

Whitelisted email addresses

The following email addresses are whitelisted for sandbox testing and will return a 2xx success response when used as transfer targets:

Test Email	Description
`testuser1@domain.com`	Returns successful validation
`testuser2@domain.com`	Returns successful validation

A request body that tests email validation might look like the following:

{
  "source": {
    "accountId": "{{accountId}}",
    "asset": "USD"
  },
  "target": {
    "email": "testuser1@domain.com",
    "asset": "USD"
  },
  "amount": "10",
  "validateOnly": true
}

Use validateOnly: true to test email validation without initiating a transfer.

Non-whitelisted emails

Any email address not in the whitelist will return a 4xx validation error indicating the user was not found.

In production, transfers validate against actual Coinbase user accounts. The sandbox whitelist is intentionally limited to prevent privacy concerns around validating real email addresses.

Reserved onchain addresses for simulated outcomes

When testing onchain transfers in the sandbox environment, you can use reserved onchain addresses to simulate deterministic success or failure outcomes. Each address returns a predictable response based on the address used.

These reserved addresses are for testing purposes in the sandbox environment. In production, they are valid onchain addresses and any funds sent to them will be lost.

Reserved Address	Simulated Outcome
`0x1111111111111111111111111111111111111111`	Success
`0x2222222222222222222222222222222222222222`	Transfer invalid target
`0x3333333333333333333333333333333333333333`	Invalid address
`0x4444444444444444444444444444444444444444`	Unsupported network

Sample request and response payloads

Success
Transfer invalid target
Invalid address
Unsupported network

Request payload:

{
  "source": {
    "accountId": "{{accountId}}",
    "asset": "USDC"
  },
  "target": {
    "network": "base",
    "address": "0x1111111111111111111111111111111111111111",
    "asset": "USDC"
  },
  "amount": "10.00"
}

Expected response: HTTP 2xx with a normal transfer response.

Request payload:

{
  "source": {
    "accountId": "{{accountId}}",
    "asset": "USDC"
  },
  "target": {
    "network": "base",
    "address": "0x2222222222222222222222222222222222222222",
    "asset": "USDC"
  },
  "amount": "10.00"
}

Expected response: HTTP 400:

{
  "errorType": "invalid_request",
  "errorMessage": "'target' is invalid: must match one of [Account, Payment Method, Onchain Address, Email Instrument]. Account requires 'accountId'; Payment Method requires 'paymentMethodId'; Onchain Address requires 'network'; Email Instrument requires 'email'"
}

Request payload:

{
  "source": {
    "accountId": "{{accountId}}",
    "asset": "USDC"
  },
  "target": {
    "network": "base",
    "address": "0x3333333333333333333333333333333333333333",
    "asset": "USDC"
  },
  "amount": "10.00"
}

Expected response: HTTP 400:

{
  "errorType": "invalid_request",
  "errorMessage": "Invalid onchain address for network base."
}

Request payload:

{
  "source": {
    "accountId": "{{accountId}}",
    "asset": "USDC"
  },
  "target": {
    "network": "base",
    "address": "0x4444444444444444444444444444444444444444",
    "asset": "USDC"
  },
  "amount": "10.00"
}

Expected response: HTTP 400:

{
  "errorType": "invalid_request",
  "errorMessage": "base is not a supported network."
}

Limitations & Considerations

Be aware of these sandbox limitations when testing:

Performance: Response times may vary from production
Third-Party Services: Some third-party integrations use mocked responses
Rate Limits: Same rate limits as production apply to prevent abuse
Compliance Checks: Simplified compliance flows (no real KYC/AML)

Transitioning to Production

When you’re ready to move from sandbox to production:

Complete Integration Testing

Ensure all features work correctly in sandbox with comprehensive test coverage

Review Security Practices

Ensure API keys are stored securely
Review access control and permissions
Implement proper error handling

Create Production API Keys

Generate production credentials in the CDP Portal with appropriate permissions

Update Configuration

Switch from sandbox to production endpoints:

- baseURL: 'https://sandbox.cdp.coinbase.com'
+ baseURL: 'https://api.cdp.coinbase.com'

Start with Small Transactions

Begin with small test transactions to verify everything works as expected

Monitor Closely

Set up monitoring and alerting for:

Failed transactions
API errors
Unusual activity

Have a Rollback Plan

Be prepared to quickly revert to previous code if issues arise

Need Help?

If you encounter issues with the sandbox environment, see the Troubleshooting page for common issues and solutions.

CDP PAYMENTS API

REST API

Overview

Key Differences: Sandbox vs Production

Getting Started

1. Create Sandbox API Credentials

2. Testing Workflows

Best Practices

Test data for transfers

Whitelisted email addresses

Non-whitelisted emails

Reserved onchain addresses for simulated outcomes

Sample request and response payloads

Limitations & Considerations

Transitioning to Production

Need Help?

CDP PAYMENTS API

REST API

​Overview

​Key Differences: Sandbox vs Production

​Getting Started

​1. Create Sandbox API Credentials

​2. Testing Workflows

​Best Practices

​Test data for transfers

​Whitelisted email addresses

​Non-whitelisted emails

​Reserved onchain addresses for simulated outcomes

​Sample request and response payloads

​Limitations & Considerations

​Transitioning to Production

​Need Help?

Overview

Key Differences: Sandbox vs Production

Getting Started

1. Create Sandbox API Credentials

2. Testing Workflows

Best Practices

Test data for transfers

Whitelisted email addresses

Non-whitelisted emails

Reserved onchain addresses for simulated outcomes

Sample request and response payloads

Limitations & Considerations

Transitioning to Production

Need Help?