> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shumi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Access and Quotas

> Tiers, prices, the $SHUMI hold path, and exactly how the query counter works.

Shumi meters natural-language queries. Everything else (typed endpoints, tool calls, screeners) is metered separately and far more loosely.

## Tiers

| Tier    | Price         | Query allowance                          |
| ------- | ------------- | ---------------------------------------- |
| Free    | Free          | 10 to start, then 1 per day, permanently |
| Plus    | \$20 / month  | 50 per day                               |
| Pro     | \$200 / month | No limit                                 |
| Genesis | \$500 once    | Pro, for the lifetime of Shumi           |

You can also get one anonymous query before signing in at all.

**Genesis is gated.** Claiming it requires holding **3,000,000 \$SHUMI** on Base. The check runs server-side at purchase; an order from a wallet below the threshold is refunded automatically. It is not a soft prompt.

## How the free tier actually counts

This is the part that is usually described wrongly, including by an earlier version of these docs.

Free is **not** a daily allowance of N. It is a **lifetime grant of 10 queries** attached to your account, and once that grant is spent you get **one query per day, forever, at no cost**. The grant does not refill. The daily drip never stops.

```mermaid theme={"dark"}
flowchart TB
    Q["Ask query"] --> G{"Lifetime grant<br/>of 10 spent?"}
    G -- "no" --> U["Spend one of the 10.<br/>Never refills."]
    G -- "yes" --> D{"Used today's<br/>free query?"}
    D -- "no" --> V["Spend today's one.<br/>Resets at midnight UTC."]
    D -- "yes" --> R["429 RATE_LIMITED"]
```

The two counters behave differently on purpose:

|                      | Resets                                                |
| -------------------- | ----------------------------------------------------- |
| Free lifetime grant  | Never. It is a running total against a fixed ceiling. |
| Free daily drip      | Midnight UTC                                          |
| Plus daily allowance | Midnight UTC                                          |

So a free account that has been idle for a year still has whatever remains of its original ten, plus today's one, not eleven, and not zero.

## Unlocking with \$SHUMI instead

Holding \$SHUMI on Base grants a tier without a subscription. No purchase, no recurring charge; the hold *is* the entitlement, and it lapses if you sell.

| Hold              | Grants                         |
| ----------------- | ------------------------------ |
| 100,000 \$SHUMI   | Plus                           |
| 1,000,000 \$SHUMI | Pro                            |
| 3,000,000 \$SHUMI | Qualifies you to claim Genesis |

For Plus and Pro the hold is an alternative path. You may subscribe with a card instead. For Genesis it is a hard requirement, and holding it qualifies you to *buy*; it does not grant Genesis by itself.

When you hold and subscribe, **the higher tier wins.** Entitlements resolve across every source and the best one applies; they do not stack into a larger allowance.

## Checking what you actually have

Tier is resolved from your entitlement, not inferred from your credential. The same resolver that answers this endpoint is the one the gate enforces, so the two cannot disagree:

```bash theme={"dark"}
curl https://api.shumi.ai/api/cli/billing/tier \
  -H "Authorization: Bearer $SHUMI_TOKEN"
```

```json theme={"dark"}
{
  "schemaVersion": 1,
  "data": {
    "tier": "pro",
    "source": "shumi_hold",
    "expiresAt": null,
    "identity": { "kind": "apiKey", "userId": 1042, "walletAddress": "0x…" }
  }
}
```

`source` tells you *why* you have the tier, which matters when you have more than one path active:

| `source`          | Meaning                                 |
| ----------------- | --------------------------------------- |
| `free`            | No entitlement beyond the free tier     |
| `shumi_hold`      | Granted by your \$SHUMI balance on Base |
| subscription      | An active monthly subscription          |
| lifetime purchase | Genesis, bought once                    |
| `manual`          | Granted directly                        |

The two purchase sources carry the payment provider's name inside the literal
string. Read the value from this endpoint rather than hardcoding it: the
meaning is stable, the spelling is not.

<Note>
  The paid entry tier is **Plus** everywhere a person reads it, and `access` in the `tier` field. The wire name predates the display name and is kept rather than migrated, per the rule on the [Glossary](/platform/glossary). Match on `access`, print "Plus".
</Note>

## When the quota runs out

Ask queries return `429 RATE_LIMITED` with the used and limit values in `error.details`. Typed endpoints are metered separately and are not consumed by ask queries.

Streaming is the exception worth knowing: `GET /api/cli/watch/{stream}` holds a connection open, which makes it the most expensive route on the surface, and it requires a paid tier rather than being purchasable per call. Exhausted free quota gets `429` there, not a partial stream.

## Related

* [API Overview](/api-reference/introduction), the envelope and error contract
* [Quickstart](/quickstart), getting a key
* [Glossary](/platform/glossary), why `access` and Plus are both correct