> ## 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

# top_up_card

> Raise the spending limit of an open company-funded multi-use card from your company balance.

Connect to `https://mcp.agentcard.sh/mcp` with your company credential (`client_id` + `client_secret`, or the company access token).

Behavior: idempotent per `idempotency_key`.

## What it does

`top_up_card` raises the spending limit of an open company-funded multi-use card from your company balance. Agentcard keeps the existing card and its number, so the top-up does not count against the cardholder's limit on new cards.

Call it whenever your user adds money to a card they already have. If you close the card and create a new one instead, the card number changes and each new card counts against that limit, which ends in `card_limit_reached`.

Each top-up needs its own `idempotency_key`. On `funding_in_progress`, `deposit_confirming`, a timeout, a connection error or any result you are unsure of, call again with the same arguments and the same key: Agentcard returns the first attempt's result and never adds the money twice. Use a new key only for a new top-up, or after one of the other refusals below.

## Inputs

| Field | Type | Description |
| - | - | - |
| `card_id` *(required)* | string | The open multi-use card to top up |
| `amount_cents` *(required)* | number | Amount to add in cents, minimum 100 (\$1.00). 500 = \$5.00 |
| `idempotency_key` *(required)* | string | Stable key for this top-up (e.g. your deposit id) |

## Returns

| Field | Type | Description |
| - | - | - |
| `message` *(required)* | string | Human-readable outcome. |
| `status` | string | "applied", "funding\_in\_progress", or one of the refusals below. |
| `cardId` | string | The card id, present when applied. |
| `amountCents` | number | The card's new total limit in cents, present when applied. |
| `balanceCents` | number | What the card can still spend in cents, present when applied. |
| `transferId` | string | The company-wallet transfer that funded the top-up. |
| `retryAfterSeconds` | number | Present on funding\_in\_progress and deposit\_confirming: retry after this many seconds with the same key. |

## Example call

```json theme={null}
{
  "tool": "top_up_card",
  "arguments": {
    "card_id": "card_7c1d",
    "amount_cents": 500,
    "idempotency_key": "deposit-1042"
  }
}
```

The tool answers:

```json theme={null}
{
  "message": "Added $5.00 to card card_7c1d: limit is now $7.00, $7.00 left to spend. Same card number.",
  "status": "applied",
  "cardId": "card_7c1d",
  "amountCents": 700,
  "balanceCents": 700,
  "transferId": "owt_9a"
}
```

## Refusals

A refusal comes back as a `status` with a `message`, not as an error. For example, a top-up on a single-use card answers:

```json theme={null}
{
  "message": "Only multi-use cards can be topped up. Single-use cards close after their first charge. Issue a new card instead.",
  "status": "not_multi_use"
}
```

| `status` | Why | What to do |
| - | - | - |
| `idempotency_key_required` | The call had no `idempotency_key`. | Call again with one key for this top-up. |
| `org_wallet_funding_required` | The company balance cannot cover the amount. | Live: send USDC to the deposit address `get_company_wallet` shows. Sandbox: add test money with `POST /api/v1/wallet/test-fund` and `{"amount_cents": 5000}`. Then call again with a new key. |
| `deposit_confirming` | Funding setup for this cardholder is still finishing. | Wait `retryAfterSeconds`, then call again with the same key. |
| `not_multi_use` | The card is single-use. | Create a card with `create_card` with `type: "multi_use"` and `funds_source: "company_flow"`, and top that one up from then on. |
| `not_company_funded` | The card is funded by the user, not the company balance. | Top up a company-funded multi-use card, or create one with `create_card` with `type: "multi_use"` and `funds_source: "company_flow"`. |
| `card_closed` | The card is closed, or it closed while the top-up was funding. In the second case the money stays with the cardholder and counts toward their next company-funded card. | Create a new card with `create_card` with `type: "multi_use"` and `funds_source: "company_flow"`. |
| `limit_exceeds_preset_total` | The card's preset caps its total spend below the new limit. | Top up a smaller amount with a new key, or create a card under a preset with a higher total. |
| `idempotency_key_reuse` | The key was already used with different arguments, for a top-up or for a card created with `create_card`. | Use a new key for this top-up. |

A few failures come back as a tool error instead of a status, with the code at the start of the message. Nothing is reserved for any of them except `top_up_failed`.

| Error code | Why | What to do |
| - | - | - |
| `top_up_failed` | The top-up did not apply. The money stays with the cardholder and counts toward their next company-funded card. | Call again with a new key. |
| `kyc_required` | The cardholder's identity verification is not approved. | Finish verification with `start_cardholder_kyc`, then call again. |
| `org_onboarding_required` | The cardholder has not finished onboarding. | Finish onboarding with `create_onboarding_session`, then call again. |
| `subscription_required` | Live top-ups from the company balance need an active subscription. | Subscribe from Settings, Billing in the dashboard, then call again. |

The same top-up over REST is `POST /api/v1/cards/{id}/topups` with an `Idempotency-Key` header and `{"amount_cents": 500}`.


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