---
title: "Top up an existing wallet-owned active card directly with x402"
method: POST
path: "/api/card/topup"
---

# Top up an existing wallet-owned active card directly with x402

`POST /api/card/topup`

## Request

- Base URL: `https://api.x402card.org`
- URL: `https://api.x402card.org/api/card/topup`
- Auth: none declared

Public agent marketplace entrypoint. The Base USDC payer must own an active card. The server selects that card; funding is asynchronous and the current load fee applies.

## Request body

- object
  - `amountUsdCents` integer: Gross USDC payment in integer USD cents. Omit to use the current configured default.
  - `idempotencyKey` string, required: Stable caller-generated key. Reuse it after an ambiguous response.

## Response `200`

Settled funding order with queued asynchronous card top-up

## Other responses

- `402`: Payment Required
- `409`: Active card missing, terms changed, idempotency conflict, or order is no longer payable
- `503`: Funding worker, provider BIN, treasury reconciliation, or backing float is unavailable

---

[API](https://skmtc.dev/x402card/apis/x402card-virtual-cards-and-freeland-esim-api.md) · [All operations](https://skmtc.dev/x402card/apis/x402card-virtual-cards-and-freeland-esim-api/llms.txt) · [OpenAPI document](https://skmtc.dev/x402card/apis/x402card-virtual-cards-and-freeland-esim-api/revisions/90ffb84a664e?raw)