---
title: "Provision a sandbox or credit key for testing"
method: POST
path: "/v5/sandbox"
tags: ["Authentication"]
---

# Provision a sandbox or credit key for testing

`POST /v5/sandbox`

## Request

- Base URL: `https://headlessoracle.com`
- URL: `https://headlessoracle.com/v5/sandbox`
- Auth: none declared

Two paths: (1) Email path — POST with { "email": "..." } to get a sb_ sandbox key (7 days, 200 calls). One key per email/IP per 7-day window. (2) x402 agent path — POST with X-Payment header containing a valid Base mainnet USDC payment ($0.001). Skips email entirely; returns a ho_crd_ credit key with 10 credits. Agent-native: no human in the loop. Sandbox keys are rejected by /v5/receipts and /v5/webhooks/subscribe (paid features).

## Headers

- `X-Payment` string

## Request body

- object
  - `email` string, email: Required for email path. Omit when using X-Payment header.
  - `use_case` string: Brief description of what you're building (helps us prioritise).

## Response `200`

Key issued (sandbox or credit)

- object
  - `api_key` string
  - `tier` 'sandbox' | 'credits'
  - `email_captured` boolean
  - `expires_at` string, date-time
  - `calls_remaining` integer
  - `credits` integer: Credit balance (x402 path only).
  - `upgrade_url` string
  - `quickstart` object

## Other responses

- `400`: Email missing or invalid (email path)
- `402`: X-Payment header invalid or payment verification failed (x402 path)
- `429`: Sandbox allocation already used for this IP or email
- `503`: x402 payments not configured on this instance

---

[API](https://skmtc.dev/headlessoracle/apis/headless-oracle.md) · [All operations](https://skmtc.dev/headlessoracle/apis/headless-oracle/llms.txt) · [OpenAPI document](https://skmtc.dev/headlessoracle/apis/headless-oracle/revisions/4e82fe332f29?raw)