Choose what to restrict
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:
Allow a refused merchant
When a category or merchant rule refuses a merchant you meant to allow, one command allows it:- The purchase is refused and you are told why.
- You run one command naming the merchant.
- The card resumes and the retry goes through.
<card-id> for you to replace. A card paused after settlement takes agent-cards cards resume <card-id> before the retry; a refusal at checkout needs nothing more.
Over MCP the same step is one tool call:
--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.
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
Combine them with commas:
cli_only,daily. To see the built-ins and your saved names together:
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.
--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:
Over MCP the same rules are fields on
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 <card-id> "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:
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.
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.
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:
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:
- Keep watching. Do nothing. The next odd match tells you again.
- Remember. Run
allow-merchantso 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:
--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
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 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.daily for example, share one window too. The total is always per card.
Over MCP: list_presets, save_preset, 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.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.
--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 and 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: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:
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.
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: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:
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:
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
- Read the refusal, or the pause notice. Both arrive by the same email and alerts as your other card notifications.
- Remember the merchant. The message suggests a pattern.
- If the card is multi-use and was paused after settlement, resume it.
- 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 <card-id>, 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
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
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:
create_card with scope_preset: "ai_labs" and type: "single_use" answers with a tool error. The reason is in structuredContent.status:
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:
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:
--only-from cli. A connected app asks for its details, and a connected app always counts as mcp. agent-cards cards details cmtta98lz001tbrkn055mqx6a answers:
--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:
agent-cards cards preset save euro-zone --only-currencies pesos prints the message alone. With --json it prints one line instead:
save_preset with an unknown category answers with a tool error:
save_preset with "only_currencies": "pesos" answers the same way:
POST /me/presets with {"name":"weekend-crypto","only_categories":"crypto"} answers HTTP 400:
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:
--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:
--watch-currencies as the way to be told instead of paused.