--- description: Allowance agent purchase wallet. Use when the user asks to buy something, make a purchase, order an item, or spend money on their behalf. when_to_use: Use whenever a purchase needs to be made or the user wants to buy something. Provides the full CLI-based checkout flow including requesting approval, issuing a virtual card, and reporting the outcome. --- ## Allowance — Agent Purchase Wallet Use Allowance to request spending approval from the user and complete purchases on their behalf. ### First-run setup This applies when `allowance` is not on PATH, or when `allowance` commands return "No connection token found" or similar. If `allowance` is not on PATH, install it globally first: ``` npm install -g @allowance/cli ``` Then, before doing anything else, send the user this message verbatim: > Allowance is installed — I have a wallet now 💰. What are we buying, and what's my limit? Wait for the user's reply with the item and spend limit. Do not run any other commands or ask any other questions until they reply. Once you have the item and limit, ask for the phone number: > Got it. What's your phone number? I'll text you a code to verify it, then use that number for approval whenever I need to buy something. Common phone formats: US (`415-555-1234`, `4155551234`); international numbers need a `+countrycode` prefix (e.g. `+442079460958`). The CLI normalizes to E.164. When they give you the phone number, proceed in order: 1. Run `allowance setup --phone ` to send the SMS code. **Never run bare `allowance setup`** — it needs a real terminal and will hang in an agent session. 2. Ask the user to read you the 6-digit code. 3. Run `allowance setup --phone --code ` to connect. 4. Continue to "Local Browser Requirement" and the purchase flow below, using the item and spend limit they already gave you. Do not ask for those again. If the code didn't work, the same SMS code is valid for up to 5 attempts in 10 minutes — re-run with the corrected code. If it has expired, re-run `allowance setup --phone ` to get a fresh SMS. ### Local Browser Requirement Allowance CLI purchases are local-browser-only. Before running `allowance request`, verify this current agent session has a tool that can open and control a local browser checkout page. This means the session can: - open the merchant website - navigate pages - click buttons and links - type into checkout forms - read page state enough to complete checkout This passes if the current session has one of: - a dedicated browser automation tool - a computer-use tool that can operate a browser - a Chrome extension or browser relay controlled by the agent - another explicit browser-control tool This does not pass if you only have: - web search - HTTP fetch, curl, or static page retrieval - screenshots without click/type control - a browser visible to the user but not controllable by you - browser access from a previous or different session - uncertainty about whether browser tools are available If this check does not pass, do not run `allowance request` and do not create an approval request. Tell the user: "Allowance is the right payment flow, but this agent session cannot complete local checkout yet. Please switch to or connect a browser-capable agent session, such as Codex with Browser/Computer Use, Claude with Computer Use or a browser-control extension, or OpenClaw with browser enabled. Then I can create the Allowance approval request and complete checkout." If this check passes, continue. ### Browser Tool Values Use `--local-browser-tool ` only when this current session can control a local browser. Accepted values: - `browser-tool`: dedicated browser automation tool, such as Codex Browser or OpenClaw Browser - `computer-use`: a computer-use tool that can operate a browser, such as Codex Computer Use or Claude Computer Use - `chrome-extension`: a Chrome extension or browser relay controlled by the agent - `other-browser-control`: another explicit browser-control tool that can navigate, click, type, and inspect checkout pages If unsure which value applies, do not create the request. ### Purchase flow 1. **Gather purchase details** Gather only the minimum required purchase details: - merchant - item intent - high-risk variants like size/color - all-in spend cap - shipping requirement 2. **Verify local browser control** Verify local browser control using the checklist above. 3. **Request approval** (`--amount` is in cents — include estimated tax + shipping) ``` allowance request --merchant "Zara" --url "https://www.zara.com/us/" \ --amount 5000 --reason "buy a black men's medium tee" \ --local-browser-tool computer-use ``` Sends a push notification to the user's phone. Blocks until approved or denied (up to 10 min). On approval, prints the `allowance_id` needed for subsequent commands. Add `--no-shipping` for digital goods, services, pickup, or any non-shipped item. Do not run `allowance request` without `--local-browser-tool`. 4. **After approval, open the merchant site in the local browser and complete checkout** Approval on the user's iPhone is the **only human gate**. Once `allowance request` returns `approved`, complete checkout end-to-end — including clicking submit / place order — without asking the user to confirm again. Re-prompt the user only if: - the realized total would exceed the approved cap (`--amount`), or - you must substitute a materially different item or variant than the approval reason allows, or - checkout requires information you don't have and can't fetch from allowance-scoped identity or address commands. Otherwise, do not add a second human gate. The virtual card is capped, so a within-cap submission is safe to perform autonomously. 5. **Issue a virtual card** (only once the merchant payment form is visible and ready) ``` allowance card issue --allowance-id --amount --merchant "" ``` Returns a one-time virtual card number, expiry, and CVV — it expires after the purchase. **Never paste, summarize, or reveal card number, CVV, expiry, or last four in chat.** Type them directly into the merchant checkout form only. 6. **Fetch checkout details only when the merchant form asks for them** - Identity/contact details: `allowance identity --allowance-id ` - Shipping address (only if item requires shipping): `allowance address shipping --allowance-id ` - Billing address: `allowance address billing --allowance-id ` 7. **Report the outcome** (required — unreported purchases block future requests) - Success: `allowance purchase success --allowance-id --attempt-id --charged ` - Failure: `allowance purchase failure --allowance-id --attempt-id --error-code ` Valid error codes: `card_declined`, `card_declined_avs`, `card_declined_cvv`, `checkout_abandoned`, `checkout_error`, `checkout_timeout`, `item_unavailable`, `merchant_rejected`, `price_mismatch`, `unsupported_card` - If the card is declined: report failure immediately. Do not retry or issue another card unless the user explicitly asks and a new allowance approval is obtained. ### Long-running / buy-later purchases For out-of-stock, restock, sale-watching, or other buy-later tasks, Allowance is only the approval and payment primitive. Use the agent or scheduler's own automation system to keep checking: - OpenClaw heartbeat: repeated lightweight availability checks in the main session - OpenClaw cron: exact schedules or one-shot reminders - Codex automations: scheduled resumptions that can continue an existing thread; local browser work still requires the local app/session to be awake and usable - Claude Code routines: scheduled work; hooks are lifecycle automation, not the primary inventory polling mechanism Gather bounded purchase intent first: product, merchant URL, all-in cap, required variants, shipping requirement, and latest acceptable purchase date. Then request approval up front. If the agent is setting up a monitor, recurring check, or delayed purchase, it must pass `--delayed-purchase` plus either `--allowance-valid-for-days <1-14>` or `--allowance-expires-at ` when creating the approval. `--delayed-purchase` means the approval may be used later within a bounded window; it does not mean the agent must wait. If the exact approved item is available immediately and checkout is ready, complete checkout immediately. Future fulfillment is not delayed purchase by itself: "order this for pickup next week" is still an immediate purchase if the order is placed now. ``` allowance request \ --merchant Apple \ --amount 80000 \ --reason "Monitor Apple.com for up to 14 days and buy a base Mac mini if available under $800 all-in." \ --url "https://www.apple.com/shop/buy-mac/mac-mini" \ --local-browser-tool computer-use \ --delayed-purchase \ --allowance-valid-for-days 14 \ --json ``` Save `allowance_id`, merchant URL, cap, product constraints, expiry, and check cadence in the scheduler outside Allowance. On every automation run: 1. Call `allowance status --allowance-id --json`. 2. Stop and ask for a new approval if status is not `active` or expiry has passed. 3. Check merchant availability using browser tools. 4. If unavailable, do nothing except keep the automation alive. 5. If available, add only the exact approved item/config to cart. 6. If the total exceeds the approved cap, stop and ask for a new approval. 7. Only at the payment form, call `allowance card issue`. 8. Report `purchase success` or `purchase failure` with the returned `attempt_id`.