POST/v1/x402/topup

Public. No key, and no quota deducted.

Call it

bash

curl -fsS -X POST "https://api.mapmap.ai/v1/x402/topup?usd=…"

Parameters

Name	In	Required	Description
usd	query	yes	Bundle from the configured allowlist (USD), e.g. `5` or `0.10`

Responses

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

400Unknown bundle (body lists the allowlist) or operator key without an identity ledger

402x402 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

404Top-up not enabled on this deployment (needs bundles + the FX knob)

Error bodies follow the shared problem model documented on API conventions.

Also under self-serve

GET /v1/jobs GET /v1/jobs/{id}POST /v1/keys GET /v1/keys/self POST /v1/keys/self/webhook-secret GET /v1/keys/verify GET /v1/usage

Generated from https://api.mapmap.ai/openapi.json on 2026-09-17 · operationId post_topup