billing

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

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.

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

Query parameters

amount_microstring required

Unsigned base-10 integer as string; never a float.

Example:1

Top-up amount in micro-USDC ("5000000" = 5 USDC).

Headers

PAYMENT-SIGNATUREstring

Base64 JSON x402 v2 PaymentPayload.

X-PAYMENTstring

Same as PAYMENT-SIGNATURE (x402 v1 header name).

Response

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.

intent_idstring uuid required
state'PENDING_FINALITY' | 'CONFIRMED' | 'EXCEPTION' required
amount_microstring required

Unsigned base-10 integer as string; never a float.

credited_microstring

Unsigned base-10 integer as string; never a float.

reasonstring
payerstring required

The wallet that signed the authorization. It need not be linked to the account.

tx_hashstring required
log_indexinteger required
networkstring required

Example response

{
  "intent_id": "3f0e2a55-8c1b-4d2e-9a6f-0b7c1d2e3f40",
  "amount_micro": "1",
  "credited_micro": "1"
}

Changes

No recorded changes to this operation across all 1 revision of this API.