---
title: "Create a credit top-up"
method: POST
path: "/api/v1/credits/topups"
tags: ["credits"]
---

# Create a credit top-up

`POST /api/v1/credits/topups`

## Request

- Base URL: `https://api.morphllm.com`
- URL: `https://api.morphllm.com/api/v1/credits/topups`
- Auth: HTTP bearer

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.

## Request body

- object: Top-up to create.
  - `amount` union, required: USD to add to the balance, from 0.01 to 10000, with at most two decimals. Paid as the same amount of USDC.
    - string
    - number
  - `idempotencyKey` string, uuid: UUID v4. Retrying with the same key returns the same checkout instead of creating another.

## Response `201`

Top-up created.

- CreditTopupCreated: A created top-up, ready to pay.
  - `checkoutId` string, required: Checkout id. Poll it at GET /api/v1/credits/topups/{checkoutId}.
  - `status` 'ACTIVE' | 'PROCESSING' | 'COMPLETED' | 'FAILED' | 'EXPIRED' | 'DEACTIVATED' | 'REFUNDED' | 'PARTIALLY_REFUNDED', required: 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`.
  - `amount` string, required: USD amount, two decimals.
  - `currency` 'USDC', required: Settlement currency.
  - `x402_url` string, uri, required: 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.
  - `url` string, uri, required: Hosted checkout page for paying the same top-up in a browser.

## Other responses

- `400`: The amount is missing, out of range, or has more than two decimals, or the idempotency key is not a UUID.
- `401`: Missing or invalid Morph API key on a credit top-up request.
- `403`: 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.
- `409`: The idempotency key was already used for a different top-up.

## Changes

- **2026-10-29** `f379850e2856`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/morphllm/apis/morph-api/changes/api/v1/credits/topups/post.md)

---

[API](https://skmtc.dev/morphllm/apis/morph-api.md) - [All operations](https://skmtc.dev/morphllm/apis/morph-api/llms.txt) - [OpenAPI document](https://skmtc.dev/morphllm/apis/morph-api/revisions/d5b145cc274e?raw)