---
title: "Deposit-first top-up via x402 — pay once, get a reusable balance + API key"
method: POST
path: "/api/v1/x402/topup"
tags: ["Agent Payments (x402)"]
---

# Deposit-first top-up via x402 — pay once, get a reusable balance + API key

`POST /api/v1/x402/topup`

## Request

- Base URL: `https://virtualsms.io`
- URL: `https://virtualsms.io/api/v1/x402/topup`
- Auth: one of:
  - API key in header `X-API-Key`
  - API key in query parameter `api_key`

LIVE. Call without payment to receive the HTTP 402 payment manifest; retry with a
valid `X-PAYMENT` (or `PAYMENT-SIGNATURE`) header to settle inline. On success returns
an API key (returned once) plus a USD balance, usable through the standard
`/api/v1/customer/*` REST API at ordinary retail prices — no further per-call payment.

Canonical discovery manifest: `https://virtualsms.io/.well-known/x402.json`

Accepted payment rails: Base USDC, Solana USDC, Solana USDT, BNB Chain USDC, BNB Chain
USDT. Deposit bounds: $2.50 minimum, $10000 maximum, $2.50 default, set via the
optional `amount_usd` field.

Depositing again from the same wallet does NOT mint a second key by default — the
first key stays valid. Set `mint_new_key: true` to mint a fresh one (e.g. the original
was lost); the wallet's own signature is the proof of ownership.

## Request body

- object
  - `amount_usd` number: Optional USD deposit amount, default 2.50, min 2.50, max 10000
  - `mint_new_key` boolean: Mint a fresh API key even if this wallet already has one

## Response `200`

Payment settled — balance credited, API key returned (once) on a first deposit

- object
  - `status` 'credited' | 'credit_pending' | 'already_processed'
  - `api_key` string: Returned once, only on a wallet's first deposit or when mint_new_key was set
  - `user_id` string
  - `balance_usd` number
  - `credited_usd` number
  - `endpoints` object: The standard customer API routes to spend the balance with the api_key
  - `x402_settlement` object
    - `tx_hash` string
    - `amount_paid_usdc` number
    - `network` string
    - `token` string

## Other responses

- `400`: Invalid amount_usd or malformed X-PAYMENT header
- `402`: Payment Required

---

[API](https://skmtc.dev/virtualsms/apis/virtualsms-account-verification-platform-for-developers-and.md) · [All operations](https://skmtc.dev/virtualsms/apis/virtualsms-account-verification-platform-for-developers-and/llms.txt) · [OpenAPI document](https://skmtc.dev/virtualsms/apis/virtualsms-account-verification-platform-for-developers-and/revisions/be89af981be1?raw)