Allowance

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.

Allowance — Agent Purchase Wallet

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. [phone]). The CLI normalizes to E.164.

When they give you the phone number, proceed in order:

1. 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.
2. Ask the user to read you the 6-digit code.
3. Run allowance setup --phone <phone> --code <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 <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

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)

   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.

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)

   text

   allowance card issue --allowance-id <allowance_id> --amount <cents> --merchant "<name>"
   

   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 <allowance_id>
   • Shipping address (only if item requires shipping): allowance address shipping --allowance-id <allowance_id>
   • Billing address: allowance address billing --allowance-id <allowance_id>

7. Report the outcome (required — unreported purchases block future requests)

   • Success: allowance purchase success --allowance-id <id> --attempt-id <attempt-id> --charged <cents>
   • Failure: allowance purchase failure --allowance-id <id> --attempt-id <attempt-id> --error-code <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 <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:

1. Call allowance status --allowance-id <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.

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:

text

openclaw mcp add allowance \
  --url https://mcp.useallowance.com \
  --transport streamable-http \
  --auth oauth

openclaw mcp login allowance
openclaw mcp doctor allowance --probe

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.