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

# Sandbox Mode

> Test the API for free with a sandbox key: no wallet, no payment, mock data

Sandbox mode lets you test the Limitguard API without calling real data sources, making USDC payments, or spending a prepaid balance.

## How to Activate

Sandbox mode is decided by the key, never by a header: a request is a sandbox request when its `X-API-Key` is a sandbox key (`lg_sandbox_...`).

1. Create a free sandbox key. No wallet, no payment:

```bash theme={null}
curl -X POST https://api.limitguard.ai/v1/keys/create \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "tier": "sandbox"}'
# -> {"api_key": "lg_sandbox_...", "tier": "sandbox", ...}
```

2. Send it on any endpoint:

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.limitguard.ai/v1/entity/check \
    -H "X-API-Key: lg_sandbox_xxxxxxxxxxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{"entity_name": "Any Company Name", "country": "NL"}'
  ```

  ```python Python theme={null}
  import httpx

  response = httpx.post(
      "https://api.limitguard.ai/v1/entity/check",
      headers={"X-API-Key": "lg_sandbox_xxxxxxxxxxxxxxxxxxxx"},
      json={"entity_name": "Any Company Name", "country": "NL"},
  )
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.limitguard.ai/v1/entity/check", {
    method: "POST",
    headers: {
      "X-API-Key": "lg_sandbox_xxxxxxxxxxxxxxxxxxxx",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ entity_name: "Any Company Name", country: "NL" }),
  });
  ```
</CodeGroup>

<Warning>
  There is no sandbox header. An `X-Limitguard-Mode: sandbox` header is ignored, so a request that sends it with a live key is a normal, paid call. Keys starting with `lg_test_` are refused in production with `401 Test keys not accepted in production`.
</Warning>

`POST /v1/reports/entity` (and the MCP `get_compliance_report` tool) refuses sandbox keys with `403`: reports are built only from real checks.

## Sandbox Behavior

| Property | Behavior |
| - | - |
| **Data sources** | No real sources called (KVK, sanctions, VIES, etc.) |
| **Responses** | Deterministic mock data: the same input always gives the same output |
| **Payments** | No USDC payment required: x402 is skipped |
| **Balance** | Not debited |
| **Rate limit** | 10 requests per minute per IP |

## Mock Data Examples

### /v1/entity/check (sandbox)

```json theme={null}
{
  "trust_score": 75,
  "trust_level": "medium",
  "cluster": "verified_startup",
  "recommendation": "review",
  "confidence": 0.85,
  "top_factors": [
    {
      "source": "sandbox",
      "signal": "Mock data for Acme Corp BV",
      "impact": "positive",
      "weight": 0.5
    }
  ],
  "correlations": {},
  "sources_checked": 0,
  "processing_time_ms": 1,
  "version": "1.0",
  "sandbox": true
}
```

The `signal` echoes the `entity_name` you sent. `sandbox: true` marks every mock response.

### /v1/risk/score (sandbox)

```json theme={null}
{
  "risk_score": 25,
  "risk_level": "low",
  "recommendation": "proceed",
  "top_factors": [
    {
      "source": "sandbox",
      "signal": "Mock risk data for Acme Corp BV",
      "impact": "positive",
      "weight": 0.4
    }
  ],
  "processing_time_ms": 1,
  "sandbox": true
}
```

## Rate Limit Response

When the sandbox rate limit is exceeded:

```json theme={null}
HTTP 429

{
  "error": "Sandbox rate limit exceeded (10 req/min). Use a real API key for higher limits."
}
```

The response includes a `Retry-After: 60` header.

## Use Cases

| Scenario | Recommendation |
| - | - |
| First-time integration | Sandbox key |
| CI/CD automated tests | Sandbox key in an environment variable; it can never trigger a paid call |
| Frontend development | Sandbox key |
| Load testing | Sandbox key (10 requests per minute per IP); never load test production |
| Demo / prototype | Sandbox key |

## Middleware Execution Order

Sandbox detection runs **before** x402 payment verification, so a sandbox request never reaches the payment check and is never charged.

## Transitioning to Production

When ready to use real data, replace the `lg_sandbox_` key with an `lg_live_` key from the [dashboard](https://dashboard.limitguard.ai/sign-up) or `POST /v1/keys/create`, or pay per call with [x402](/x402-protocol).

No other code changes required. The same endpoints, request format, and response structure apply in both modes.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.