> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentvault.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Agent cards
> Set how much each agent can spend, where it can pay, and which purchases need your approval.
Set how much each agent can spend, where it can pay, and which purchases it
must ask you about. In the sidebar, under **Workspace**, click **Agent cards**.
Creating one takes about 3 minutes.
An agent card is a set of rules on one of your [cards](/dashboard/cards), its
funding card (**Underlying card**). The rules are checked every time an agent
tries to fill it.
## Create an agent card
On an empty page it reads **Create agent card**.
Name it after the agent that will use it, for example "Grocery agent".
Pick the card this agent pays with, or click **Add a new card**.
They start at the [defaults](#spending-limits). Clear a field for no limit.
The agent card's page opens. Changes there save as you make them.
Your agent can now spend with this card, within the limits you set.
Give each agent its own agent card and [API key](/dashboard/api-keys), so you
can stop one agent and leave the rest running.
Free allows 1 agent card, Plus 5, and Enterprise unlimited. Only agent cards linked to
a funding card you still have count. See
[Billing](/dashboard/billing#agent-cards-allowance).
## The Default agent card
Your first card gets one named **Default agent card**, so that card is never
usable without limits. It uses the defaults below. Rename it after its agent.
Every card you add after the first starts with **No limits**: an agent can fill
it for any amount at any authorized site. On the **Cards** page, click **Add
limits** on it straight away.
## The agent card page
**Spending this period** shows spend **This week** and **This month** against
your caps. **Configuration** holds the **Name** and **Underlying card**.
Spend is counted per funding card, so agent cards that share one show the same
figure. Fills made while it had **No limits** are never counted, even after you
attach an agent card. They appear only on [Activity](/dashboard/activity).
## Spending limits
| Setting | What it limits | Default | Recommendation |
| - | - | - | - |
| **Per-transaction cap** | One purchase | \$75 | A little above your largest normal order |
| **Daily limit** | The last 24 hours. Plus and Enterprise | \$100 (none on Free) | About two orders |
| **Weekly limit** | The last 7 days | \$200 | Your normal weekly spend |
| **Monthly limit** | The last 30 days | \$500 | Your monthly budget for this agent |
Windows roll: a weekly limit frees up as old spend passes 7 days, not on Monday.
To stop spending, [pause](#pause-and-resume) rather than setting $0. A limit
must be more than $0: a \$0 or negative value is refused
(`agent_card_cap_not_enforceable`), shown on the page as **Unable to update
agent card**. There is no upper bound.
The daily, weekly and monthly limits apply on production deployments only.
Other deployments enforce only the **Per-transaction cap**. See
[Limits](/reference/limits#spending-limits).
Spending limits are in beta. A total Agent Vault cannot read is declined, but a
total read wrongly could slip past, so keep an eye on
[Activity](/dashboard/activity).
### Spend counts when the card is filled
A purchase counts the moment the card number is typed, before any order exists.
If the order is never placed, the amount still counts until it ages out, so a
few abandoned attempts can reach a limit with nothing bought. Agent Vault never
reverses it. Check your card statement for real charges.
## Merchant restrictions
**Mode** sets where this agent card may pay. The default is **Allow all**. Pick
the narrowest mode that still lets the agent do its job.
| **Mode** | Pays at | Plan |
| - | - | - |
| **Allow all** | Any site | All |
| **Blocklist** | Any site except those you list | All |
| **Allowlist only** | Only the sites you list | Enterprise |
Pick **Blocklist** or **Allowlist only**.
Type a domain such as `example.com` and click **Add**.
Click the cross on a chip to remove it. `amazon.com` covers `smile.amazon.com`,
but not `amazon.co.uk`. Sites on an active allowlist skip the
[new-site approval](/dashboard/destinations#approve-a-new-site) for all your
saved details.
If you leave Enterprise, an agent card already in **Allowlist only** mode
keeps that mode and keeps paying only at its listed sites. The list is shown but
read-only. To change it, switch **Mode** to **Allow all** or **Blocklist**, or
return to Enterprise. See [Billing](/dashboard/billing#how-plan-features-are-enforced).
## Require approval above an amount
**Require confirmation above**, under **Behavior**, makes any purchase at or
above that amount wait for your **Approve** or **Deny**. Set it to the order
size you would want to check yourself.
* Blank (the default): never asks.
* `0`: asks for every purchase.
* A negative value: saved but ignored, so it never asks.
Once set, you are also asked when the total cannot be read or confirmed. You
have about 5 minutes to answer. See
[Purchase approvals](/dashboard/approvals-and-notifications#purchase-approvals).
If the total is often unknown, add a [page hint](/guides/page-hints) rather than
raising the amount.
## Auto-pause on limit exceeded
**Auto-pause on limit exceeded** stops the agent card when a purchase would break
any limit. It is on by default. Keep it on, so you can look before the agent
tries again. With it off, a smaller cart or a new window goes straight through.
## Pause and resume
If another active agent card shares the funding card, pausing this one does
not stop the card: it stays usable under the other's limits only. To stop it,
pause every agent card on it.
Click **Pause** at the top of the agent card's page to stop its card fills, and
**Resume** to restart them.
| Status | Meaning | How it clears |
| - | - | - |
| **Active** | Working normally | |
| **Paused** | You paused it | Click **Resume** |
| **Limit** | It auto-paused after a limit | Click **Resume** |
To stop every agent at once, see [Overview](/dashboard/overview#stop-every-agent-at-once).
## What happens when…
| Situation | Your agent is told | What to do |
| - | - | - |
| A limit is reached | To stop. Not which limit, or what is left | Check [Activity](/dashboard/activity). With auto-pause on, the status is **Limit**: click **Resume**. With it off, the card stays **Active** |
| The agent card is paused | To ask you to resume | Click **Resume** |
| The site is blocked | The site is not allowed. Not which list | Edit **Merchant restrictions** |
| An approval times out | Nothing was filled. It can ask again | Answer within 5 minutes |
| You reach your plan's limit | **New agent card** is disabled: **Plan limit reached** | Click **Upgrade**, or delete one. See [Agent cards allowance](/dashboard/billing#agent-cards-allowance) |
A site is allowed if any **active** agent card on that card allows it. The
limits that apply come from every agent card that allows the site and is
**Active** or stopped at **Limit**. A **Limit** card's caps keep applying, so a
looser sibling cannot raise the limit after one denial.
An agent card you paused yourself contributes no limits and no merchant
permission. To keep a tight cap in force, lower the sibling's limits too. If the
only agent card allowing a site is paused, that site is blocked until you resume
it.
## Card tokens
**Underlying card tokens** shows the funding card's mock tokens: **Card number**,
**CVV** and the real **Expiry**. The security code (CVV) is never stored, so it
is marked **Entered live by you**: you type the real code when an agent fills
it. The tokens work only through Agent Vault, for an API key allowed to use the
card.
## Notification webhook
On Plus and Enterprise, an agent card can send its events to your own system. None is
set by default.
Type a public `https://` address and click **Save**.
Use it to check each delivery is genuine.
The test appears under **Recent deliveries**, which lists the newest 10.
Deliveries include the merchant host and ids that tie a fill to its funding
card and session, plus the amount and threshold on purchase approvals. They
never include a card number, security code,
password, 2FA secret, identity value or approval link. Payloads and verification are on
[Webhooks](/reference/webhooks#what-a-payload-contains).
## Delete an agent card
Deleting an agent card is permanent. It does not stop an agent: an open session
keeps running. If it is the funding card's only agent card, that card is left
with **No limits**, even for a checkout already running. To stop the card,
[pause](#pause-and-resume) instead, [revoke the agent's key](/dashboard/api-keys#revoke-a-key)
or [delete the card](/dashboard/cards#delete-a-card).
It is under **Danger zone**.
The agent card and its rules are removed.
If you delete the card instead, the agent card shows **No funding card** until
you pick another **Underlying card**. Until then it controls nothing and does not
use any of your plan's agent card allowance.
### Stop an agent using a card
| To stop | Do this |
| - | - |
| Card fills on one funding card, keeping your rules | [Pause](#pause-and-resume) every agent card on that funding card. One active sibling keeps the card usable |
| One agent, everywhere | [Revoke its API key](/dashboard/api-keys#revoke-a-key) |
| One card, for every agent | [Delete the funding card](/dashboard/cards#delete-a-card) |
| Every agent at once | [Pause all agents](/dashboard/overview#stop-every-agent-at-once) |
None of these takes back a value already typed into a page.
## For developers
| On the page | Field |
| - | - |
| The four limits | `perTxnCap`, `dailyLimit`, `weeklyLimit`, `monthlyLimit` |
| **Mode** and its sites | `merchantMode` (`allow_all`, `blocklist`, `allowlist`), `merchantList` |
| **Behavior** | `autoPauseOnLimit`, `confirmAbove` |
| Status | `status`: `active`, `paused` or `limit` |
| Why an approval was asked | `over_threshold`, `amount_mismatch`, `amount_unknown`, `amount_unconvertible`, `amount_unknown_strict` |
| Counters | `totalTxns`, `totalSpent`, `spentThisWeek`, `spentThisMonth`, `lastUsedAt` |
| Errors above | `limit_reached`, `card_paused`, `merchant_blocked`, `approval_timeout`, `plan_quota_reached` |
Counters count card fills, not settled charges. Webhook events and the
`X-AgentPay-Signature` header are on [Webhooks](/reference/webhooks).
**Next:** [Approvals](/dashboard/approvals-and-notifications) to make sure approval requests reach you in time.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.