---
title: "`POST /v1/x402/topup?usd={bundle}`."
method: POST
path: "/v1/x402/topup"
tags: ["self-serve"]
---

# \`POST /v1/x402/topup?usd={bundle}\`.

`POST /v1/x402/topup`

## Request

- Base URL: `https://api.mapmap.ai`
- URL: `https://api.mapmap.ai/v1/x402/topup`
- Auth: none declared

## Query parameters

- `usd` string, required

## Response `200`

Settled and credited: `{status, creditedMillipence, balanceMillipence, tx, network, fxMicroUsdPerPence}`; `status: "replay"` reports an already-processed authorization without settling twice

## Other responses

- `400`: Unknown bundle (body lists the allowlist) or operator key without an identity ledger
- `402`: x402 payment required: `accepts[0].maxAmountRequired` is the bundle's exact atomic amount; `extra` carries `bundleUsd`, `creditMillipenceEstimate` and `fxMicroUsdPerPence`. Retry with `X-PAYMENT` signing exactly that amount
- `404`: Top-up not enabled on this deployment (needs bundles + the FX knob)

---

[API](https://skmtc.dev/mapmap/apis/sn-gateway.md) · [All operations](https://skmtc.dev/mapmap/apis/sn-gateway/llms.txt) · [OpenAPI document](https://skmtc.dev/mapmap/apis/sn-gateway/revisions/2293be8b4c38?raw)