---
title: "Purchase prepaid credits via x402 USDC payment"
method: POST
path: "/v5/credits/purchase"
tags: ["Billing"]
---

# Purchase prepaid credits via x402 USDC payment

`POST /v5/credits/purchase`

## Request

- Base URL: `https://headlessoracle.com`
- URL: `https://headlessoracle.com/v5/credits/purchase`
- Auth: API key in header `X-Oracle-Key`

Submit a verified Base mainnet USDC payment to add prepaid credits to a free-plan key (any other plan is refused with 409 CREDITS_NOT_APPLICABLE before payment). Credit tiers: 0.001 USDC = 1 credit, 0.09 USDC = 100 credits, 0.80 USDC = 1000 credits. Requires X-Payment header with verified tx.

## Response `200`

Credits added

- object
  - `purchased` integer, required: Credits added by this payment (1, 100 or 1000, sized from the verified on-chain amount). The new total is at GET /v5/credits/balance.
  - `message` string, required

## Other responses

- `402`: Payment required or insufficient amount
- `409`: CREDITS_NOT_APPLICABLE: the key's plan is not free, so purchased credits could never be spent. Refused before any payment is requested or verified.
- `503`: Payment verification service unavailable

---

[API](https://skmtc.dev/headlessoracle/apis/headless-oracle.md) · [All operations](https://skmtc.dev/headlessoracle/apis/headless-oracle/llms.txt) · [OpenAPI document](https://skmtc.dev/headlessoracle/apis/headless-oracle/revisions/4e82fe332f29?raw)