---
title: "Add credits by paying this request (Machine Payments Protocol, HTTP 402)"
method: POST
path: "/v1/credits/topup"
---

# Add credits by paying this request (Machine Payments Protocol, HTTP 402)

`POST /v1/credits/topup`

## Request

- Base URL: `https://varosity.ai/api`
- URL: `https://varosity.ai/api/v1/credits/topup`
- Auth: API key in header `X-API-Key`

The first call returns 402 with a payment challenge (WWW-Authenticate: Payment). An MPP client pays it — card through a Stripe Link agent wallet, or USDC on Tempo — and retries with Authorization: Payment <credential>. Because Authorization carries the payment, send the Varosity key as X-API-Key. amountUsd: whole dollars 5–500 (default 10); credits equal dollars paid; each payment is credited once, to the account that requested it.

## Query parameters

- `amountUsd` integer

## Response `200`

Paid and credited: { credited_cents, balance_cents, receipt } plus a Payment-Receipt header

## Other responses

- `400`: amountUsd is not a whole number from 5 to 500
- `401`: Missing or invalid key — send it as X-API-Key
- `402`: Payment required: challenge in WWW-Authenticate (also returned when a credential does not match this account or amount)
- `429`: Too many challenges or payment attempts this hour
- `500`: Paid but the credit did not post; support is alerted
- `502`: Payment could not be processed; nothing was charged
- `503`: Machine payments unavailable

## Changes

- **2026-10-20** `81d0169a4897`: 1 info
  - the endpoint scheme security `apiKeyHeader` was added to the API

[Operation history](https://skmtc.dev/varosity/apis/varosity-ai-api/changes/v1/credits/topup/post.md)

---

[API](https://skmtc.dev/varosity/apis/varosity-ai-api.md) · [All operations](https://skmtc.dev/varosity/apis/varosity-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/varosity/apis/varosity-ai-api/revisions/81d0169a4897?raw)