Skip to main content
POST
Create a credit top-up

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.
  3. A 200 from x402_url means the funds are authorized, not credited. Poll Get Credit Top-up 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.

Authorizations

Authorization
string
header
required

Morph API key, passed as Authorization: Bearer sk-.... Create keys at https://www.morphllm.com/dashboard/api-keys.

Body

application/json

Amount to add, plus an optional idempotency key for safe retries.

Top-up to create.

amount
required

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
string<uuid>

UUID v4. Retrying with the same key returns the same checkout instead of creating another.

Example:

"3b241101-e2bb-4255-8caf-4136c566a962"

Response

Top-up created.

A created top-up, ready to pay.

checkoutId
string
required

Checkout id. Poll it at GET /api/v1/credits/topups/{checkoutId}.

Example:

"6ae3c4f9b78e569c621631be"

status
enum<string>
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.

Available options:
ACTIVE,
PROCESSING,
COMPLETED,
FAILED,
EXPIRED,
DEACTIVATED,
REFUNDED,
PARTIALLY_REFUNDED
Example:

"ACTIVE"

amount
string
required

USD amount, two decimals.

Example:

"25.00"

currency
enum<string>
required

Settlement currency.

Available options:
USDC
Example:

"USDC"

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.

Example:

"https://api.cdp.coinbase.com/platform/v2/payment-sessions/paymentSession_9a323500-bd94-47f5-9ca8-2dc60e19a8e9/authorizations/x402"

url
string<uri>
required

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"