> ## Documentation Index
> Fetch the complete documentation index at: https://paperplane-justin-winter-s-projects.vercel.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Buy a credit pack via x402 (agent payments)

> Agent-payable alternative to /v1/credits/checkout for funded agents that can't open a human payment_url. Follows the x402 v2 handshake: call once without an X-PAYMENT header to get a 402 challenge, then retry with the header set to a signed payment payload. Disabled on deployments without a configured facilitator — see docs/PRD-agentic-payments.md. Pass `sandbox: true` to mint a real credit code with no facilitator call and no charge, on any deployment.



## OpenAPI

````yaml /openapi.json post /v1/x402/credits
openapi: 3.1.0
info:
  title: paperplane API
  version: 1.0.0
  summary: Send real physical mail from code.
  description: >-
    Upload a PDF or paste text; we print it and hand it to USPS the next
    business day. No account required — pay per letter with a Stripe link or a
    prepaid credit code, and use `sandbox: true` to exercise the whole flow for
    free.


    Every failure returns the same envelope: `status`, a stable machine-readable
    `code`, a human `reason`, and a `next` array of concrete recovery steps.


    This document is generated from the same zod schemas the server validates
    with, so it cannot describe an endpoint that does not exist.
  contact:
    name: paperplane support
    url: https://sendpaperplane.com/contact
  license:
    name: Proprietary
    identifier: LicenseRef-Proprietary
  termsOfService: https://sendpaperplane.com/terms
servers:
  - url: https://sendpaperplane.com
    description: Production
security: []
tags:
  - name: Mail
    description: Quote, send, track, and cancel letters.
  - name: Credits
    description: Prepaid balances that pay for letters without a card.
  - name: Reviews
    description: Post-delivery feedback. Identity is derived from the order, not supplied.
  - name: Addresses
    description: >-
      Typeahead and reverse geocoding. Convenience only; USPS verification is
      authoritative.
  - name: Meta
    description: Machine-readable description of this API.
paths:
  /v1/x402/credits:
    post:
      tags:
        - Credits
      summary: Buy a credit pack via x402 (agent payments)
      description: >-
        Agent-payable alternative to /v1/credits/checkout for funded agents that
        can't open a human payment_url. Follows the x402 v2 handshake: call once
        without an X-PAYMENT header to get a 402 challenge, then retry with the
        header set to a signed payment payload. Disabled on deployments without
        a configured facilitator — see docs/PRD-agentic-payments.md. Pass
        `sandbox: true` to mint a real credit code with no facilitator call and
        no charge, on any deployment.
      operationId: buyCreditsWithX402
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/X402CreditsRequest'
            example:
              pack: value
              email: jordan@example.com
      responses:
        '200':
          description: >-
            Settlement replay — this transaction hash already minted an account,
            so the same credit code is returned with `replayed: true` and no
            `settlement`. Nothing was charged twice.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/X402CreditsResponse'
              example:
                status: ok
                credit_code: pp-ab12-cd34-ef56
                face_cents: 1999
                bonus_cents: 700
                replayed: true
        '201':
          description: 'Credits minted (or a free sandbox: true rehearsal)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/X402CreditsResponse'
              example:
                status: ok
                credit_code: pp-ab12-cd34-ef56
                face_cents: 1999
                bonus_cents: 700
                settlement:
                  network: eip155:8453
                  tx_hash: '0xdeadbeef'
        '400':
          description: Unknown pack id or malformed email.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: >-
            No X-PAYMENT header (challenge returned instead) or the payment
            payload failed facilitator verification.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: >-
            `region_unsupported` — the stablecoin lane is hidden in this region
            (New York).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '501':
          description: >-
            x402 is not enabled on this deployment yet — use
            /v1/credits/checkout or a credit_code instead.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    X402CreditsRequest:
      type: object
      properties:
        pack:
          type: string
        email:
          type: string
          format: email
          pattern: >-
            ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
        sandbox:
          type: boolean
      required:
        - pack
        - email
    X402CreditsResponse:
      type: object
      properties:
        status:
          type: string
          const: ok
        credit_code:
          type: string
        face_cents:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        bonus_cents:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        settlement:
          type: object
          properties:
            network:
              type: string
            tx_hash:
              type: string
            stripe_payment_intent_id:
              type: string
          required:
            - network
            - tx_hash
        replayed:
          type: boolean
        sandbox:
          type: boolean
      required:
        - status
        - credit_code
        - face_cents
        - bonus_cents
    Error:
      type: object
      properties:
        status:
          type: string
          enum:
            - failed
            - action_required
        code:
          type: string
        reason:
          type: string
        next:
          type: array
          items:
            type: string
      required:
        - status
        - code
        - reason
        - next

````