> ## Documentation Index
> Fetch the complete documentation index at: https://docs.credprotocol.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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?

<CardGroup cols={2}>
  <Card title="Free Testing" icon="dollar-sign">
    Sandbox requests don't count against your API quota
  </Card>

  <Card title="Instant Responses" icon="bolt">
    No blockchain queries means instant responses
  </Card>

  <Card title="Consistent Data" icon="repeat">
    Deterministic responses for reliable testing
  </Card>

  <Card title="No Dependencies" icon="plug">
    Test without relying on blockchain data availability
  </Card>
</CardGroup>

## 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:

<CodeGroup>
  ```bash cURL theme={null}
  # 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"
  ```

  ```javascript JavaScript theme={null}
  const BASE_URL = 'https://api.credprotocol.com';

  // Use an environment variable to switch between sandbox and production
  const useSandbox = process.env.NODE_ENV === 'development';

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

    const response = await fetch(`${BASE_URL}${endpoint}`, {
      headers: { 'Authorization': `Bearer ${API_KEY}` }
    });

    return response.json();
  }
  ```

  ```python Python theme={null}
  import os
  import requests

  BASE_URL = 'https://api.credprotocol.com'
  USE_SANDBOX = os.environ.get('ENVIRONMENT') == 'development'

  def get_score(address):
      endpoint = f'/api/v2/sandbox/score/address/{address}' if USE_SANDBOX else f'/api/v2/score/address/{address}'

      response = requests.get(
          f'{BASE_URL}{endpoint}',
          headers={'Authorization': f'Bearer {API_KEY}'}
      )

      return response.json()
  ```
</CodeGroup>

### 2. Sandbox Response Format

Sandbox responses use the same format as production:

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

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

## 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:

```javascript theme={null}
// 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:

```javascript theme={null}
// __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

```yaml theme={null}
# .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

<AccordionGroup>
  <Accordion title="Use environment-based switching">
    Configure your application to automatically use sandbox in development:

    ```javascript theme={null}
    const CRED_BASE_PATH = process.env.NODE_ENV === 'production'
      ? '/api/v2'
      : '/api/v2/sandbox';
    ```
  </Accordion>

  <Accordion title="Use configuration to manage environments">
    Add a check to ensure you're using the correct endpoint in production:

    ```javascript theme={null}
    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();
    }
    ```
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="Don't hardcode sandbox">
    Never hardcode `/sandbox/` in production code:

    ```javascript theme={null}
    // ❌ 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/...`;
    ```
  </Accordion>
</AccordionGroup>

## Transitioning to Production

When you're ready to go live:

<Steps>
  <Step title="Review Your Integration">
    Ensure all features work correctly with sandbox data
  </Step>

  <Step title="Update Configuration">
    Set your environment to production mode
  </Step>

  <Step title="Test with Production">
    Make a few test requests to verify production access
  </Step>

  <Step title="Monitor Usage">
    Check your Dashboard to ensure requests are being tracked correctly
  </Step>
</Steps>