---
title: "Buy prepaid credit for paid calls over HTTP 402: $5 for 500 calls, $20 for 2,000 calls, $50 for 5,000 calls. Without a credential: 402 with the challenges (MPP: a card through a Stripe Shared Payment Token, or USDC on Tempo or Base; x402: USDC on Base). Pay one and send the same request again with the credential. With x-api-key the credit goes onto that key's account; without one the top-up makes an agent account and returns its key (api_key, shown once), which holds the credit, and a claim link for its person. Send an Idempotency-Key header with both requests: the same key answers the same and never pays twice. A balance holds at most $100 (409 balance_full) and lasts 12 months from the last top-up; it pays for paid calls only, not an Audit Drive. A key's top-up while more than 50 calls are left: 409 balance_not_low unless force: true. The price includes any VAT, and every payment has a receipt. An EU business that sends its VAT ID gets our invoice. The answer has the balance and a receipt_url"
method: POST
path: "/api/credits/topup"
tags: ["Pay over HTTP 402"]
---

# Buy prepaid credit for paid calls over HTTP 402: $5 for 500 calls, $20 for 2,000 calls, $50 for 5,000 calls. Without a credential: 402 with the challenges (MPP: a card through a Stripe Shared Payment Token, or USDC on Tempo or Base; x402: USDC on Base). Pay one and send the same request again with the credential. With x-api-key the credit goes onto that key's account; without one the top-up makes an agent account and returns its key (api_key, shown once), which holds the credit, and a claim link for its person. Send an Idempotency-Key header with both requests: the same key answers the same and never pays twice. A balance holds at most $100 (409 balance_full) and lasts 12 months from the last top-up; it pays for paid calls only, not an Audit Drive. A key's top-up while more than 50 calls are left: 409 balance_not_low unless force: true. The price includes any VAT, and every payment has a receipt. An EU business that sends its VAT ID gets our invoice. The answer has the balance and a receipt_url

`POST /api/credits/topup`

## Request

- Base URL: `https://agentdrives.com`
- URL: `https://agentdrives.com/api/credits/topup`
- Auth: one of:
  - none
  - API key in header `x-api-key`

## Headers

- `Idempotency-Key` string

## Request body

- object
  - `amount_usd` unknown, required
  - `buyer` object: Optional, an Audit paid over HTTP 402: for our invoice. The price includes any VAT. An EU VAT ID that VIES confirms gets our invoice at once, with no VAT outside the Netherlands. 400 invalid_vat_id, invalid_country or invalid_buyer
    - `vat_id` string: EU VAT ID with its country prefix
    - `country` string: Two-letter code of your business's country
    - `company` string: Business name for the invoice
    - `address` string: Postal address for the invoice, one line
  - `agent` string: Without a key: your name as an agent, kept on the new account
  - `force` boolean: Top up although the balance isn't low, or make another account from the same address

## Response `200`

Paid: the balance, the payment, its receipt (and a new account's key)

- CreditTopup
  - `account` object
    - `id` string
    - `type` 'agent'
  - `api_key` string: Without a key only: the new account's key, shown once (again only to the same Idempotency-Key)
  - `claim` ClaimLink
    - `url` string, uri: For the person: open it and sign in
    - `expires_at` string, date-time
    - `how` string
    - `mailed_to` string
    - `mailed` boolean
  - `credit` object: The account's credit after this call
    - `balance_cents` integer
    - `calls_left` integer
    - `expires_at` string, date-time, nullable
    - `paid_cents` integer: What this call took
    - `low` boolean: 50 calls left or fewer: time to top up
    - `topup` object: How to top up, when low
  - `topup` object
    - `id` string
    - `amount_cents` integer
    - `calls` integer
  - `payment` object
    - `rail` 'mpp' | 'x402'
    - `method` 'stripe' | 'tempo' | 'evm'
    - `amount_cents` integer
    - `reference` string
    - `payment_intent` string, nullable
    - `vat` object
    - `receipt_url` string
    - `invoice` object, nullable
  - `replayed` boolean: The same Idempotency-Key again: this is the first answer, nothing was charged twice
  - `next` string

## Other responses

- `400`: Error as problem details (RFC 9457) with a machine-readable `error` and a `fix` that says what to do next
- `401`: Error as problem details (RFC 9457) with a machine-readable `error` and a `fix` that says what to do next
- `402`: Payment Required: the challenges in WWW-Authenticate (MPP: Payment, method stripe, tempo or evm) and PAYMENT-REQUIRED (x402 v2, exact, USDC on Base), and a body with error payment_required, what it buys, accepts (the rails on now), fix and, in Stripe's test mode, test_mode: true
- `409`: Error as problem details (RFC 9457) with a machine-readable `error` and a `fix` that says what to do next
- `422`: Error as problem details (RFC 9457) with a machine-readable `error` and a `fix` that says what to do next
- `429`: Error as problem details (RFC 9457) with a machine-readable `error` and a `fix` that says what to do next
- `502`: Error as problem details (RFC 9457) with a machine-readable `error` and a `fix` that says what to do next
- `503`: Error as problem details (RFC 9457) with a machine-readable `error` and a `fix` that says what to do next

---

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