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

# Mint Test Tokens

> Sandbox only. Mints SPHEREUSDC, the sandbox test stablecoin, to the given address on a test network (ethereum is Sepolia, sol is Solana Devnet). The mint is submitted asynchronously: poll GET /v2/sandbox/faucet/{id} for the tx hash. Send an Idempotency-Key header to make retries safe: the same key returns the same mint, and reusing a key with different parameters is rejected with 409. Limits: 10 mints per hour per application, at most 1000 per mint, and a wallet balance cap of 10000 (409 when a mint would exceed it).

This endpoint works only against `https://api.sandbox.spherepay.co`. It mints SPHEREUSDC, the sandbox test stablecoin, to the given address on a test network (`ethereum` is Sepolia, `sol` is Solana Devnet). The mint is submitted asynchronously, so poll [Retrieve a Test Token Mint](https://docs.spherepay.co/api-reference/sandbox/faucet-get-id.md) for the transaction hash. Send an `Idempotency-Key` header to make retries safe: the same key returns the same mint, and reusing a key with different parameters returns `409`. Limits are 10 mints per hour per application, at most 1000 per mint, and a wallet balance cap of 10000 (`409` when a mint would exceed it).


## OpenAPI

````yaml openapi/spherepay.yaml POST /v2/sandbox/faucet
openapi: 3.0.0
info:
  contact: {}
  description: The Sphere REST API for payments, transfers, and accounts.
  title: Sphere API
  version: '2'
servers:
  - description: Production
    url: https://api.spherepay.co
  - description: Sandbox
    url: https://api.sandbox.spherepay.co
security:
  - bearer: []
tags: []
paths:
  /v2/sandbox/faucet:
    post:
      summary: Mint test tokens
      description: >-
        Sandbox only. Mints SPHEREUSDC, the sandbox test stablecoin, to the
        given address on a test network (ethereum is Sepolia, sol is Solana
        Devnet). The mint is submitted asynchronously: poll GET
        /v2/sandbox/faucet/{id} for the tx hash. Send an Idempotency-Key header
        to make retries safe: the same key returns the same mint, and reusing a
        key with different parameters is rejected with 409. Limits: 10 mints per
        hour per application, at most 1000 per mint, and a wallet balance cap of
        10000 (409 when a mint would exceed it).
      operationId: postV2SandboxFaucet
      parameters:
        - description: >-
            Caller idempotency key (1 to 128 characters: letters, digits, "_",
            ".", ":" or "-"). Scoped to the application.
          in: header
          name: Idempotency-Key
          required: false
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              properties:
                address:
                  description: Wallet address that receives the tokens.
                  example: '0xdEc79ba951875fc930F5309181d5b71b821E97FE'
                  maxLength: 255
                  minLength: 1
                  type: string
                amount:
                  description: >-
                    Amount of SPHEREUSDC in human units, as a decimal string.
                    Defaults to 1000; at most 1000 per request. A mint that
                    would take the wallet above 10000 SPHEREUSDC, counting mints
                    still pending, is refused with 409.
                  example: '1000'
                  pattern: ^\d+(\.\d+)?$
                  type: string
                network:
                  description: >-
                    Test network to mint on: ethereum (Sepolia) or sol (Solana
                    Devnet).
                  enum:
                    - ethereum
                    - sol
                  example: ethereum
                  type: string
              required:
                - network
                - address
              type: object
        required: true
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FaucetMintResponseDto'
          description: ''
        '400':
          content:
            application/json:
              examples:
                Bad Request:
                  summary: Bad Request
                  value:
                    code: address/invalid
                    correlationId: 28c61e885c6e5eaa78c1a2183a9b883c
                    detail: Invalid request parameters
                    status: 400
              schema:
                $ref: '#/components/schemas/ProblemDetailsDto'
          description: Bad Request
        '404':
          content:
            application/json:
              examples:
                Not Found:
                  summary: Not Found
                  value:
                    code: resource/not-found
                    correlationId: 28c61e885c6e5eaa78c1a2183a9b883c
                    detail: Resource not found
                    status: 404
              schema:
                $ref: '#/components/schemas/ProblemDetailsDto'
          description: Not Found
        '422':
          content:
            application/json:
              examples:
                Validation Error:
                  summary: Validation Error
                  value:
                    code: validation/failed
                    correlationId: 28c61e885c6e5eaa78c1a2183a9b883c
                    detail: Validation failed
                    errors:
                      - detail: Invalid email format
                        pointer: /email
                      - detail: Name is required
                        pointer: /name
                    status: 422
              schema:
                $ref: '#/components/schemas/ProblemDetailsDto'
          description: Unprocessable Entity - Validation Error
      servers:
        - description: Sandbox
          url: https://api.sandbox.spherepay.co
components:
  schemas:
    FaucetMintResponseDto:
      properties:
        address:
          type: string
        amount:
          type: string
        createdAt:
          type: string
        currency:
          enum:
            - SPHEREUSDC
          type: string
        id:
          description: Mint id. Poll GET /v2/sandbox/faucet/{id} for the tx hash.
          type: string
        network:
          enum:
            - ethereum
            - sol
          type: string
        status:
          description: >-
            pending: queued; submitted: sent to the chain; succeeded: confirmed
            on chain (txHash set); failed: not minted, request again with a new
            Idempotency-Key.
          enum:
            - pending
            - submitted
            - succeeded
            - failed
          type: string
        txHash:
          nullable: true
          type: string
      required:
        - id
        - status
        - network
        - address
        - amount
        - currency
        - txHash
        - createdAt
      type: object
    ProblemDetailsDto:
      properties:
        code:
          type: string
        correlationId:
          type: string
        detail:
          type: string
        errors:
          items:
            properties:
              detail:
                type: string
              header:
                type: string
              parameter:
                type: string
              pointer:
                type: string
            required:
              - detail
            type: object
          type: array
        status:
          type: integer
        title:
          type: string
      required:
        - status
        - detail
      type: object
  securitySchemes:
    bearer:
      bearerFormat: JWT
      scheme: bearer
      type: http

````

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