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

# Mint a Sandbox Key

> Mint a sandbox API key with no account and no authentication, and get a complete example order back with it.

Mints a provisional account and a `zn_test_` API key. **No authentication required** — this is the entry point for an agent that has nothing but the hostname.

The response is written to be self-guiding: send `api_key` as a Bearer token, `POST` the `example_order` body to `/orders` as-is, and work through `next` in order.

```bash theme={null}
curl -X POST https://api.zinc.com/sandbox/keys \
  -H "Content-Type: application/json" \
  -d '{"name": "acme-shopping-agent dev testing"}'
```

An empty body — or no body at all — is valid. Both fields are optional:

* `name` becomes the key's label in the dashboard.
* `email` is the address of whoever will [claim](/docs/v2/api-reference/sandbox/claim-sandbox) this sandbox later. It is never required and is not used for anything else.

## What you get back

| Field            | Use                                                                                                          |
| ---------------- | ------------------------------------------------------------------------------------------------------------ |
| `api_key`        | The `zn_test_` key. Send as `Authorization: Bearer <api_key>`; test keys route to the sandbox automatically. |
| `example_order`  | A complete, valid `POST /orders` body. Send it unchanged for your first order.                               |
| `claim_url`      | Give this to the human you work for. This is the **only** time it's returned — only its hash is stored.      |
| `quickstart_url` | Where to fetch [the agent quickstart](/docs/v2/api-reference/sandbox/get-agent-quickstart) as markdown.           |
| `expires_policy` | Plain-language statement of the 7-idle-day expiry.                                                           |
| `next`           | The ordered list of steps to take now.                                                                       |

<Info>
  Keys expire after **7 days without use**, and everything they created is sandbox data that is deleted with them. Any use resets the clock, so persist the key across runs rather than minting a new one each time.
</Info>

## Rate limits

This endpoint is capped per IP per day, plus a global daily ceiling.

* **`429`** — daily cap reached. Reuse a key you already minted, or wait out `Retry-After` (the window resets at UTC midnight; `X-RateLimit-Reset` gives the exact timestamp).
* **`503`** — the sandbox or its limiter is temporarily unavailable. The limiter fails closed rather than leaving an unauthenticated write path uncapped. Retry after `Retry-After`.

<Warning>
  Treat `429` as "reuse what you have", not "retry in a loop". A minted key is good for 7 idle days, so an agent that stores its key needs the mint endpoint roughly once.
</Warning>


## OpenAPI

````yaml versions/latest.json POST /sandbox/keys
openapi: 3.1.0
info:
  title: Zinc
  summary: >-
    Zinc lets you search, buy, and return items from top online retailers with a
    single API.
  description: >-
    Search, buy, and return items from top online retailers with a single API.
    Supports AI agent ordering via MPP (HTTP 402) — no account required.
    Supported retailers include 1-800-Flowers, Ace Hardware, Amazon, Amazon DE,
    Barnes & Noble, Best Buy, Chewy, Gap, IBS, Lowe's, Macys, Partstown, and 11
    more. Ships to the US and 2 other countries (DE, IT).
  version: '2026-08-21'
  x-logo:
    url: https://mintlify.s3.us-west-1.amazonaws.com/zinc/logo/light.png
  contact:
    name: Zinc API Support
    email: support@zinc.com
    url: https://zinc.com/docs
  x-guidance: >-
    Zinc lets AI agents buy products from online retailers via a single API. Use
    POST /agent/orders to place an order — no Zinc account needed, payment is
    handled via MPP (HTTP 402 flow). Provide a product URL from a supported
    retailer, a shipping address, and max_price in cents. The API charges
    max_price + $1 API fee upfront and refunds the difference on completion. To
    find products first, the /agent/* data endpoints (search, products/search,
    products/offers, products/details) are MPP-paid at $0.01 per call;
    /agent/search returns orderable URLs to feed straight into /agent/orders.
    GET /retailers lists supported retailers for free (no payment or account).
    Authenticated equivalents (orders, products, managed-accounts) require a
    Bearer token (API key prefixed zn_). Docs: https://zinc.com/docs Supported
    retailers include 1-800-Flowers, Ace Hardware, Amazon, Amazon DE, Barnes &
    Noble, Best Buy, Chewy, Gap, IBS, Lowe's, Macys, Partstown, and 11 more,
    shipping to the US and 2 other countries (DE, IT).
  x-supported-retailers:
    - 1-800-Flowers
    - Ace Hardware
    - Amazon
    - Amazon DE
    - Barnes & Noble
    - Best Buy
    - Chewy
    - Gap
    - IBS
    - Lowe's
    - Macys
    - Partstown
    - Pokémon Center
    - Sephora
    - Target
    - The Home Depot
    - TikTok
    - Walmart
    - Wayfair
    - Zinc
    - eBay
    - libraccio
    - zazzle
  x-supported-countries:
    - US
    - DE
    - IT
servers:
  - url: https://api.zinc.com
    description: Production
security:
  - BearerAuth: []
paths:
  /sandbox/keys:
    post:
      tags:
        - sandbox
      summary: Mint a sandbox API key (no account needed)
      description: Mint a provisional sandbox user + test API key. No account needed.
      operationId: create_sandbox_key_sandbox_keys_post
      requestBody:
        content:
          application/json:
            schema:
              anyOf:
                - $ref: '#/components/schemas/SandboxKeyCreate'
                - type: 'null'
              title: Body
      responses:
        '201':
          description: >-
            Sandbox key minted. The body is self-guiding: send `api_key` as a
            Bearer token, POST `example_order` to /orders as-is, and follow
            `next`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxKeyResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: >-
            Daily mint limit reached — sandbox keys are limited to a few per IP
            per day (plus a global cap). Reuse a key you already minted (valid
            until 7 days after its last use) or retry after `Retry-After`
            elapses.
          headers:
            Retry-After:
              description: Seconds until the daily window resets (UTC midnight)
              schema:
                type: integer
            X-RateLimit-Reset:
              description: Unix timestamp of the window reset
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: >-
            Temporarily unable to mint — the sandbox or its rate limiter is
            unavailable (the limiter fails closed by design). Safe to retry
            after `Retry-After`.
          headers:
            Retry-After:
              description: Suggested backoff in seconds
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security: []
components:
  schemas:
    SandboxKeyCreate:
      properties:
        email:
          anyOf:
            - type: string
              maxLength: 254
            - type: 'null'
          title: Email
          description: >-
            (optional) Your operator's email address — we'll send them a link to
            claim this sandbox and its order history when they want a live
            account. Never used for anything else, and never required.
        name:
          anyOf:
            - type: string
              maxLength: 100
            - type: 'null'
          title: Name
          description: >-
            (optional) What this key is for, e.g. 'acme-shopping-agent dev
            testing'. Becomes the key's label.
      type: object
      title: SandboxKeyCreate
      description: |-
        Optional context for a sandbox key mint.

        An empty body (or none at all) is valid — nothing here gates the mint.
    SandboxKeyResponse:
      properties:
        api_key:
          type: string
          title: Api Key
          description: >-
            Sandbox API key (zn_test_...). Send as `Authorization: Bearer
            <api_key>` — test keys route to the sandbox automatically, no extra
            headers needed.
        expires_policy:
          type: string
          title: Expires Policy
        quickstart_url:
          type: string
          title: Quickstart Url
        example_order:
          additionalProperties: true
          type: object
          title: Example Order
          description: A complete valid body for POST /orders — try it as-is.
        claim_url:
          type: string
          title: Claim Url
          description: >-
            Give this to the human you work for. Signing in there folds this
            sandbox — its order history and this key, which keeps working — into
            their Zinc account. Poll GET /sandbox/status to find out when they
            have.
        next:
          items:
            type: string
          type: array
          title: Next
          description: What to do now, in order.
      type: object
      required:
        - api_key
        - expires_policy
        - quickstart_url
        - example_order
        - claim_url
        - next
      title: SandboxKeyResponse
      description: |-
        A freshly minted sandbox key, with the next steps inline.

        The response doubles as documentation: agents read the bytes they get
        back, not a docs site, so every field they need to proceed is here.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ErrorResponse:
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetail'
      type: object
      required:
        - error
      title: ErrorResponse
      description: Wrapper for error responses.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    ErrorDetail:
      properties:
        code:
          $ref: '#/components/schemas/ErrorCode'
        message:
          type: string
          title: Message
        details:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Details
      type: object
      required:
        - code
        - message
      title: ErrorDetail
      description: Standard error response body.
    ErrorCode:
      type: string
      enum:
        - unauthorized
        - forbidden
        - invalid_token
        - token_expired
        - not_found
        - already_exists
        - validation_error
        - insufficient_funds
        - payment_failed
        - payment_method_required
        - invalid_payment_method
        - invalid_shipping_address
        - url_unreachable
        - non_us_retailer
        - unsupported_retailer
        - unsupported_country
        - retailer_country_not_supported
        - guest_checkout_not_supported
        - invalid_variant
        - out_of_stock
        - shipping_unavailable
        - order_not_cancellable
        - return_not_allowed
        - external_service_error
        - stripe_error
        - stytch_error
        - internal_error
        - bad_request
        - rate_limit_exceeded
        - service_unavailable
      title: ErrorCode
      description: Standardized error codes for the API.
  securitySchemes:
    BearerAuth:
      type: apiKey
      in: header
      name: Authorization
      description: Zinc API key (Bearer zn_...)

````