> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentcard.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Agentcard is for companies whose agent buys for their users. Pick one path: the opencommerce SDK (@agent-cards/commerce-sdk) gives your agent one buy tool that finds the product, builds the cart, gets the user's approval and places the order at real stores; the Agentcard SDK (@agent-cards/sdk) pays with the user's own card when your agent already shops in a browser (Browser Use, Kernel, Browserbase, Anchor or Notte); the Purchase API (POST /buy) does the same purchase flow over plain HTTP in any language; Issuing gives the agent its own card.
> Start with `npx agent-cards init` in the app's folder (Node 22 or later). No invite is needed: it creates your Agentcard account if you don't have one, installs the opencommerce SDK and puts the credentials in the env file, kept out of git. From a coding agent, run `npx agent-cards init --print --categories all --implementation tool --wallet vault --skip-install` to get the setup steps to apply yourself.
> Vault is by invitation: request it at https://agentcard.com/get-started?utm_source=docs&utm_medium=llms&utm_campaign=agent-instructions. opencommerce needs no invite.
> Never ask a user for a card number, expiry date or CVV in chat. Send them the Vault link; they add their card on Agentcard's page, and the agent never sees the number.
> Every purchase is approved by the user, with a passkey or Face ID, or by an auto-approval they granted. An approval covers one merchant and one exact total. If the total changes, ask again. When a result says the user already said yes, don't ask again.
> `init` writes PRODUCTION credentials, which place real orders, so test in sandbox first. For opencommerce, run `npx agent-cards credentials --mode sandbox` and put the two lines it prints in place of the production ones in the env file `init` wrote, because that command only prints them; sandbox then runs the whole flow against real stores and stops before payment, so no order is placed and nobody is charged. For Vault and Issuing, sandbox credentials issue test cards that no real merchant accepts; try the checkout against shop.agentcard.sh, a test store on Stripe test mode.
> Tell the user an order is placed only after Agentcard reports it placed.
> Vault is free up to 5,000 users (https://agentcard.com/pricing). opencommerce takes 1% of each completed order. Full docs in one file: https://docs.agentcard.com/llms-full.txt

# User balance

> Let a user fund their own balance with Apple Pay or Google Pay, then issue cards against it.

Let a user pay for their own cards. You verify their phone once, create a link, and the user pays in their own browser. When your company's cards are user-funded, the cards you create for that user then draw on that balance.

Every endpoint here takes your [platform token](https://docs.agentcard.com/api-reference/access-tokens/overview.md) and names the user with `user_id`. To fund cards yourself, use the [company wallet](https://docs.agentcard.com/api-reference/company-wallet/overview.md) instead.

```bash theme={null}
curl -X POST https://api.agentcard.sh/api/v2/wallet/fund \
  -H "Authorization: Bearer $ORG_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "usr_9ae8d0b84fc1008ecb42b232", "amount_cents": 5000}'
```

In production the user needs a [verified identity](https://docs.agentcard.com/api-reference/identity-verification/overview.md) first, or the request is refused with `kyc_required`. The response then carries a `checkout_url`. Send it to the user: Agentcard covers the provider fee, so send the exact amount the user should receive. Learn when the money lands from a fresh read of the [funding session](https://docs.agentcard.com/api-reference/user-balance/funding-session.md).

The first funding needs a verified phone. Without one, the request is refused:

```json theme={null}
{
  "error": {
    "code": "phone_verification_required",
    "message": "The user must verify a phone number first. Start with POST /api/v2/wallet/phone/start.",
    "docs": "https://docs.agentcard.com"
  }
}
```

[Send a phone code](https://docs.agentcard.com/api-reference/user-balance/phone-start.md), [verify it](https://docs.agentcard.com/api-reference/user-balance/phone-verify.md), then send the same request again.

In sandbox no one pays. The test money lands right away, `checkout_url` is `null`, and the phone code is always `111111`.

## Cap what leaves a user's balance

Spend limits are not open to every company yet. Until yours reaches them, all three requests answer:

```text theme={null}
HTTP 503
{
  "error": {
    "code": "wallet_limits_unavailable",
    "message": "Spend limits on a user balance are not available yet.",
    "docs": "https://docs.agentcard.com"
  }
}
```

Ask us to open them for your company. Nothing else about the user's balance changes while they are closed, and a limit already set on a user keeps holding.

Set how much can leave one user's balance in a single movement, in any 24 hours and in any 30 days:

```bash theme={null}
curl -X PUT https://api.agentcard.sh/api/v2/wallet/limits \
  -H "Authorization: Bearer $ORG_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"user_id": "usr_9ae8d0b84fc1008ecb42b232", "per_transaction_cents": 5000, "daily_cents": 20000, "monthly_cents": 100000}'
```

From then on, Agentcard counts every movement of money out of the user's balance onto their cards against those limits. Money the user adds is spendable on their cards up to what the limits leave, and nothing beyond it moves. A withdrawal is paid out of money already moved onto their cards, which counted then, so it does not count again. A purchase that is refunded stops counting.

Money past a limit waits in their balance and reaches their cards as the 24-hour and 30-day windows free up, so a user who adds `$250` under a `$100` daily limit can spend `$100` today and the rest over the next days.

The per-transaction limit is also held by the wallet provider that keeps the user's balance, which refuses a larger transfer on its own. The daily and monthly limits are held by Agentcard alone, since the wallet provider judges one transfer at a time. Read `wallet_provider_policy.status` in the [response](https://docs.agentcard.com/api-reference/user-balance/limits-get.md) to see whether the provider holds yours yet. Until it does, Agentcard never moves more in one transfer than the provider still allows, and retries every few minutes.

The limits sit on the user's balance, which is shared by every company the user is connected to. When two companies set limits on the same user, the user's balance obeys the smaller figure of each limit. Each company reads back only its own figures, and `stricter_limit_applies` tells it whether a smaller one from elsewhere holds. Your limits are removed when the user disconnects from your company.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.