> ## 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.
# Quickstart
> Go from sign-up to an agent that completes its first checkout, in about 15 minutes.
Set up your vault, connect an agent, and run a practice checkout where the agent
handles only tokens and your card is never typed. It takes about 15 minutes.
You need a payment card and an MCP-capable agent, such as one of the
[supported agents](/agents/overview). If you write your own agent in TypeScript,
follow [Install the SDK](/sdk/install) for the connect step instead.
Free accounts include **5 payments per rolling 30 days**. A payment counts once
the proxy types your card number into a page, so a fill refused before that costs
nothing. A fill that fails after the number reached the page can still count. The
practice checkout below fills a test card, so it never counts. See
[Billing](/dashboard/billing).
## Set up your vault, about 5 minutes
Open [https://app.agentvault.io](https://app.agentvault.io) and sign in with your
email address. Your account is created on first sign-in.
In the sidebar, under **Vault**, click **Cards**, then **Add card**.
The number field is a secure frame from our card vault, so your number never
reaches the Agent Vault backend. The security code (CVV) is never stored. See [CVV policy](/security/cvv-policy).
Under **Vault**, click **Addresses** and add an address labelled `ship`. The
billing address from your card is already saved here as `card1` or similar.
Rename it before your agent first reads its tokens: renaming later replaces them.
Your agent cannot see which address belongs to which card, so tell it the label
of your card's billing address.
Under **Vault**, click **Identity** and enter your name, email and phone number. Almost every
checkout asks for all three.
Under **Workspace**, click **Agent cards**. Adding your first card created
**Default agent card**, a set of spending rules on top of your card:
| Limit | Starter value |
| - | - |
| Per transaction | \$75 |
| Per week | \$200 |
| Per rolling 30 days | \$500 |
| Per day | \$100 (Plus and Enterprise only) |
These are fine for a first run. Change them later on [Agent cards](/dashboard/agent-cards).
Your vault is ready, and your first card has limits before any agent touches it.
Only your first card gets limits automatically. A card you add later shows **No
limits**: click **Add limits** on it before an agent uses it.
## Connect your agent, about 5 minutes
**Using a supported agent?** If **Overview** shows a **Sign in** option under
**Your agent framework**, you need no API key or local install:
1. Follow [Connect to the hosted server](/mcp/setup#connect-to-the-hosted-server)
to add the server and sign in.
2. Ask your agent to call `get_token_catalog`. It is refused until you choose
access.
3. Under **Vault**, click **Connected apps**, then **Choose access** on the new
row. Pick the cards, tick **Fill a test card instead of my card**, and click
**Save access**.
4. Skip to [Run your first checkout](#run-your-first-checkout-about-5-minutes).
The steps below set up the local MCP server, which uses an API key.
Under **Vault**, click **API keys**, then **New key**. Name it `practice`.
Leave the other defaults, but under **Verification** tick **Fill a test card
instead of my card**. Then click **Create key**.
With that box ticked, the proxy types a public Visa test card and test security
code wherever your agent fills your card tokens. Your real card is never typed.
Test-card fills count against no limit and raise no card, limit or pause alert.
The first-connection alert and new-site approval still apply. See
[Fill a test card instead](/dashboard/api-keys#fill-a-test-card-instead).
Never run the practice checkout with a key that fills your real card. The
practice page is not a payment page, and on preview and development deployments
it keeps what it receives.
The key starts with `av_` and is shown **only once**. Store it like a password.
Go to **Overview**. Under **Your agent framework**, pick your agent, then click
**Copy agent instructions**. The block has your deployment's addresses, and your
key if you created it in this browser session. Otherwise, paste your key over
the placeholder.
For an MCP client, the server entry looks like this:
```json theme={null}
{
"mcpServers": {
"agent-vault": {
"command": "npx",
"args": ["-y", "--allow-remote=all", "https://app.agentvault.io/mcp/agentvault-mcp.tgz"],
"env": {
"SELF_AGENT_PAY_API_KEY": "av_...",
"SELF_AGENT_PAY_PROXY_URL": "wss://proxy.agentvault.io/v1",
"SELF_AGENT_PAY_API_URL": "https://api.agentvault.io"
}
}
}
}
```
npm 12 refuses to fetch a package from a URL unless `--allow-remote=all` comes before the URL, so the args include it. npm 11 accepts it with an "Unknown cli config" warning.
On a self-hosted Agent Vault, copy the block from your dashboard instead: it
fills in your deployment's addresses.
Use your user-level configuration, not a project file you commit, because the
block contains your live key. Per-client paths are on [MCP setup](/mcp/setup).
Your MCP client loads the Agent Vault server on start.
It returns your tokens with the card brand and last four digits. It contains no
card number, security code or password. It does not count as a payment.
An `invalid_api_key` error means the key is wrong or revoked. Other connection
failures are on [Troubleshooting](/reference/troubleshooting#setup-and-connection).
Your agent is connected. It can see your vault as tokens, and nothing more.
## Run your first checkout, about 5 minutes
The practice checkout is at
[https://app.agentvault.io/demo-checkout](https://app.agentvault.io/demo-checkout).
It shows a \$20.00 order and charges nothing. Connect with the `practice` key, or
a hosted connection with **Fill a test card instead of my card** ticked. Ask your
agent:
> Using Agent Vault, check out at [https://app.agentvault.io/demo-checkout](https://app.agentvault.io/demo-checkout) and
> confirm the order went through.
The agent fills your name, address and card with tokens, submits, and checks
the result with `get_session_outcome`. The card fill reply should carry a
`card_fields_verified` note, confirming the test card went in instead of yours.
If it does not, stop. Check that the key's **Access** column on **API keys** reads
**Test card only**, or that the connection's row on **Connected apps** shows
**Test card**.
The practice checkout receives your real name and address. On the production
service it keeps nothing. On a preview or development deployment it keeps:
* The latest submission, in memory.
* For a run tagged for automated testing, a card-free summary with your name
and address, for about a day.
* Your name, street and the card's last four digits in the web server's log.
None of this is linked to your account, so deleting your account does not
remove it. See
[The practice checkout](/dashboard/data-and-deletion#the-practice-checkout).
The first fill on a site you have not approved pauses, and a banner reads **A
new site is waiting for your approval**. Click **Approve** within about 15
minutes, or the fill is refused. See [Destinations](/dashboard/destinations).
Under **Workspace**, click **Activity**. Open the session to see the site, the
kinds of fields filled, any refusals, and the outcome. Recording is best effort,
so an event that failed to save is missing, not retried.
Your agent completed a checkout, and the only card data it ever held was a token.
Before a real purchase, use a key without **Fill a test card instead of my
card**. On the hosted MCP server, click **Change access** on the connection's row
on **Connected apps** and clear that box. Then start a new session: an open one
keeps filling the test card. New fills type your real card and count against
your limits.
A real checkout can also pause for a
[purchase approval](/dashboard/approvals-and-notifications) or, on a deployment
with live security code entry, a [live security code](/guides/live-cvv).
## Next steps
Spending caps, merchant rules, approval thresholds and auto-pause.
Cookie banners, card frames, the card fill order, and submitting once.
What happens when a bank check or one-time code appears.
Every refusal, what it means, and whether to retry.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.