X-API-Key header unless noted otherwise. See Authentication.
Endpoints
Get Wallet Balance
GET /v1/wallet
Get the caller’s wallet: current balance, auto-reload configuration, per-product contract rates,
and any in-flight top-up. Returns 404 with FEATURE_NOT_AVAILABLE on legacy (non-wallet) accounts.
string
Current spendable balance in
currency. Negative means overdrawn.string
object | null
null means the auto-reload contract read failed, not that it’s unconfigured.object | null
null means no in-flight top-up, or the ledger read failed.object | null
null means the rates read failed, or the wallet has no rate contract yet.string
Present when an agent can add funds itself:
POST here and pay the 402 MPP challenge.Top Up the Wallet
POST /v1/wallet/top-up
Add money to the wallet, paid by the calling agent over the Machine Payments Protocol (MPP). The
first call answers 402 with a payment challenge in WWW-Authenticate; retry with a
Payment-Authorization credential to settle the charge and credit the wallet. Full handshake
walkthrough: TinyAgent Payments.
string
required
USD amount to add, from
10.00 to 500.00.200 settled or 202 pending):
string
string
string
string
The Stripe PaymentIntent that settled this top-up.
string
string | null
null when pending or unreadable.string
On a
202: don’t pay again.