# Agent Utilities developer quickstart Bounded tools for HTML, JSON, agent configuration, security indicators and product data. Read /v1/tools for the current catalog. Prices are experimental, from $0.0003 to $0.002 per call. Stripe-funded live service credits are enabled. Check /billing/api/status for the current mode before purchasing. ## Use Python directly The standard-library Python 3.10+ client at /integrations/python provides free discovery, explicit prepaid price ceilings and stable retry identities. No pip install, Node or MCP process is needed. Prepare each logical call once and preserve it for recovery. ## Use an ordinary MCP client Read /integrations/mcp and download the bundled Node.js 22+ stdio adapter. Configure AGENT_UTILITIES_API_KEY privately in its process environment. It handles authorization, stable request IDs, and one automatic retry. Tool discovery needs no key; execution spends prepaid credits. Use agent_utilities_retry with the returned requestId and unchanged tool name and arguments after an uncertain outcome. No card purchases or automatic top-ups occur through the adapter. ## Public content API GET /v1/content/index lists machine-readable material; GET /v1/content returns complete JSON including tool contracts, examples, workflows and documentation. GET /llms-full.txt provides the text version. All are free, require no key and permit cross-origin browser reads. Individual resources are /v1/content/tools/, /v1/content/workflows/ and /v1/content/docs/. This reads documentation; executing tools spends service credits. ### Identify a custom HTTP client Send an honest application `User-Agent`, such as `MyShoppingAgent/1.0`. The provided Python client already does this. A live check on the current workers.dev host found that Python's default `Python-urllib/3.14` signature receives HTTP 403 with Cloudflare error 1010 before the application responds; the identified Python client and tested requests, Node, Axios and Go signatures returned 200. This is an edge compatibility issue, not a request for a payment or API key. Do not send credentials to troubleshoot a public read. ```python import json import urllib.request request = urllib.request.Request( 'https://agent-utilities.agent-utilities.workers.dev/v1/content/index', headers={'Accept': 'application/json', 'User-Agent': 'MyShoppingAgent/1.0'}, ) with urllib.request.urlopen(request, timeout=15) as response: catalog = json.load(response) ``` Browser clients can use their normal browser headers. If an identified client still receives an edge error, stop and report the status through the support contact in /policies. [Cloudflare describes error 1010](https://developers.cloudflare.com/support/troubleshooting/http-status-codes/cloudflare-1xxx-errors/error-1010/) as a browser-signature restriction; changing payment credentials will not resolve it. ## Discover GET /v1/tools returns descriptions, schemas, prices and example requests. GET /v1/tools?category=commerce filters the catalog. GET /openapi.json returns the API contract. POST /mcp supports tool discovery and calls using the same payment headers. ## Card-funded service credits Open /billing and check the displayed mode: 1. Create an API key for the active mode and save it privately. The server stores a hash, not the key. New accounts include a separate recovery key; save both credentials. 2. Open the $5 Checkout to buy credits for useful work. Live mode charges real USD; sandbox mode accepts Stripe test details only. Do not make seller-funded live purchases just to test. 3. Return to /billing and paste your saved key. Check your balance. A browser redirect is not payment confirmation; only a verified Stripe webhook grants credits. 4. Supply Authorization: Bearer and Idempotency-Key: _ on each tool call. For example, the JSON body for POST /v1/tools/commerce.gtin-validate is: {"code":"036000291452"} Generate a request ID once for a logical operation, and keep that ID, URL and JSON body unchanged for retries. A successful credit response contains result, a receipt with chargedMicroUsd, and recoveryExpiresAt. 1 dollar of service credits = 1,000,000 micro-dollar units. The same numeric tool price applies to either credit mode or test-USDC mode. A $5 pack contains 5,000,000 service micro-dollars. It covers 10,000 calls at 500 units each, or a different number for a mix of tools. Credits are usable only with this service and cannot be transferred or withdrawn. Sandbox credits have no monetary value. GET /billing/api/balance requires the same Bearer key. POST /billing/api/checkout requires a separate stable UUID Idempotency-Key. After a checkout timeout, retry that ID instead of making a new purchase. Check your balance before creating another checkout after the 23-hour checkout retry window. ## Set a maximum price For prepaid credits, send `X-Max-Credit-Micro-Usd: 300` to authorize at most $0.0003 for a new tool call. Read `creditPriceLimits: true` from `/billing/api/status` before relying on this feature. It works on both `POST /v1/tools/` and MCP `tools/call` HTTP requests. Use a nonnegative integer with no leading zeros, at most 999999999999; malformed values return 400. The header requires API-key credits and does not apply to crypto. The ledger returns HTTP 412 with `price_limit_exceeded` if the current price exceeds your ceiling, before creating a reservation, deducting credits or using daily call capacity. Omit the header to use existing behavior. Never automatically raise a rejected ceiling; review the price first. Keep the same ID, tool, body and ceiling after a lost response. A matching completed or pending reservation can be recovered with a zero ceiling because it creates no new reservation. Zero does not cancel or refund a charge already authorized. Recovery still requires the same tool version, price and input and is subject to the ten-minute window. The browser workspace caps each new call at its displayed catalog price. The runnable cart recipe caps its three logical calls at their discovered prices, totaling at most 1300 micro-dollars. MCP adapter 0.3.0 caps each new debit at its startup catalog price; its recovery helper uses a zero ceiling and cannot create a new reservation. It has no total session budget. Older adapter 0.2.1 does not set a ceiling. An API client can set per-call ceilings itself. ## Recovery and limits - Tool results are encrypted and recoverable for ten minutes. The cleanup alarm removes expired result material; cleanup may be delayed by runtime scheduling. - An unfinished reservation is refunded after its recovery deadline. Failed tools are not charged. A restart can rerun an unfinished read-only tool before committing its result. - Request tombstones last one day; old timestamped request IDs cannot create a new debit after cleanup. - No automatic top-ups. No subscription or recurring charge. Refund/dispute events freeze the account for operator review. - Preview limits: 100 account creations per day, 20 lifetime checkout attempts per account and 1,000 new credit tool calls per day across the service. - API key loss can be recovered with the separately saved recovery credential. If both are lost, self-service recovery is unavailable. Account/purchase/credit records persist for reconciliation. See /policies for account and retention information. - Never put keys in URLs, source code, screenshots, logs or shared documents. There is no public free-execution bypass. ## Optional crypto test Open /wallet-test in the browser with MetaMask installed. Select Base Sepolia (84532). This requires test USDC in Circle Gateway and Base Sepolia ETH for the initial approval/deposit. The page can request exactly 1 test-USDC approval and deposit through your wallet; you review and approve transactions yourself. Payment execution stays unavailable until the operator enables the configured testnet service. A test call requests 0.0003 test USDC for GTIN validation. It uses two signatures: the official Circle payment authorization, followed by an input-binding signature. Retry the identical prepared request after response loss or uncertain settlement. Keep the page open until the outcome is known; signed authorizations are held only in tab memory and are lost on reload. An ordinary x402 client needs our request-binding adapter. The included src/client.ts supports both local signing accounts and browser-wallet signers. The service never needs your wallet's private key. ## Current launch status Check /health and /billing/api/status for the deployed flags. A configured test mode is not proof of successful provider payments, profitability or a paying customer. Stripe sandbox checkout, webhook crediting, request retry, duplicate webhook delivery, and refund freeze were verified on September 17, 2026. Live-mode code and credential recovery are implemented. Live provider credentials and deployed mode are configured; a genuine live customer purchase and fulfillment remain unverified. Fixture tests do not prove customer demand. ## Replace an API key In /billing, enter your current key, expand Replace API key, generate a replacement, copy it to private storage and confirm you saved it. Activate the replacement, then update your agents. The old key stops working immediately. Your balance, account ID, checkout history and retry IDs remain the same. Existing pending tool retries in the tab automatically use the new key. For API clients, generate 32 cryptographically random bytes, encode them as 64 lowercase hexadecimal characters and prepend au_live_ for live mode or au_test_ for sandbox. Save that replacement before sending POST /billing/api/accounts/rotate-key with Authorization: Bearer , Content-Type: application/json, and JSON containing only replacementKey. The server stores hashes only. Do not place either key in URLs, logs, shell history or source files. If the response is lost, repeat with the same replacement. If the old credential no longer works, authenticate that same request with the saved replacement itself: alreadyActive confirms it is active without rotating again. Do not generate another replacement until you resolve the outcome. Rotation cannot bypass frozen-account restrictions and is capped at 100 changes per account. Losing both the API and recovery credentials prevents automatic recovery. ## Live versus test mode Read /billing/api/status before using the service. Live keys start au_live_ and create real $5 USD Stripe checkouts; test keys start au_test_ and cannot access live balances. Keep recovery credentials (au_recovery_live_ or au_recovery_test_) separate from your agent. The public workspace accepts only its currently configured mode. Crypto remains a separate testnet-only feature. /policies lists support, refunds, privacy and release limits. ## Recover a lost API key Use Recover an account in /billing. Enter the saved recovery credential, prepare replacement credentials, copy and save both replacements, then activate recovery. The service revokes the previous API key and recovery credential atomically while preserving your account ID, balance, purchases, retry records and any account freeze. API clients can POST /billing/api/accounts/recover using Authorization: Bearer and JSON with replacementKey and replacementRecoveryKey. Each new credential uses 32 cryptographically random bytes encoded as 64 lowercase hexadecimal characters, prefixed for its type and mode. Persist both replacements privately before sending the request. After response loss, retry the same pair; if the old recovery credential is revoked, repeat with the new recovery credential. alreadyActive confirms success. Do not create a new pair to retry an uncertain recovery.