---
title: "Top up the prepaid balance with an x402 payment (agents)"
method: POST
path: "/api/v1/billing/x402/top-up"
tags: ["billing"]
---

# Top up the prepaid balance with an x402 payment (agents)

`POST /api/v1/billing/x402/top-up`

## Request

- Base URL: `https://amplerun-api.spiry.org`
- URL: `https://amplerun-api.spiry.org/api/v1/billing/x402/top-up`
- Auth: HTTP bearer

x402 v2, scheme exact: an EIP-3009 transferWithAuthorization of native USDC on Base (eip155:8453) straight to the treasury. Without a payment header the answer is 402 with PaymentRequirements (also base64 in the PAYMENT-REQUIRED header). Sign them and repeat the same request with PAYMENT-SIGNATURE (the v1 header name X-PAYMENT is accepted too). The payment itself authorizes the top-up; no Idempotency-Key is needed, and repeating the same payment returns the first result. The credit goes to the API key's account whatever wallet pays, and lands once, after Base finality (state PENDING_FINALITY until then). A 202 means the settlement is broadcast but not mined yet; repeat the same request. 404 while the operator has not enabled x402.

## Query parameters

- `amount_micro` string, required: Unsigned base-10 integer as string; never a float.

## Headers

- `PAYMENT-SIGNATURE` string
- `X-PAYMENT` string

## Response `200`

Settled on chain and pinned to this account; credited now (CONFIRMED) or after finality (PENDING_FINALITY). PAYMENT-RESPONSE and X-PAYMENT-RESPONSE carry the base64 SettlementResponse.

- X402TopUp
  - `intent_id` string, uuid, required
  - `state` 'PENDING_FINALITY' | 'CONFIRMED' | 'EXCEPTION', required
  - `amount_micro` string, required: Unsigned base-10 integer as string; never a float.
  - `credited_micro` string: Unsigned base-10 integer as string; never a float.
  - `reason` string
  - `payer` string, required: The wallet that signed the authorization. It need not be linked to the account.
  - `tx_hash` string, required
  - `log_index` integer, required
  - `network` string, required

## Other responses

- `202`: Settlement broadcast, not mined yet. Repeat the same request.
- `402`: Payment required, or the payment was refused (error names the reason, e.g. invalid_amount, authorization_expired).
- `default`: Error envelope. 401 unauthenticated, 403/404 forbidden, 409 conflict, 422 invalid input, 429 rate limited (code UNAVAILABLE, retryable:true, no Retry-After header), 503 unavailable money/provider state with retryable:true.

---

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