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

# Create Credit Top-up

> Buy credits with USDC from an agent at /api/v1/credits/topups

## Overview

Creates a USDC checkout for `amount` (US dollars, $10 to $10,000) and returns its `x402_url`. This is the write behind `morph billing topup`.

1. Call this route with your Morph API key and read `x402_url` and `checkoutId`.
2. POST to `x402_url` with an x402 client that supports the `auth-capture` scheme on Base (`AuthCaptureEvmScheme` from `@x402/evm`). A client that only handles the `exact` scheme cannot pay it. See Coinbase's [x402 checkout guide](https://docs.cdp.coinbase.com/coinbase-business/checkout-apis/accept-x402-payments).
3. A 200 from `x402_url` means the funds are authorized, not credited. Poll [Get Credit Top-up](https://docs.morphllm.com/api-reference/endpoint/credits-topup-get.md) until `credited` is `true`.

`url` is the same checkout as a hosted page, for paying in a browser instead. The checkout accepts payment for 24 hours.

Pass `idempotencyKey` (a UUID v4) to make retries return the same checkout. An account's first top-up needs a verified phone number or a prior card top-up; until then this route returns `403 phone_verification_required`. Organization keys top up the organization and require an organization admin.


## OpenAPI

````yaml POST /api/v1/credits/topups
openapi: 3.1.0
info:
  title: Morph API
  version: 1.2.0
  description: >-
    The Morph public API at api.morphllm.com: OpenAI- and Anthropic-compatible
    inference (chat completions, messages), Fast Apply code editing, Compact
    context compression, Singleshot typed decisions, model listing, and
    dedicated endpoint management, and agentic credit top-ups paid over x402.
    Model ids, prices, and context windows are served live at
    https://www.morphllm.com/api/models/json.
  contact:
    name: Morph
    url: https://morphllm.com
    email: info@morphllm.com
  license:
    name: Proprietary
    url: https://morphllm.com/privacy/tos
servers:
  - url: https://api.morphllm.com
    description: Production
security: []
tags:
  - name: chat
    description: >-
      OpenAI- and Anthropic-compatible chat inference, including Fast Apply and
      WarpGrep models.
  - name: compact
    description: Context compression for long agent conversations.
  - name: singleshot
    description: 'Typed decisions: a state in, a calibrated distribution per question out.'
  - name: models
    description: Model listing.
  - name: dedicated
    description: Dedicated endpoint discovery, status, and cancellation.
  - name: credits
    description: Agentic credit top-ups paid in USDC over x402.
  - name: telemetry
    description: Usage reporting hooks.
paths:
  /api/v1/credits/topups:
    post:
      tags:
        - credits
      summary: Create a credit top-up
      description: >-
        Creates a USDC checkout for the amount and returns its `x402_url` for an
        agent to pay. Credits land once the payment settles; poll the status
        route or `morph billing topup-status --wait`. Organization keys top up
        the organization and require an organization admin.
      operationId: createCreditTopup
      requestBody:
        description: Amount to add, plus an optional idempotency key for safe retries.
        content:
          application/json:
            schema:
              type: object
              properties:
                amount:
                  anyOf:
                    - type: string
                    - type: number
                  description: >-
                    USD to add to the balance, from 10 to 10000, with at most
                    two decimals. Paid as the same amount of USDC.
                  example: '25.00'
                idempotencyKey:
                  type: string
                  format: uuid
                  description: >-
                    UUID v4. Retrying with the same key returns the same
                    checkout instead of creating another.
                  example: 3b241101-e2bb-4255-8caf-4136c566a962
              required:
                - amount
              description: Top-up to create.
              example:
                amount: '25.00'
                idempotencyKey: 3b241101-e2bb-4255-8caf-4136c566a962
      responses:
        '201':
          description: Top-up created.
          content:
            application/json:
              example:
                checkoutId: 6ae3c4f9b78e569c621631be
                status: ACTIVE
                amount: '25.00'
                currency: USDC
                x402_url: >-
                  https://api.cdp.coinbase.com/platform/v2/payment-sessions/paymentSession_9a323500-bd94-47f5-9ca8-2dc60e19a8e9/authorizations/x402
                url: >-
                  https://payments.coinbase.com/payment-sessions/paymentSession_9a323500-bd94-47f5-9ca8-2dc60e19a8e9
              schema:
                $ref: '#/components/schemas/CreditTopupCreated'
        '400':
          description: >-
            The amount is missing, out of range, or has more than two decimals,
            or the idempotency key is not a UUID.
          content:
            application/json:
              example:
                error: amount must be a USD amount between 10 and 10000
              schema:
                $ref: '#/components/schemas/CreditsError'
        '401':
          $ref: '#/components/responses/CreditsUnauthorized'
        '403':
          description: >-
            The account needs a verified phone number before its first top-up,
            is not allowed to purchase, or the key belongs to an organization
            member who is not an admin.
          content:
            application/json:
              example:
                error: phone_verification_required
                message: >-
                  Verify a phone number before the first top-up:
                  https://www.morphllm.com/dashboard/billing
              schema:
                $ref: '#/components/schemas/CreditsError'
        '409':
          description: The idempotency key was already used for a different top-up.
          content:
            application/json:
              example:
                error: idempotencyKey was already used for a different top-up
              schema:
                $ref: '#/components/schemas/CreditsError'
      security:
        - bearerAuth: []
components:
  schemas:
    CreditTopupCreated:
      type: object
      properties:
        checkoutId:
          type: string
          description: Checkout id. Poll it at GET /api/v1/credits/topups/{checkoutId}.
          example: 6ae3c4f9b78e569c621631be
        status:
          $ref: '#/components/schemas/CreditTopupCheckoutStatus'
        amount:
          type: string
          description: USD amount, two decimals.
          example: '25.00'
        currency:
          type: string
          enum:
            - USDC
          description: Settlement currency.
          example: USDC
        x402_url:
          type: string
          format: uri
          description: >-
            POST here with an x402 client that supports the `auth-capture`
            scheme on Base (`AuthCaptureEvmScheme` from `@x402/evm`). A 200
            means the funds are authorized, not yet credited. Accepts payment
            for 24 hours.
          example: >-
            https://api.cdp.coinbase.com/platform/v2/payment-sessions/paymentSession_9a323500-bd94-47f5-9ca8-2dc60e19a8e9/authorizations/x402
        url:
          type: string
          format: uri
          description: Hosted checkout page for paying the same top-up in a browser.
          example: >-
            https://payments.coinbase.com/payment-sessions/paymentSession_9a323500-bd94-47f5-9ca8-2dc60e19a8e9
      required:
        - checkoutId
        - status
        - amount
        - currency
        - x402_url
        - url
      description: A created top-up, ready to pay.
      example:
        checkoutId: 6ae3c4f9b78e569c621631be
        status: ACTIVE
        amount: '25.00'
        currency: USDC
        x402_url: >-
          https://api.cdp.coinbase.com/platform/v2/payment-sessions/paymentSession_9a323500-bd94-47f5-9ca8-2dc60e19a8e9/authorizations/x402
        url: >-
          https://payments.coinbase.com/payment-sessions/paymentSession_9a323500-bd94-47f5-9ca8-2dc60e19a8e9
    CreditsError:
      type: object
      properties:
        error:
          type: string
          description: Why the top-up request failed.
          example: Top-up not found
        message:
          type: string
          description: What to do next, when the caller can resolve the error.
          example: >-
            Verify a phone number before the first top-up:
            https://www.morphllm.com/dashboard/billing
      required:
        - error
      description: Error body returned by the credit top-up routes.
      example:
        error: Top-up not found
    CreditTopupCheckoutStatus:
      type: string
      enum:
        - ACTIVE
        - PROCESSING
        - COMPLETED
        - FAILED
        - EXPIRED
        - DEACTIVATED
        - REFUNDED
        - PARTIALLY_REFUNDED
      description: >-
        Coinbase checkout status. `ACTIVE` accepts payment at `x402_url`;
        `PROCESSING` means capture is under way; `COMPLETED` means settled.
        `FAILED`, `EXPIRED` and `DEACTIVATED` are terminal and unpaid, so start
        a new top-up. A completed top-up can later become `REFUNDED` or
        `PARTIALLY_REFUNDED`.
      example: ACTIVE
  responses:
    CreditsUnauthorized:
      description: Missing or invalid Morph API key on a credit top-up request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreditsError'
          example:
            error: Unauthorized
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: opaque
      description: >-
        Morph API key, passed as `Authorization: Bearer sk-...`. Create keys at
        https://www.morphllm.com/dashboard/api-keys.

````

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