> ## 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.

# Get Credit Top-up

> Check whether a top-up has been paid and credited at /api/v1/credits/topups/{checkoutId}

## Overview

Returns a top-up's checkout `status` and whether it has been `credited`. This is the read behind `morph billing topup-status`. Each call re-reads the checkout from Coinbase and credits the balance as soon as the payment settles, so there is no need to wait for a webhook.

Gate on `credited`. `FAILED`, `EXPIRED` and `DEACTIVATED` are terminal and unpaid: create a new top-up. While the checkout is still `ACTIVE`, `x402_url` is returned again so a retry can pay it.


## OpenAPI

````yaml GET /api/v1/credits/topups/{checkoutId}
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/{checkoutId}:
    get:
      tags:
        - credits
      summary: Get a credit top-up
      description: >-
        Reads the checkout from Coinbase and credits it on the spot once it has
        settled, so polling here returns `credited: true` without waiting on the
        webhook.
      operationId: getCreditTopup
      parameters:
        - schema:
            type: string
            pattern: ^[0-9a-f]{24}$
            description: Checkout id returned when the top-up was created.
            example: 6ae3c4f9b78e569c621631be
          required: true
          description: Identifies the top-up to read.
          name: checkoutId
          in: path
      responses:
        '200':
          description: The top-up state.
          content:
            application/json:
              example:
                checkoutId: 6ae3c4f9b78e569c621631be
                status: COMPLETED
                amount: '25.00'
                currency: USDC
                credited: true
                transactionHash: >-
                  0x8f5c0e5b8d1f6a3c9e2b7d4a1f0c3e6b9a2d5f8c1e4b7a0d3f6c9e2b5a8d1f4c
                x402_url: null
              schema:
                $ref: '#/components/schemas/CreditTopupStatus'
        '401':
          $ref: '#/components/responses/CreditsUnauthorized'
        '404':
          description: >-
            No top-up with this id belongs to the key. Other accounts’ top-ups
            also return 404.
          content:
            application/json:
              example:
                error: Top-up not found
              schema:
                $ref: '#/components/schemas/CreditsError'
      security:
        - bearerAuth: []
components:
  schemas:
    CreditTopupStatus:
      type: object
      properties:
        checkoutId:
          type: string
          description: Checkout id.
          example: 6ae3c4f9b78e569c621631be
        status:
          $ref: '#/components/schemas/CreditTopupCheckoutStatus'
        amount:
          type: string
          description: USD amount of the top-up, two decimals.
          example: '25.00'
        currency:
          type: string
          enum:
            - USDC
          description: Currency the top-up settles in.
          example: USDC
        credited:
          type: boolean
          description: True once the amount has been added to the balance. Gate on this.
          example: true
        transactionHash:
          type:
            - string
            - 'null'
          description: On-chain capture transaction on Base, once settled.
          example: '0x8f5c0e5b8d1f6a3c9e2b7d4a1f0c3e6b9a2d5f8c1e4b7a0d3f6c9e2b5a8d1f4c'
        x402_url:
          type:
            - string
            - 'null'
          format: uri
          description: >-
            Payment URL while the checkout is still `ACTIVE` and unpaid; null
            otherwise.
          example: null
      required:
        - checkoutId
        - status
        - amount
        - currency
        - credited
        - transactionHash
        - x402_url
      description: Current state of a top-up.
      example:
        checkoutId: 6ae3c4f9b78e569c621631be
        status: COMPLETED
        amount: '25.00'
        currency: USDC
        credited: true
        transactionHash: '0x8f5c0e5b8d1f6a3c9e2b7d4a1f0c3e6b9a2d5f8c1e4b7a0d3f6c9e2b5a8d1f4c'
        x402_url: null
    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.