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

# 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 the dashboard's Go live page, 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.