Sandbox Testing Guide

How to use sandbox endpoints for development and testing

Overview

The Cred Protocol sandbox provides mock API endpoints for development and testing. Use the sandbox to build and test your integration without consuming your API quota or waiting for real blockchain queries.

Why Use the Sandbox?

Free Testing

Sandbox requests don’t count against your API quota

Instant Responses

No blockchain queries means instant responses

Consistent Data

Deterministic responses for reliable testing

No Dependencies

Test without relying on blockchain data availability

Sandbox Endpoints

Sandbox Endpoint	Production Equivalent
/api/v2/sandbox/score/address/{address}	/api/v2/score/address/{address}
/api/v2/sandbox/score/batch/	/api/v2/score/batch/
/api/v2/sandbox/report/address/{address}	/api/v2/report/address/{address}

Getting Started

1. Use Sandbox During Development

Simply add /sandbox before the endpoint path:

cURL

# Sandbox (for development)
curl "https://api.credprotocol.com/api/v2/sandbox/score/address/0x123..." \
  -H "Authorization: Bearer YOUR_API_KEY"

# Production (for live data)
curl "https://api.credprotocol.com/api/v2/score/address/0x123..." \
  -H "Authorization: Bearer YOUR_API_KEY"

2. Sandbox Response Format

Sandbox responses use the same format as production:

{
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0Ab17",
  "score": 726,
  "decile": 8,
  "range": "good",
  "model_version": "andromeda_1.0",
  "timestamp": "2024-01-15T10:30:00Z"
}

Sandbox responses are deterministic - the same address always returns the same mock score. This makes testing reliable and reproducible.

Test Scenarios

Testing Different Score Ranges

Use these test addresses to simulate different credit scores:

Address	Mock Score	Range
0x0000000000000000000000000000000000000001	935+	excellent
0x0000000000000000000000000000000000000002	770-858	good
0x0000000000000000000000000000000000000003	655-769	fair
0x0000000000000000000000000000000000000004	300-654	low

Testing Your UI

Use the sandbox to test how your UI handles different scenarios:

// Test different score ranges
const testAddresses = [
  '0x0000000000000000000000000000000000000001', // excellent
  '0x0000000000000000000000000000000000000002', // good
  '0x0000000000000000000000000000000000000003', // fair
  '0x0000000000000000000000000000000000000004', // low
];

for (const address of testAddresses) {
  const score = await getScore(address);
  console.log(`${address}: ${score.score} (${score.range})`);
}

CI/CD Integration

Automated Testing

Use the sandbox in your test suite for consistent, fast tests:

// __tests__/cred-api.test.js
describe('Cred API Integration', () => {
  const API_URL = 'https://api.credprotocol.com';
  const API_KEY = process.env.CRED_API_KEY;

  test('should return credit score for valid address', async () => {
    const response = await fetch(
      `${API_URL}/api/v2/sandbox/score/address/0x742d35Cc6634C0532925a3b844Bc9e7595f0Ab17`,
      { headers: { 'Authorization': `Bearer ${API_KEY}` } }
    );

    const data = await response.json();

    expect(response.status).toBe(200);
    expect(data.score).toBeGreaterThanOrEqual(300);
    expect(data.score).toBeLessThanOrEqual(1000);
    expect(data.decile).toBeGreaterThanOrEqual(1);
    expect(data.decile).toBeLessThanOrEqual(10);
  });

  test('should return valid range', async () => {
    const response = await fetch(
      `${API_URL}/api/v2/sandbox/score/address/0x742d35Cc6634C0532925a3b844Bc9e7595f0Ab17`,
      { headers: { 'Authorization': `Bearer ${API_KEY}` } }
    );

    const data = await response.json();

    expect(['low', 'fair', 'good', 'very_good', 'excellent']).toContain(data.range);
  });
});

GitHub Actions Example

# .github/workflows/test.yml
name: API Integration Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Run tests
        env:
          CRED_API_KEY: ${{ secrets.CRED_API_KEY }}
        run: npm test

Best Practices

Use environment-based switching

Configure your application to automatically use sandbox in development:

const CRED_BASE_PATH = process.env.NODE_ENV === 'production'
  ? '/api/v2'
  : '/api/v2/sandbox';

Use configuration to manage environments

Add a check to ensure you’re using the correct endpoint in production:

const config = {
  useSandbox: process.env.NODE_ENV !== 'production',
  baseUrl: 'https://api.credprotocol.com'
};

async function getScore(address) {
  const path = config.useSandbox
    ? `/api/v2/sandbox/score/address/${address}`
    : `/api/v2/score/address/${address}`;

  const response = await fetch(`${config.baseUrl}${path}`, {
    headers: { 'Authorization': `Bearer ${API_KEY}` }
  });

  return response.json();
}

Test error handling

The sandbox returns consistent error responses too:

• Invalid addresses return 400 errors
• Missing auth returns 401 errors
• Use these to test your error handling

Don't hardcode sandbox

Never hardcode /sandbox/ in production code:

// ❌ Bad
const url = 'https://api.credprotocol.com/api/v2/sandbox/score/...';

// ✅ Good
const basePath = config.useSandbox ? '/api/v2/sandbox' : '/api/v2';
const url = `https://api.credprotocol.com${basePath}/score/...`;

Transitioning to Production

When you’re ready to go live:

1. Review Your Integration

   Ensure all features work correctly with sandbox data

2. Update Configuration

   Set your environment to production mode

3. Test with Production

   Make a few test requests to verify production access

4. Monitor Usage

   Check your Dashboard to ensure requests are being tracked correctly