Skip to main content

​
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 EndpointProduction 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: 
# 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:
AddressMock ScoreRange
0x0000000000000000000000000000000000000001935+excellent
0x0000000000000000000000000000000000000002770-858good
0x0000000000000000000000000000000000000003655-769fair
0x0000000000000000000000000000000000000004300-654low

​
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

Configure your application to automatically use sandbox in development:
const CRED_BASE_PATH = process.env.NODE_ENV === 'production'
  ? '/api/v2'
  : '/api/v2/sandbox';
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();
}
The sandbox returns consistent error responses too:
  • Invalid addresses return 400 errors
  • Missing auth returns 401 errors
  • Use these to test your error handling
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