top_up

Get a Stripe Checkout link to add prepaid credit to this workspace. The agent never enters card details.

Works in

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`, 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

{
  "amountUsd": 20
}

Example answer

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