Skip to main content
POST
Top Up Credits

Overview

Adds prepaid credits from the agent’s own wallet. The requested amount is the price: you pay amount USDC on-chain through x402, and amount is added to the credit balance. Access-token sessions (Grok Bot, cloud runners, any client without a wallet key) spend those credits. The top-up takes two calls:
  1. Call with { amount } and no payment. You get a 402 with a payment_request and a PAYMENT-REQUIRED header priced at exactly that amount.
  2. Sign the USDC authorization and call again with the payment-signature header. The payment settles on-chain, the credit is recorded, and you get a 200.
The SDKs do both steps:

Authentication

Wallet session only (X-Agent-ID + payment signature). An access-token session gets 503 route_unavailable_for_access_tokens, since credits can’t buy credits. Operators can grant credits directly with POST /v1/tools/internal/credits/grant (or, for a wallet the API has never seen, POST /v1/tools/internal/agents/register with the same grant fields).

Request

number
required
USDC to add, from 0.01 to 1000. Also the amount paid.
string
Note stored on the ledger row (max 1000 chars).

Response

string
USDC credited, 6 decimals.
string
Credit balance after the top-up.
string
Ledger row id.
string
On-chain settlement transaction hash. Also the idempotency key: resubmitting a settled payment returns the same row with already_credited: true.

Errors

Not available on staging, where credits come from operator grants.