---
title: "Buy prepaid x402 credit (agents)"
method: POST
path: "/v1/credits/topup"
---

# Buy prepaid x402 credit (agents)

`POST /v1/credits/topup`

## Request

- Base URL: `https://api.recallsapi.com`
- URL: `https://api.recallsapi.com/v1/credits/topup`
- Auth: none required

Answers 402 with one x402 exact-scheme requirement (USDC on Base) for the chosen amount ($1 when amount is left out); pay it with any x402 client. After the payment settles on-chain the answer carries `credit_token`, shown once and stored only as a hash. Send an existing token as X-Credit-Token to add to its balance instead. Not refundable; does not expire; one balance holds at most $1,000.

## Query parameters

- `amount` '1' | '5' | '20'

## Headers

- `X-Credit-Token` string
- `PAYMENT-SIGNATURE` string

## Response `200`

Paid and credited

- object
  - `credit_token` string: Only when a new token was created
  - `added_usd` string
  - `balance_usd` string
  - `balance_micro_usd` integer
  - `prices_usd` object
  - `transaction` string
  - `network` string
  - `refundable` boolean
  - `expires` boolean

## Other responses

- `400`: amount is not one of the top-up amounts
- `401`: Unknown credit token
- `402`: Payment Required: x402 v2 payment requirements (scheme exact, USDC on Base, amount in base units, payTo) in the PAYMENT-REQUIRED header as base64 JSON, and the same object as the body
- `409`: Transaction already credited, or the balance limit would be passed
- `503`: Facilitator unavailable

---

[API](https://skmtc.dev/recallsapi/apis/recallsapi-com.md) · [All operations](https://skmtc.dev/recallsapi/apis/recallsapi-com/llms.txt) · [OpenAPI document](https://skmtc.dev/recallsapi/apis/recallsapi-com/revisions/2501df40ea54?raw)