---
title: "Buy a prepaid credit bundle over x402 (one settlement = many scans)."
method: POST
path: "/v1/credits/topup"
---

# Buy a prepaid credit bundle over x402 (one settlement = many scans).

`POST /v1/credits/topup`

## Request

- Base URL: `https://lazaretto.dev`
- URL: `https://lazaretto.dev/v1/credits/topup`
- Auth: none declared

Body {bundle:"starter"|"pro"|"scale"}. Pay the bundle price via x402; returns a new X-API-Key with credits (or tops up a presented key). One credit = one full scan.

## Response `200`

Key + credit balance.

## Other responses

- `400`: Unknown bundle (body lists bundles with prices).
- `402`: Payment required: same dual-stack x402 challenge as /v1/scan (v2 header + v1 body), priced per bundle. x402-fetch v1 clients must raise maxValue above its $0.10 default.
- `409`: payment_in_use: this x402 payment is already in use by another request, or was used for one within the last few minutes. Nothing was settled or issued for this request. Sign a new payment.
- `500`: paid_not_fulfilled: the payment settled but the credits could not be issued. Do not pay again. Email contact@lazaretto.dev with the tx_hash from the body if it is present, otherwise with the paying wallet address and the time of payment, and the credits are issued by hand.
- `502`: settlement_outcome_unknown: the payment facilitator did not answer clearly (an error, a timeout, a dropped connection, or a failure reported after a transfer may have gone out), so whether the payment moved is unknown. No credits are issued. Do not pay again. The body carries `tx_hash` when the facilitator named a transaction. Email contact@lazaretto.dev with the paying wallet address and the `time` from the body; if the payment did settle, the credits are issued by hand.

---

[API](https://skmtc.dev/lazaretto/apis/lazaretto-skill-tool-verification-api.md) · [All operations](https://skmtc.dev/lazaretto/apis/lazaretto-skill-tool-verification-api/llms.txt) · [OpenAPI document](https://skmtc.dev/lazaretto/apis/lazaretto-skill-tool-verification-api/revisions/2bd4e34d0067?raw)