> This page is also available as Markdown: append .md to its URL. The full index of Sikaru docs is at https://docs.sikaru.ai/llms.txt. Code examples use only operations from the public API reference at https://docs.sikaru.ai/api-reference.

# Agent credit top-ups

Facts on this page:

1. Check the balance first: `sikaru credits balance [-p PROJECT] [-o json]`, or `GET /v1/projects/{project_id}/credits` (SDK operation `credit_top_ups_get_balance`, project API key with `runs:read` or `runs:create`). The response is `{state, availableUsd, topUpMaxUsd}`: `state` is `ready`, `no_card` or `complimentary`; `availableUsd` is null unless `ready`; `topUpMaxUsd` is the largest offer allowed now, or null while agent top-ups are off.
2. Create a top-up offer: `sikaru credits add --amount 20 [-p PROJECT] [-o json]`, or `POST /v1/projects/{project_id}/credit-top-ups` with `{"amountUsd": "20.00"}` (SDK operation `credit_top_ups_create`). The response is `{id, amountUsd, expiresAt, payUrl, status}`.
3. Pay `payUrl` with an agent wallet that supports HTTP 402 machine payments. Link is the supported agent wallet: `link-cli mpp pay PAY_URL --method POST --context "..."`.
4. Read an offer: `sikaru credits status ID [-o json]`, or `GET /v1/projects/{project_id}/credit-top-ups/{top_up_id}`. Statuses: `offered`, `charging`, `pending_action`, `paid`, `credited`, `expired`, `failed`, `disputed`.
5. Limits: $5.00 minimum, a per-top-up maximum (default $500.00, or lower when an organization admin sets a cap in Billing), US and Canada payers. Offers expire after 45 minutes. An organization with no card yet (`state` is `no_card`) can still be funded: its first paid top-up opens its credit account. When an admin turns agent top-ups off, offers are refused with `top_up_unavailable`.
6. A run paused with reason `credits_exhausted` carries a `topUp` hint only while the organization has agent top-ups turned on; its `maxUsd` is the organization's per-top-up cap. After the payment returns, the run resumes on its own; `sikaru agent runs resume --project-id PROJECT --run-id RUN` continues it at once.
7. People fund the organization in Billing: save a card (the first card earns a one-time $5 starting credit), add credits from $5 to $500 in whole dollars, or turn on auto-reload, which adds a fixed amount ($5 to $500, more than the threshold) when the balance falls below a threshold ($0 to \$500), both in whole dollars.

An agent that runs out of credits can fund its organization itself. It asks Sikaru for a **top-up offer** of an amount it chooses, and its agent wallet pays the offer's URL. The credits land in the organization's wallet once the payment succeeds, and a run that paused for funding can resume in the same turn. No one needs to open Billing, not even for a brand-new organization: its first paid top-up opens its credit account.

Anyone who can read runs in a project can check its organization's balance, and anyone who can start runs can create an offer for that organization: a project API key with `runs:read` or `runs:create`, or a CLI sign-in. Paying an offer can only add credits to that organization.

Organization admins control agent top-ups in Billing: they can turn them off for the whole organization, or cap each top-up below Sikaru's maximum. Offers, payments and the `topUp` hint follow both settings.

## Check the balance

An agent can check its organization's credits before work pauses, and top up while it still has room to finish.

#### CLI

```sh
sikaru credits balance -p PROJECT
```

```text
Available: $2.50
Agent top-ups: up to $50.00 per top-up with `sikaru credits add`
```

Add `-o json` for `{"state": "ready", "availableUsd": "2.500000", "topUpMaxUsd": "50.00"}`.

#### Python

```python
balance = client.credit_top_ups.get_balance("PROJECT")
if balance.top_up_max_usd and float(balance.available_usd or 0) < 5:
    offer = client.credit_top_ups.create("PROJECT", amount_usd="20.00")
```

#### TypeScript

```ts
const balance = await client.creditTopUps.getBalance("PROJECT");
if (balance.topUpMaxUsd && Number(balance.availableUsd ?? 0) < 5) {
  await client.creditTopUps.create("PROJECT", { amountUsd: "20.00" });
}
```

`state` is `ready` when credits fund work, `no_card` while the organization has no credit account yet (an agent top-up opens one, as does saving a card in Billing), and `complimentary` when usage is covered. `availableUsd` is what new work can use now, after amounts held for work in progress. `topUpMaxUsd` is the largest offer the agent can create, or `null` while agent top-ups are off.

## Create an offer

#### CLI

```sh
sikaru credits add --amount 20 -p PROJECT
```

The command prints the offer's pay URL, amount and expiry. Add `-o json` for the full offer:

```json
{
  "id": "tu_...",
  "amountUsd": "20.00",
  "expiresAt": 1793606400,
  "payUrl": "https://api.sikaru.ai/v1/credit-top-ups/tu_.../pay",
  "status": "offered"
}
```

#### Python

```python
from sikaru_sdk import SikaruApi

client = SikaruApi(api_key="...")
offer = client.credit_top_ups.create("PROJECT", amount_usd="20.00")
print(offer.pay_url)
```

#### TypeScript

```ts
import { SikaruApi } from "@aadi-labs/sikaru-sdk";

const client = new SikaruApi({ apiKey: "..." });
const offer = await client.creditTopUps.create("PROJECT", { amountUsd: "20.00" });
console.log(offer.payUrl);
```

Amounts are US dollars in whole cents, such as `20` or `20.50`. An amount outside the limits is refused before any payment is requested.

## Pay the offer with an agent wallet

The pay URL takes payment through the standard HTTP 402 machine-payment exchange: a request without payment returns `402` with a payment challenge, and the agent's wallet answers it with a one-time payment token. The URL needs no Sikaru credential.

[Link](https://link.com) is the supported agent wallet. With its CLI, the agent pays the URL in one command, and the person behind the wallet approves the spend:

```sh
link-cli mpp pay "PAY_URL" --method POST \
  --context "Adding 20 USD of Sikaru credits so my paused agent run can continue, at the request of the account owner."
```

The amount comes from the challenge. The wallet shows `--context`, which must be at least 100 characters, to the person approving the payment. A successful payment returns the offer with status `credited` and `fundsAvailable: true`. If `fundsAvailable` is `false`, the credits are in place but spending has not caught up yet; wait for `Retry-After` seconds before resuming.

Each offer is charged at most once. Paying it again returns the original receipt; paying an expired offer is refused. Check an offer at any time:

```sh
sikaru credits status tu_... -p PROJECT
```

## Resume a paused run

When a run stops because the organization has no credits, it pauses with reason `credits_exhausted` and keeps its work. While the organization has agent top-ups turned on, the pause, the `run.paused` event and `402` refusals carry a `topUp` hint. Its `maxUsd` is the organization's per-top-up cap:

```json
{
  "reason": "credits_exhausted",
  "topUp": {
    "operation": "credit_top_ups_create",
    "cli": "sikaru credits add",
    "minUsd": "5.00",
    "maxUsd": "500.00"
  }
}
```

`sikaru agent run` exits with code `5`, and its `next` field lists the top-up command before the resume command. Once the credits land, the paused turn resumes on its own. To continue the same turn at once, resume it:

```sh
sikaru agent runs resume --project-id PROJECT --run-id RUN
```

Other funding stops, such as the organization's monthly spend limit or an agent's spending cap, carry no hint: a person resolves them in Billing.

## Funding from Billing

Agent top-ups sit alongside the ways people fund an organization in Billing:

* **Card.** An admin saves one card for the organization. The first card earns a one-time \$5 starting credit.
* **Add Credits.** Buy any whole-dollar amount from $5 to $500 on the saved card.
* **Auto Reload.** When the balance falls below $X, add $Y. Both are whole dollars: the threshold is $0 to $500 and the amount is $5 to $500, more than the threshold. After two declined reload charges in a row, auto-reload turns itself off until an admin turns it back on.
* **Monthly spend limit and usage alerts.** An admin can cap the organization's spend for the calendar month, and set up to 10 alerts that email the organization's admins when the month's spend passes an amount.

Transactions in Billing list every credit purchase, auto-reload, agent top-up and the starting credit.

## Limits

| Limit              | Value                                          |
| ------------------ | ---------------------------------------------- |
| Minimum per top-up | \$5.00                                         |
| Maximum per top-up | \$500.00 by default, or the organization's cap |
| Offer lifetime     | 45 minutes                                     |
| Payers             | US and Canada                                  |

If a payment is disputed, new top-ups for the organization pause until support clears them; credits already added stay in place. Top-ups appear in Billing transactions as Agent Top-Up, with the agent that paid.