Browse wiki · Agent billing API
Agent billing API
Let an agent manage invoice credits
Create an Agent · invoices and credit purchases key in the API tab. Keep its secret in your server or agent secret store. Existing keys gain no new permissions automatically.
Use your workspace API base: https://YOUR_HOST/w/YOUR_WORKSPACE_ID/v1. All requests below require Authorization: Bearer YOUR_API_KEY.
| Endpoint | Permission | Purpose |
|---|---|---|
| GET /billing | billing:read | Credit balance, USDC unit price, purchase bounds, invoice limit and duration tariffs |
| POST /credit-purchases | billing:write | Create or reuse a checkout for credits |
| GET /credit-purchases/{id} | billing:read | Read the canonical purchase returned by creation |
Check balance before creating an invoice
curl "$API_BASE/billing" -H "Authorization: Bearer $API_KEY"The balance is a snapshot, not a reservation. Concurrent creators may consume credits; handle HTTP 402 from invoice creation. Reads consume no credits.
Create a credit purchase
curl "$API_BASE/credit-purchases" \
-H "Authorization: Bearer $API_KEY" \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: topup-order-1001' \
--data '{"credits":10}'Choose 10–100,000 whole credits. The server calculates the price and platform recipient. Return the response's url to a human payer; creating a checkout does not charge a wallet or grant credits. An agent may pay only through a separately authorized payer integration. Merchant API keys cannot sign wallet transactions.
HTTP 201 means created; 200 can mean a matching active checkout was reused. Save the returned canonical id and url. Retry with the same idempotency key and quantity after a timeout. A different quantity with the same key returns 409.
Confirm credit delivery
Poll GET /credit-purchases/{id} with backoff. The purchase starts as pending and becomes credited after independently confirmed payment and atomic credit delivery. Pending is a credit-delivery state, not proof the checkout is still payable; check the linked invoice for payment expiry. Then read GET /billing again. A receipt or submitted transaction alone is not credit delivery.
Portal and agent purchases share limits: two active unpaid checkouts per workspace and ten admitted new purchase requests per UTC day. Matching open checkouts are reused; retries of an existing idempotency key do not create another purchase. Respect 429 Retry-After. Billing is workspace-wide, not isolated per key or recipient.
Automatic wallet debit is not implemented. Scheduled invoice creation is available separately. Webhook settings are available in the API tab. Use explicit checkout payment and bounded polling.