> ## Documentation Index > Fetch the complete documentation index at: https://docs.agentcard.sh/llms.txt > Use this file to discover all available pages before exploring further. # Set rules on a card > Set rules on a card: how much it spends, where, when, at which merchants, and from which program. You can put rules on a card so an agent spends only what you meant. A rule never lets a card spend more than the money on it; it only narrows where, when, and on what. A card without rules is a normal card. Put the rules on one card, save them under a name and reuse them, or make them the default for your account or for one connected app, an app or MCP tool that acts for you. When a card is created, one set of rules applies: the rules on the create call, else the app's default, else your account default, else none. ## Choose what to restrict | Rule | What it does | | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Total** | The most the card spends over its life. | | **Rate** | A cap per rolling 24 hours, 7 days, or 30 days. Every card under the same preset shares one window. | | **Category** | `meals`, `groceries`, `travel`, `software`, `ai`, `wellness`, `retail`. `Strict` refuses an off-category charge; `Watch` lets it through and tells you; see [Choose `Strict` or `Watch`](#choose-strict-or-watch). | | **Merchant** | Name patterns the charge must match, such as `OPENAI`. | | **Remembered merchants** | Names you allow after a refusal. Not a restriction: a remembered merchant passes the category and merchant rules and nothing else. | | **Place** | The country or US state the merchant is in. Not where your agent runs. | | **Currency** | The currency a purchase is charged in, such as `USD, EUR`, written as a code or a common name. `Strict` refuses a purchase in another currency; `Watch` lets it through and tells you. Agentcard enforces it; the card network does not; see [Choose the currencies](#choose-the-currencies). | | **Time window** | Days and hours, always in a named zone. UTC unless you pass `--timezone`. | | **Where the card can be used from** | The CLI, an MCP tool, the API, or the dashboard: `--only-from cli`, `mcp`, `api`, or `browser`. | A rate is shared across every card using the preset. `--per-day 25` on a saved name means \$25 a day for all of them together. A charge over the rate at Agentcard checkout is refused, and you are told why. A charge made straight at a merchant is checked when it settles: over the rate, Agentcard pauses a multi-use card and tells you. The card network holds only each card's total. All rules apply together. When Agentcard cannot judge a rule, the purchase is refused and you are told why; an `--only-from` rule refuses when Agentcard cannot tell whether the CLI, an MCP tool, the API, or the dashboard is asking. Every refusal in this guide works that way. You are told by email within moments of the charge, or by a text on your iMessage thread if you have no email on file. The notice names the merchant and the amount and carries the exact command to allow the merchant: ```text theme={null} agent-cards cards preset allow-merchant cmtt4mw7s001fbr8zeel9tzse "GROCERY MART" ``` ## Allow a refused merchant When a category or merchant rule refuses a merchant you meant to allow, one command allows it: ```bash theme={null} agent-cards cards preset allow-merchant cmtt4mw7s001fbr8zeel9tzse 'GROCERY MART' ``` The loop is three lines: 1. The purchase is refused and you are told why. 2. You run one command naming the merchant. 3. The card resumes and the retry goes through. One step. No form, no support ticket, no new card. The merchant stays allowed on that card from then on. The pause or watch notice carries this command with the card id and merchant filled in; a refusal at checkout carries it with the merchant filled in and `` for you to replace. A card paused after settlement takes `agent-cards cards resume ` before the retry; a refusal at checkout needs nothing more. Over MCP the same step is one tool call: ```json theme={null} { "tool": "allow_card_merchant", "arguments": { "card_id": "cmtt4mw7s001fbr8zeel9tzse", "pattern": "GROCERY MART" } } ``` The rest of this guide explains the rules; [Remember a merchant](#remember-a-merchant) covers card and account scope. `--only-from` says which of your tools may use the card. Agentcard decides by how the request signed in, not by what the tool says about itself. | Who is asking | Counts as | | ---------------------------------------------------------------- | --------------------------------------------------------------------------- | | Your company's API key | `api` | | An app you connected, including its MCP tools | `mcp` | | You, signed in at the command line | `cli` | | You, signed in to the dashboard or talking to Agentcard in Slack | `browser` | | A scheduled purchase | Whoever set up the schedule: `mcp` for a connected app, otherwise `browser` | Your sign-in is shared by the CLI and the dashboard, so Agentcard reads which one is asking from the request itself. A checkout you approve in the vault, where your own added card lives, does not go through presets at all; your approval is the control there. ## Start with a built-in | Name | What it does | | --------------- | ------------------------------------------------------------------------ | | `daily` | \$50 per rolling 24 hours, shared by every card on this preset | | `weekday_meals` | Restaurants only, `Strict`, weekdays 11:00 to 14:00 America/Los\_Angeles | | `cli_only` | Credentials and purchases from the CLI only | | `ai_labs` | AI vendors: OpenAI, Anthropic, Gemini and similar | Combine them with commas: `cli_only,daily`. To see the built-ins and your saved names together: ```bash theme={null} agent-cards cards preset list ``` ## Write your own rules Put the rules on the create call, or save them under a name and pass the name. Pass `--preset` or rule flags, not both; the command refuses the pair. ```bash theme={null} # One-off on create agent-cards cards create --amount 80 \ --per-day 25 \ --only-categories meals \ --only-days weekdays \ --only-hours 11-14 \ --timezone America/Los_Angeles \ -y # Save for reuse (same flags) agent-cards cards preset save lunch \ --per-day 25 \ --only-categories meals \ --only-days weekdays \ --only-hours 11-14 \ --timezone America/Los_Angeles agent-cards cards create --amount 80 --preset lunch -y ``` Hours and days run in UTC unless you pass `--timezone`. Every summary and every refusal names the zone, for example `weekdays 11:00-14:00 America/Los_Angeles`. The zone must be a real IANA name. `America/Los_Angles` is refused rather than silently run in UTC. The flags: | Flag | Meaning | | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--total` | Lifetime spend cap, in US dollars. `--amount` is the money on the card; an amount above the total is refused | | `--per-day` / `--per-week` / `--per-month` | Rolling caps, shared across cards under the same preset | | `--only-categories` | `Strict` categories, comma-separated: `meals`, `groceries`, `travel`, `software`, `ai`, `wellness`, `retail` | | `--watch-categories` | The same categories in `Watch` mode | | `--only-merchants` | Merchant name patterns the charge must match, comma-separated | | `--only-in` | Countries, regions, and US states; see [Restrict where the merchant is](#restrict-where-the-merchant-is) | | `--only-currencies` | `Strict` purchase currencies, comma-separated, by code or common name: `usd,eur` or `dollars,euros`; see [Choose the currencies](#choose-the-currencies) | | `--watch-currencies` | The same currencies in `Watch` mode: a purchase in another currency is allowed, and you are told | | `--only-days` | `mon,tue`, or `weekdays` / `weekends` | | `--only-hours` | For example `9-17`, 24-hour clock. UTC without `--timezone` | | `--timezone` | IANA zone for `--only-days` / `--only-hours`, default `UTC` | | `--only-from` | `cli`, `mcp`, `api`, and/or `browser` | Over MCP the same rules are fields on [`save_preset`](/tools/mcp/user/save_preset): `total`, `per_day`, `only_categories`, and so on. Over the API, `POST /me/presets` takes the same snake\_case fields. ### Pick categories `meals` means restaurants and food places Agentcard recognizes, from the merchant's category code and common names. `meals` is not every café on earth. A café Agentcard does not recognize falls under your `Strict` rule: the purchase is refused and you are told why. Allow the café once with `agent-cards cards preset allow-merchant "ODD CAFE"` and the retry goes through. Under a `Watch` rule the same charge is allowed, the card stays open, and you are told. Either way the next step is the same: allow that merchant once with `allow-merchant`, and the next charge there goes through quietly. `software` covers SaaS, developer tools, and hosting. `ai` means the merchant's name is an AI vendor: OpenAI, ChatGPT, Anthropic, Claude, Gemini, or Google AI. When the network reports a merchant category code, it must be one an AI vendor bills under, so a bakery named after a product does not match. The older name `software_ai` still works and means both. ### Choose `Strict` or `Watch` Every category rule is `Strict` unless you ask for `Watch`: ```bash theme={null} agent-cards cards create --amount 40 --watch-categories meals -y ``` `Strict` refuses an off-category purchase and tells you why. `Watch` lets it through and tells you. When a `Strict` charge settles anyway on a multi-use card, Agentcard pauses the card and tells you. The charge itself has already been paid; the pause stops the next one. The card shows as `pausing` until the card network confirms, then as `paused`, and your notice arrives at that confirmation. A single-use card spent by a charge shows as `closing` until the network confirms, then `closed`. Use `Watch` while you learn which merchants a category really covers. Switch to `Strict` once the notifications go quiet. | Mode | Any category | Currency | Spend, place, time, `--only-from`, `--only-merchants` | | ---------------------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------ | ----------------------------------------------------- | | **`Strict`** (default) | The purchase is refused and you are told why. After settlement on a multi-use card: paused and you are told | `--only-currencies`: the same | Always `Strict` | | **`Watch`** (`--watch-categories`) | Allowed, and you are told. No pause | `--watch-currencies`: the same | Not available; stays `Strict` | One rule for every category: `software` and `ai` run `Watch` exactly as `meals` does. The currency rule makes its own choice, so a preset can watch `software` and still refuse a purchase in another currency; see [Choose the currencies](#choose-the-currencies). Where each mode is enforced matters once the card is used outside Agentcard checkout. With a `Strict` category the card network itself declines an off-category charge wherever the card is used. With a `Watch` category, or once you have allowed a merchant on the card, only Agentcard checks the category, at checkout and after settlement, so a charge made straight at a merchant goes through and you are told afterwards. The create output in the CLI and the MCP tools says which of the two your card has. A multi-use card with a `Strict` category cannot be created today. Ask for one and the create is refused: ```text theme={null} Error: strict_category_multi_use_unsupported: Multi-use cards with a strict category rule are not available yet: the card network closes a category-restricted card after its first approved charge. Create a single-use card, use Watch (--watch-categories) for a multi-use card, or drop the category rule. ``` The reason is the card network. When we hand it a category restriction, it puts the card on a product that cancels the card after its first approved charge, while our records would still say the card is open. Rather than ship a card that lies about itself, we refuse to create it. Use a single-use card for a strict rule, or `Watch` for a multi-use one; `Watch` pushes nothing to the network, so Agentcard alone checks it at checkout and at settlement and the card stays open. The AI card, `ai_labs`, is no longer an exception for new cards. Until 2026-10-08 a multi-use `ai_labs` card can still be created, and its create response carries a notice saying so; from that date it is refused like any other `Strict` category. Cards already created keep working. For a multi-use AI card use `--watch-categories software,ai`; for a strict one, create it single-use. Either way the card keeps the boosted tokenback rate on charges at software and AI vendors; other charges on it earn the normal rate. When `Watch` tells you about a charge, you have two choices: 1. **Keep watching.** Do nothing. The next odd match tells you again. 2. **Remember.** Run `allow-merchant` so future charges at that name pass the category and merchant rules quietly. `weekday_meals` is `Strict`. Save a `Watch` variant if you want the softer loop: ```bash theme={null} agent-cards cards preset save weekday_meals_watch \ --watch-categories meals \ --only-days weekdays \ --only-hours 11-14 \ --timezone America/Los_Angeles ``` A preset takes `--only-categories` or `--watch-categories`, not both. Two category rules on one card intersect, so the `Strict` one would refuse every merchant the `Watch` one meant to allow, and the `Watch` rule would do nothing. The save is refused. Save two presets if you need both behaviors. Inline JSON and the API take the same choice as a field: `{ "kind": "category", "categories": ["meals"], "enforcement": "watch" }`. Omit `enforcement`, or pass `"strict"`, for refuse and pause. ### Remember a merchant ```bash theme={null} agent-cards cards preset allow-merchant ODDCAFE agent-cards cards preset allow-merchant account ODDCAFE ``` **Allow the merchant for one card.** This is the default. From now on your agent can buy from that merchant with this card through Agentcard checkout. Your other cards do not change. One exception. If this card was created with `Strict` categories, the card network still enforces the category lock it was given when the card was made, and we cannot widen it afterwards. So a purchase made directly at that merchant, outside Agentcard checkout, can still be declined by the network. When that applies, the response tells you. If you need both to work, create a new card from the same preset; a new card allows the merchant everywhere. **Allow the merchant for your whole account.** Every card you create from now on allows that merchant. Cards you already have keep working exactly as they do today. Over MCP, call [`allow_card_merchant`](/tools/mcp/user/allow_card_merchant) with `pattern` and `card_id`, or with `scope: "account"`. Over the API, `POST /cards/:id/preset/allow-merchant` or `POST /me/preset/allow-merchant` with `{ "pattern": "ODDCAFE" }`. A pattern is a case-insensitive substring of the merchant's name as the card network reports it, as with `--only-merchants`: `starbucks` matches `STARBUCKS #123`. A remembered merchant leaves the rest of the preset in place. Spend, place, currency, time, and `--only-from` rules still apply. A merchant can show up under two names. At Agentcard checkout it is `AMAZON`. On your card statement, which is what the card network reports, it is `AMZN MKTP US`. If you allowed the first name, a charge under the second can still pause a `Strict` card. When that happens, allow the name from the pause notice too. Both can live on the same preset. ### Save rules under a name Save a name you already use and your change applies to the cards you create from now on. Cards you already have keep the rules they were created with. ```bash theme={null} agent-cards cards preset save lunch --per-day 30 --only-categories meals # → Updated lunch. Cards already using the old version keep it; new cards get this one. ``` A card you create from a saved name keeps the rules it was created with, even if you change the name later. The card's own amount is its spending limit at the network, and changing one card never touches another. Shared caps count together: a per-day, per-week, or per-month cap counts every card created from that name in one window, and keeps counting after you allow a merchant. Cards created from the same built-in, `daily` for example, share one window too. The total is always per card. Over MCP: [`list_presets`](/tools/mcp/user/list_presets), [`save_preset`](/tools/mcp/user/save_preset), [`delete_preset`](/tools/mcp/user/delete_preset). Over the API: `GET` and `POST /me/presets`, and `DELETE /me/presets/:name`. ## Set a default, change a card Set your account default and every card you create from now on follows it, unless you pass rules on the create call or the app has its own default. Point an existing card at a saved name to change what that card may do from now on. ```bash theme={null} agent-cards cards preset --set daily # account default agent-cards cards preset --set lunch # change one card's rules ``` Over MCP, [`set_card_preset`](/tools/mcp/user/set_card_preset) does both and also takes inline rules. When you change a card's rules, Agentcard updates the card's network limit when the network allows it, and the response says what Agentcard now enforces on its own and when the change needs a new card. ## Set a default for one app Give the CLI, or one connected app, a standing preset. New cards created from there inherit it when the create call passes no `--preset` and no rule flags. ```bash theme={null} agent-cards cards preset --for cli --set daily agent-cards cards preset --for "My App" --set lunch agent-cards cards preset --for list # every app and whether it has a preset agent-cards cards preset --for cli --clear ``` `--for` matches a connected app's name in any case. `cli` is reserved for the command line. The `cli` default applies to cards the CLI creates and purchases the CLI makes, not to the dashboard or a Slack conversation, which inherit the account default. If two connections share a name, Agentcard lists both with connect date and id; pass the id instead. Over MCP, pass `for_app` on [`get_card_preset`](/tools/mcp/user/get_card_preset) and [`set_card_preset`](/tools/mcp/user/set_card_preset). Account-scope `allow_card_merchant` updates the account default, not an app default. ## Restrict where the merchant is Say where the merchant may be: ```bash theme={null} agent-cards cards create --amount 50 --only-in 'US, Canada' -y ``` A purchase from a merchant anywhere else is refused, and you are told why. The rule is about the merchant's location, not where your agent runs, and there is no "within N miles of a place" rule. Write a country by name or by its two-letter code: `US`, `Canada`, `Mexico`, `FR`, `JP`. Write a US state by full name or with its country: `California`, `US-CA`. Write a region by name, in any case, with spaces or hyphens: `europe`, `north-america`. A region expands to its countries when the rule is saved, and the card's summary shows what you typed: `Location: Europe, Canada`. A code that is both a country and a US state is refused, so you can pick: ```text theme={null} CA could be Canada or California. Write Canada, or US-CA. ``` The regions: `eu` is the 27 member states; `eea` adds Iceland, Liechtenstein, and Norway; `europe` is geographic Europe, the EEA plus the UK, Switzerland, and the other non-EU European states, without Russia or Turkey, which you name to add; then `nordics`, `benelux`, `dach`, `north-america`, `central-america`, `caribbean`, `south-america`, `latin-america`, `middle-east`, `africa`, `asia`, `oceania`, and `apac`. A state next to a region narrows only the US: `north-america,US-CA` allows any Canadian or Mexican merchant and only Californian US merchants. ```bash theme={null} agent-cards cards create --amount 50 --only-in 'europe, Canada' -y agent-cards cards preset save west-coast --only-in 'California, Oregon, Washington' ``` Agentcard checks the place at checkout and, when the card network reports the merchant's country, after settlement. A settlement from a place the rule refuses pauses a multi-use card and you are told. A settlement that arrives without a location is not a violation. At Agentcard checkout the rule judges the country of the order. A merchant that operates in one country is that country. A merchant that operates in several, Uber Eats, Sephora, Walmart, and TaskRabbit today, gives the checkout nothing to judge until it knows the order's country. When the country is unknown, the purchase is refused and you are told why, with `geo_unknown` as the reason, rather than guessing and letting a purchase through in a country you excluded. ## Choose the currencies Say which currencies your agent may pay in: ```bash theme={null} agent-cards cards create --amount 40 --only-currencies usd,eur ``` A charge in any other currency is refused, and you are told why. Write a code or a plain name, in any case: `usd`, `EUR`, `dollars`, `euros`, `yen`. `dollars` means US dollars and `pounds` means British pounds. For any other dollar, pound, or peso, add the country: `canadian dollars`, `mexican pesos`. Some names mean more than one currency. If you write `pesos`, the save is refused and the message lists what it could mean, so you can pick: ```text theme={null} "pesos" could be MXN, ARS, CLP, COP, or PHP. Write the currency code, or name the country (Mexican pesos). ``` The same goes for francs, krona, krone, rupees, riyals, rials, dirhams, dinars, and shillings. A code that is not a currency, such as `ZZZ`, is refused the same way. A rule is saved only when Agentcard can check it. This rule is about the money, not the place. A merchant in Paris that charges in dollars passes a `usd` rule. To restrict where the merchant is, use `--only-in`. If you would rather be told than refused, use `--watch-currencies` with the same list. The charge goes through and you are told. A preset takes one of the two, not both. The card summary shows what you allowed: `Currency: USD, EUR`, or `Currency: USD (watch)`. Under it, the create output in the CLI and the MCP tools adds one line: Agentcard enforces the currency rule at checkout and settlement; the card network does not. Agentcard checks this rule; the card network does not. At Agentcard checkout, a purchase in another currency is refused before the merchant sees the card, with `currency_denied` as the reason. A card used straight at a merchant is checked when the charge settles. If a charge in another currency settles anyway on a multi-use card, Agentcard pauses the card and tells you. The card shows as `pausing` until the card network confirms, then `paused`, and your notice arrives at that confirmation. A single-use card closes after its first charge as usual, and the violation is recorded. With `--watch-currencies`, the charge is allowed and you are told. Sometimes Agentcard cannot tell the currency. At checkout, a `Strict` rule then refuses the purchase with `currency_unknown`, and a `Watch` rule lets it through and tells you. A settlement that arrives without a currency is not a violation. A charge is judged once, in the currency it was authorized in. If it later settles in another currency, you get a notice and nothing else changes: the card is not paused. Only a card with a currency rule gets that notice: ```text theme={null} This charge was authorized in USD and settled in EUR. This card's preset restricts currency, so you are being told; the card was judged on USD and stays as it is. ``` A currency pause is not about the merchant, so there is no merchant to allow. The notice names the charge's currency and the allowed ones, and carries the commands that put the new currency on the card: save a preset with both currencies, set it on the card, resume. ## Read a refusal, take a next step When your agent asks for the card details or tries to pay, the refusal tells you which rule stopped it, what the card allows, and what to do next. Category and merchant refusals include the command that allows the merchant. ### Recover from a `Strict` refusal 1. Read the refusal, or the pause notice. Both arrive by the same email and alerts as your other card notifications. 2. Remember the merchant. The message suggests a pattern. ```bash theme={null} agent-cards cards preset allow-merchant cmtt4mw7s001fbr8zeel9tzse ODDCAFE # MCP: allow_card_merchant { "card_id": "cmtt4mw7s001fbr8zeel9tzse", "pattern": "ODDCAFE" } ``` 3. If the card is multi-use and was paused after settlement, resume it. ```bash theme={null} agent-cards cards resume # MCP: resume_card ``` 4. Retry the purchase. The remembered merchant now goes through. Any other off-category merchant is still refused, and you are told why. ### `Watch`: keep watching or remember `Watch` already let the charge through. You get a notification by the same email and alerts as your other card notifications, not a separate approval inbox. Then either do nothing and keep watching, so the next odd match tells you again, or remember the merchant so future charges at that name are quiet. `Watch` never pauses the card. `cards preset `, or `get_card_preset`, shows the active rules, remembered merchants included. Transaction history does not restate these messages. Shopping budgets set with `buy budget` are a separate control; card presets run alongside them. The card network enforces only part of this. Merchants you allowed and `Watch` categories are checked by Agentcard, at checkout and at settlement, never by the network. A `Strict` category is also enforced by the network, which declines an off-category charge even at a merchant you allowed later. ## Undo a rule | Goal | CLI | MCP / API | | ------------------------------------------ | ---------------------------------- | ------------------------------------------------------------------ | | Clear this card (remembered merchants too) | `cards preset --clear` | `set_card_preset` with `preset: null` / `DELETE /cards/:id/preset` | | Clear the account default | `cards preset --clear` | `set_card_preset` without `card_id` / `DELETE /me/preset` | | Clear an app default | `cards preset --for --clear` | `for_app` plus clear / `DELETE /me/preset?for=` | | Delete a saved name | `cards preset delete ` | `delete_preset` / `DELETE /me/presets/:name` | Clear a preset and Agentcard stops checking that card, allowed merchants included. A spending limit the card network already holds stays until you create a new card. Standing defaults and saved names belong to you as the account owner. A connected app gets `403 read_only` when it tries to change or clear a card's preset, set or clear the account or an app default, or delete a saved name. The app can still read presets, save new names, and allow a merchant; for anything else it should ask you to make the change from the CLI or dashboard. Delete a saved name and you can no longer create cards from it; cards you already have keep working as they do today. The delete is refused while the name is still your account default or an app default. Clear that first. ## Try an example ```bash theme={null} agent-cards cards create --amount 50 --preset weekday_meals -y agent-cards cards create --amount 40 --only-categories ai --only-from mcp -y agent-cards cards create --amount 40 --watch-categories meals -y agent-cards cards create --amount 50 --only-currencies usd,eur -y agent-cards cards preset --set daily agent-cards cards preset --for cli --set cli_only agent-cards cards preset --set lunch agent-cards cards preset allow-merchant ODDCAFE agent-cards cards preset --clear ``` ### Read a refusal Each example below is what you actually see, copied from a real run. The examples are grouped by what your agent was doing: creating a card, asking for its details, paying a merchant directly, or saving a rule Agentcard cannot check. The notices you receive come last. **Creating a card the network cannot support.** From the CLI, `agent-cards cards create --amount 40 --only-categories meals --multi-use -y` is refused before any card is issued: ```text theme={null} Error: strict_category_multi_use_unsupported: Multi-use cards with a strict category rule are not available yet: the card network closes a category-restricted card after its first approved charge. Create a single-use card, use Watch (--watch-categories) for a multi-use card, or drop the category rule. ``` Over MCP, `create_card` with `scope_preset: "ai_labs"` and `type: "single_use"` answers with a tool error. The reason is in `structuredContent.status`: ```json theme={null} { "content": [ { "type": "text", "text": "Scoped (AI) cards are always multi-use — omit type or pass multi_use." } ], "structuredContent": { "message": "Scoped (AI) cards are always multi-use — omit type or pass multi_use.", "status": "scope_preset_requires_multi_use" }, "isError": true } ``` **Creating a card the network will not check.** `agent-cards cards create --amount 40 --watch-categories meals --multi-use -y` goes through. The `Network` line says that Agentcard, not the card network, checks the category: ```text theme={null} Multi-use card with rules This card stays open across charges until its limit is spent — good for subscriptions. - Creating card... ✔ Virtual card issued! Card •••• 0109 Expires 09/28 Balance $40.00 ID cmtta6yaj000nbrknctlehc1l Preset Categories: Meals & restaurants (watch). Network no category allowlist on this card — Agentcard checks at checkout and settlement Run: agent-cards cards details cmtta6yaj000nbrknctlehc1l # to see full PAN/CVV The card draws on your balance when used. It stays open until its limit is spent. Manage it with `agent-cards cards pause/resume`. ``` **Creating a multi-use `ai_labs` card before 2026-10-08.** `agent-cards cards create --amount 40 --preset ai_labs --multi-use -y` goes through and carries a notice: ```text theme={null} Multi-use card with preset Preset: ai_labs This card stays open across charges until its limit is spent — good for subscriptions. - Creating card... ✔ Virtual card issued! Card •••• 4454 Expires 09/28 Balance $40.00 ID cmtta6zne000ubrknm8imiu5n Preset Categories: Software, AI vendors. Rewarded merchants: OPENAI, CHATGPT, ANTHROPIC, CLAUDE, GEMINI, GOOGLE AI. Notice From 2026-10-08 a reusable card with a Strict category can no longer be created, this AI card included: the card network cancels such a card after its first approved charge. Cards already created keep working. For a reusable AI card after that date use --watch-categories software,ai (Watch); for a strict one, create a single-use card. Run: agent-cards cards details cmtta6zne000ubrknm8imiu5n # to see full PAN/CVV The card draws on your balance when used. It stays open until its limit is spent. Manage it with `agent-cards cards pause/resume`. ``` **Asking for card details from the wrong place.** A card was created with `--only-from cli`. A connected app asks for its details, and a connected app always counts as `mcp`. `agent-cards cards details cmtta98lz001tbrkn055mqx6a` answers: ```text theme={null} Error: policy_denied: This card is CLI-only. Run the purchase from the CLI, or change the preset with `cards preset` (or `cards preset --set …` for one card). ``` **Paying a merchant directly, over the daily cap.** Your agent used a multi-use card with `--per-day 20` to pay \$25 at a merchant, outside Agentcard checkout. Agentcard cannot stop that charge, because the merchant never asked us. It finds out when the charge settles. Then it pauses the card and tells you. In the sandbox you play the merchant with a test charge; its answer shows the card's status afterwards in `card.status`, and the pause notice below arrives as it would live. A place rule works the same way. The reason is `geo_denied` when the merchant is somewhere the rule excludes, and `geo_unknown` when Agentcard cannot tell where the order is. **Paying a merchant directly, in another currency.** Your agent paid \$12.50 in euros at a café, directly, with a card that allows only `usd`. When the charge settled, Agentcard paused the card and told you. In the sandbox the test charge's answer shows `card.status` as `PAUSED`. In the sandbox the network confirms at once, so the card never shows `pausing` here. A live card does, until the network answers. The same charge on a card with `--watch-currencies usd` goes through, and the card stays open. **Saving a rule Agentcard cannot check.** From the CLI, `agent-cards cards create --amount 20 --only-currencies pesos -y` is refused before any card is issued: ```text theme={null} Error: policy_invalid: "pesos" could be MXN, ARS, CLP, COP, or PHP. Write the currency code, or name the country (Mexican pesos). ``` `agent-cards cards preset save euro-zone --only-currencies pesos` prints the message alone. With `--json` it prints one line instead: ```text theme={null} {"ok":false,"error":"policy_invalid","message":"\"pesos\" could be MXN, ARS, CLP, COP, or PHP. Write the currency code, or name the country (Mexican pesos)."} ``` Over MCP, `save_preset` with an unknown category answers with a tool error: ```json theme={null} { "content": [ { "type": "text", "text": "Unknown category \"crypto\". Use meals, groceries, travel, software, ai, wellness, or retail." } ], "structuredContent": { "message": "Unknown category \"crypto\". Use meals, groceries, travel, software, ai, wellness, or retail.", "status": "policy_invalid" }, "isError": true } ``` `save_preset` with `"only_currencies": "pesos"` answers the same way: ```json theme={null} { "content": [ { "type": "text", "text": "\"pesos\" could be MXN, ARS, CLP, COP, or PHP. Write the currency code, or name the country (Mexican pesos)." } ], "structuredContent": { "message": "\"pesos\" could be MXN, ARS, CLP, COP, or PHP. Write the currency code, or name the country (Mexican pesos).", "status": "policy_invalid" }, "isError": true } ``` Over the API, `POST /me/presets` with `{"name":"weekend-crypto","only_categories":"crypto"}` answers HTTP 400: ```json theme={null} {"error":"policy_invalid","message":"Unknown category \"crypto\". Use meals, groceries, travel, software, ai, wellness, or retail."} ``` `POST /me/presets` with `{"name":"euro-zone","only_currencies":"pesos"}` answers HTTP 400 too, and `POST /cards/create` with `{"amountCents":2000,"only_currencies":"ZZZ"}` names the code: ```json theme={null} {"error":"policy_invalid","message":"\"pesos\" could be MXN, ARS, CLP, COP, or PHP. Write the currency code, or name the country (Mexican pesos)."} {"error":"policy_invalid","message":"ZZZ is not a currency code. Use an ISO 4217 code (USD, EUR, GBP, JPY) or a common name (dollars, euros, pounds, yen)."} ``` **What the notice says.** For a \$5.00 charge at GROCERY MART, by email or, with no email on file, on your iMessage thread: ```text theme={null} --- paused, email text A $5.00 charge at GROCERY MART is outside the preset on your card ending in 4242; the card is paused. Category denied: this preset allows Software, AI only. To allow this merchant and get going again, run: agent-cards cards preset allow-merchant cmtta6zne000ubrknm8imiu5n "GROCERY MART" agent-cards cards resume cmtta6zne000ubrknm8imiu5n --- paused, iMessage ⏸ $5.00 at GROCERY MART paused your card ending in 4242 (outside its preset). To allow this merchant and resume: agent-cards cards preset allow-merchant cmtta6zne000ubrknm8imiu5n "GROCERY MART" agent-cards cards resume cmtta6zne000ubrknm8imiu5n --- watched, email text A $5.00 charge at GROCERY MART on your card ending in 4242 was allowed but is outside the preset's watched categories. To allow this merchant and stop these notices, run: agent-cards cards preset allow-merchant cmtta6yaj000nbrknctlehc1l "GROCERY MART" --- watched, iMessage 👀 $5.00 at GROCERY MART on your card ending in 4242 went through but is outside the categories it watches. To allow this merchant: agent-cards cards preset allow-merchant cmtta6yaj000nbrknctlehc1l "GROCERY MART" ``` **What the notice says for a currency rule.** For a \$12.50 charge in euros at CAFE DE PARIS: on a card with `--only-currencies usd`, on one with `--watch-currencies usd`, and on one whose charge was authorized in dollars and settled in euros. Sandbox charges send no notices, so each text below was produced from the product's own notice wording with the values from these settlements: ```text theme={null} --- paused, email text A $12.50 charge at CAFE DE PARIS was made in EUR. This card's preset allows purchases in USD only, so the card ending in 2799 is paused. To allow EUR on this card and get going again, save a preset with the currencies you want, put it on the card, and resume it: agent-cards cards preset save usd-eur --only-currencies usd,eur agent-cards cards preset cmttneff4000cjpj64zb1kckl --set usd-eur agent-cards cards resume cmttneff4000cjpj64zb1kckl To be told instead of paused next time, save the preset with --watch-currencies usd instead. --- paused, iMessage ⏸ $12.50 at CAFE DE PARIS was made in EUR; your card ending in 2799 allows USD only, so it is paused. To allow EUR on this card and resume: agent-cards cards preset save usd-eur --only-currencies usd,eur agent-cards cards preset cmttneff4000cjpj64zb1kckl --set usd-eur agent-cards cards resume cmttneff4000cjpj64zb1kckl Or save the preset with --watch-currencies usd to be told instead of paused. --- watched, email text A $12.50 charge at CAFE DE PARIS was made in EUR and went through. This card's preset watches purchases in USD, so you are being told; nothing is blocked. To allow EUR on this card and stop these notices, save a preset with the currencies you want and put it on the card: agent-cards cards preset save usd-eur --only-currencies usd,eur agent-cards cards preset cmttneg9f000jjpj6nhumquby --set usd-eur --- watched, iMessage 👀 $12.50 at CAFE DE PARIS was made in EUR and went through; your card ending in 2283 watches USD. Nothing is blocked. To allow EUR on this card: agent-cards cards preset save usd-eur --only-currencies usd,eur agent-cards cards preset cmttneg9f000jjpj6nhumquby --set usd-eur --- settled in another currency, email text A $12.50 charge at CAFE DE PARIS on your card ending in 8573 settled in a different currency than it was authorized in. Nothing is blocked and the card is not paused. This charge was authorized in USD and settled in EUR. This card's preset restricts currency, so you are being told; the card was judged on USD and stays as it is. ``` The three commands in a paused notice put the charge's currency on the card: save a preset with both currencies, set it on the card, resume. A watched notice carries the first two. Both name `--watch-currencies` as the way to be told instead of paused. ### Look up a refusal code | Code | Where | What it means | What to do next | | --------------------------------------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `strict_category_multi_use_unsupported` | create, HTTP 400 | A multi-use card with a `Strict` category; the card network would cancel it after its first charge | Create it single-use, or use `--watch-categories` for a multi-use card | | `scope_preset_requires_multi_use` | create, HTTP 400 | `scope_preset: ai_labs` together with `type: single_use` | Omit `type`, or pass `multi_use`; prefer `preset` | | `policy_invalid` | create, save, set; HTTP 400 | The rules do not parse: an unknown category, an ambiguous place code, an ambiguous or unknown currency, a misspelled zone, `--preset` next to rule flags, or both modes of a category or currency rule at once | The message names the field; correct it and retry | | `policy_denied` | card details, HTTP 403 | The card's `--only-from` or time rule refuses the request for the card's details | Use the CLI, MCP tool, API, or dashboard the rule allows, or the allowed window, or change the card's rules with `cards preset --set` | | `policy_update_failed` | set, HTTP 409 | The card's rules changed under you, or the network refused the new limit | Read the card's rules again and retry | | `limit_exceeds_preset_total` | create, set-limit; HTTP 400 | An amount or a new limit above the total the preset allows | Ask for less, or raise the total | | `pending_card_mismatch` | create retry, HTTP 400 | The retry did not match the approval it was waiting on | Retry with the values from the earlier `approval_pending` answer | | `read_only` | set, delete, account-scope remember; HTTP 403 | A connected app tried to change the owner's defaults or delete a saved name | The owner makes the change from the CLI or dashboard | | `ai_cards_disabled` | create, HTTP 400 | The AI card is switched off for this account | Use another preset | | `category_denied` | checkout, settlement | The merchant's category is outside a `Strict` category rule | Allow the merchant once with `allow-merchant`; resume a paused card; retry | | `category_unknown` | checkout, settlement | The charge came with no category and the merchant's name is not one Agentcard knows | Allow the merchant once, or use a merchant Agentcard recognizes | | `merchant_denied` | checkout, settlement | The merchant's name matches none of the names the rule allows | Allow the merchant once, or widen the rule | | `merchant_unknown` | checkout | The merchant is unknown and the rule needs one | Retry with a named merchant | | `spend_total_exceeded` | checkout, settlement | The charge would take the card past its total | Create a card with a higher total | | `spend_rate_exceeded` | checkout, settlement | The charge would take the shared window past its cap | Wait for the window to roll, or save the preset again with a higher rate | | `spend_rate_unknown` | checkout | Agentcard could not check how much this preset has spent, so it refused rather than guess | Try again | | `geo_denied` | checkout, settlement | The merchant is outside the places the rule allows | Use a merchant in an allowed place, or widen the rule | | `geo_unknown` | checkout | The merchant operates in several countries and the order's country is unknown | Use a single-country merchant, or a checkout that supplies the order's country | | `currency_denied` | checkout, settlement | The purchase is in a currency outside a `Strict` currency rule | Buy in an allowed currency, or change the preset with `cards preset --set`; resume a paused card | | `currency_unknown` | checkout | Agentcard cannot tell the currency of the purchase and the rule is `Strict` | Use a checkout that states its currency, or switch to `--watch-currencies` | | `surface_denied` | card details, checkout | The request came from a place the `--only-from` rule excludes | Run it from the CLI, an MCP tool, the API, or the dashboard, whichever the rule allows | | `surface_unknown` | card details, checkout | Agentcard cannot tell whether the CLI, an MCP tool, the API, or the dashboard is asking | Use a signed-in CLI, a connected app, or an API key | | `time_window_denied` | card details, checkout, settlement | Outside the allowed days or hours, in the rule's zone | Retry inside the window, or change the window |