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

Operation: x402TopUp.

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.

Endpoint

POST https://amplerun-api.spiry.org/api/v1/billing/x402/top-up

Authentication

Use the credential and scope required by this operation. For programmatic renter/host calls: Authorization: Bearer $AMPLERUN_API_KEY. A host-agent signature or other specialized proof is required where the description specifies it.

Parameters

Name	Location	Presence	Type	Description
amount_micro	query	Required	DecimalString	Top-up amount in micro-USDC (“5000000” = 5 USDC).
PAYMENT-SIGNATURE	header	Optional	string	Base64 JSON x402 v2 PaymentPayload.
X-PAYMENT	header	Optional	string	Same as PAYMENT-SIGNATURE (x402 v1 header name).

Responses

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.

application/json

Field	Type	Presence	Description
intent_id	UUID	Required
state	“PENDING_FINALITY” / “CONFIRMED” / “EXCEPTION”	Required
amount_micro	DecimalString	Required
credited_micro	DecimalString	Optional
reason	string	Optional
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

{
  "$ref": "#/components/schemas/X402TopUp"
}

202

Settlement broadcast, not mined yet. Repeat the same request.

application/json

Field	Type	Presence	Description
state	“SETTLING”	Required
tx_hash	string	Required
retry	string	Optional

{
  "type": "object",
  "required": [
    "state",
    "tx_hash"
  ],
  "properties": {
    "state": {
      "enum": [
        "SETTLING"
      ]
    },
    "tx_hash": {
      "type": "string"
    },
    "retry": {
      "type": "string"
    }
  }
}

402

Payment required, or the payment was refused (error names the reason, e.g. invalid_amount, authorization_expired).

application/json

Field	Type	Presence	Description
x402Version	2	Required
error	string	Required
resource	object	Required
accepts	array of object	Required

{
  "$ref": "#/components/schemas/X402PaymentRequired"
}

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.

application/json

Field	Type	Presence	Description
error	object	Required

{
  "$ref": "#/components/schemas/ErrorEnvelope"
}

Static request outline

Replace path/query placeholders and provide the required JSON body, headers and credential from the sections above. This is a request outline, not a command that chooses an amount or starts a rental for you.

curl --request POST 'https://amplerun-api.spiry.org/api/v1/billing/x402/top-up' \
  --header "Authorization: Bearer $AMPLERUN_API_KEY"

Schema definitions · Download OpenAPI · Authentication · Errors and recovery