top_up_card

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

{
  "tool": "top_up_card",
  "arguments": {
    "card_id": "card_7c1d",
    "amount_cents": 500,
    "idempotency_key": "deposit-1042"
  }
}

The tool answers:

{
  "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:

{
  "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}.

MCP

Organization tools

User tools

What it does

Inputs

Returns

Example call

Refusals

​What it does

​Inputs

​Returns

​Example call

​Refusals

What it does

Inputs

Returns

Example call

Refusals