---
title: top_up
description: Get a Stripe Checkout link to add prepaid credit to this workspace. The agent never enters card details.
---

<WorksIn />

Open a Stripe-hosted Checkout page to add prepaid credits to this workspace and return its URL
for the customer to pay on. The agent never enters card details itself; it hands the link to a
human. `POST /v1/top-ups` itself needs a dashboard owner or admin session and cannot be called
with an agent token, which is why this tool exists: it is the way an agent gets a payment link.

## Inputs

| Argument | Type | Required | Default | Limits | Meaning |
| --- | --- | --- | --- | --- | --- |
| `amountUsd` | number | No | this gateway's suggested amount | exclusive minimum 0, max 1000000 | Amount to top up. Omitted, it is at least `minimumUsd` from [`balance`](/mcp-tools/balance), more when the balance is negative. Below the minimum is refused with the minimum in the error. |

The same amount within 10 minutes returns the same pending session; at most 3 new sessions per
hour. When a session cannot be opened (billing off, a read-only token, the operator workspace)
the result carries `checkoutUrl: null`, a `reason`, and `dashboardUrl` where a human can top up
instead.

## Example call

```json
{
  "amountUsd": 20
}
```

## Example answer

```json
{
  "checkoutUrl": "https://checkout.stripe.com/c/pay/cs_test_a1b2c3d4",
  "topUpId": "topup_9f8e7d6c5b4a3928",
  "amountUsd": 20,
  "minimumUsd": 5,
  "maximumUsd": 500,
  "dashboardUrl": "https://looot.ai/usage?top_up=1"
}
```

## Errors

An amount outside the allowed range returns [`top_up_amount_out_of_range`](/errors/mcp-errors#top_up_amount_out_of_range), naming the minimum and
maximum. When a session cannot be opened at all, the tool still answers `isError: true` with
`code: "top_up_unavailable"` and a `reason` such as `billing_disabled`, `operator_workspace`,
`read_only_token`, [`rate_limited`](/errors/run-errors#rate_limited), `checkout_failed`, `stripe_timeout` or `balance_sufficient`;
`checkoutUrl` is `null` and `dashboardUrl` still points to the usage page for a human to top up
by hand.

## REST and CLI

- CLI/dashboard: a human tops up at `https://looot.ai/usage?top_up=1`, or `looot balance` shows the same link

<Related />