Allowance agent purchase wallet. Use when the user asks to buy something, make a purchase, order an item, book travel, reserve something, pay, or spend money on their behalf.
Use Allowance to request spending approval from the user and complete purchases on their behalf.
Routing rule
Use the Allowance CLI by default. When the user asks to buy, order, book,
reserve, pay, or spend money, follow the CLI flow below without asking whether
to use CLI or MCP.
Only use the MCP integration if the user explicitly asks for Allowance MCP,
OpenClaw MCP, hosted MCP, remote MCP, or says they cannot install or use the
Allowance CLI. Do not mention MCP during normal purchase flows.
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:
text
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:
Run allowance setup --phone <phone> to send the SMS code. Never run
bare allowance setup — it needs a real terminal and will hang in an
agent session.
Ask the user to read you the 6-digit code.
Run allowance setup --phone <phone> --code <code> to connect.
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 <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 <value> 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
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
Verify local browser control
Verify local browser control using the checklist above.
Request approval (--amount is in cents — include estimated tax + shipping)
text
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.
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.
Issue a virtual card (only once the merchant payment form is visible and ready)
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.
Fetch checkout details only when the merchant form asks for them
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 <iso8601> 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.
text
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:
Call allowance status --allowance-id <allowance_id> --json.
Stop and ask for a new approval if status is not active or expiry has passed.
Check merchant availability using browser tools.
If unavailable, do nothing except keep the automation alive.
If available, add only the exact approved item/config to cart.
If the total exceeds the approved cap, stop and ask for a new approval.
Only at the payment form, call allowance card issue.
Report purchase success or purchase failure with the returned attempt_id.
Explicit MCP setup only
Use this section only if the user explicitly asks for Allowance MCP, OpenClaw
MCP, hosted MCP, remote MCP, or says they cannot install or use the Allowance
CLI. Otherwise, ignore this section and use the CLI flow above.
For OpenClaw, connect the hosted Allowance MCP server with OAuth:
The hosted MCP is an alternate integration path, not the default purchase flow.
Do not ask the user to choose between CLI and MCP. If the user did not ask for
MCP, use the Allowance CLI.