# Tier System

ZDrive has three access tiers based on wallet connection and credit balance.

## Tier comparison

|                      | Anonymous         | Connected                                  | Paid                  |
| -------------------- | ----------------- | ------------------------------------------ | --------------------- |
| **Requirement**      | None              | Wallet + minimum on-chain activity on Base | Wallet + credits > 0  |
| **Query limit**      | 10 / session (1h) | 25 / day                                   | 100 / hour (burst)    |
| **Models**           | Qwen3-32B only    | Qwen3-32B, MiniMax-M2.5                    | All TEE models        |
| **Vault upload**     | No                | No                                         | Yes                   |
| **Datacenter block** | Yes               | Yes                                        | No (agent use)        |
| **Rate key**         | Session UUID      | Wallet address + date                      | Wallet address + hour |

## Tier resolution flow

```mermaid
flowchart TD
    REQ[Request] --> WALLET{Wallet signature\npresent?}
    WALLET -->|No| SESSION{Session token\npresent?}
    SESSION -->|No| DENY401[401 No identity]
    SESSION -->|Yes| ASNCHECK1{Datacenter\nASN?}
    ASNCHECK1 -->|Yes| DENY403[403 Datacenter blocked]
    ASNCHECK1 -->|No| IPLIMIT{IP daily session\nlimit reached?}
    IPLIMIT -->|Yes| DENY429[429 Connect wallet\nto continue]
    IPLIMIT -->|No| SESSLIMIT{Session query\ncount ≥ 10?}
    SESSLIMIT -->|Yes| DENY429b[429 Free limit reached]
    SESSLIMIT -->|No| FREE[Free tier — Qwen3-32B]

    WALLET -->|Yes| BALANCE{credits > 0?}
    BALANCE -->|Yes| HOURLY{Hourly burst\n≥ 100?}
    HOURLY -->|Yes| DENY429c[429 Hourly limit]
    HOURLY -->|No| PAID[Paid tier — full models]
    BALANCE -->|No| ASNCHECK2{Datacenter\nASN?}
    ASNCHECK2 -->|Yes| DENY403b[403 Datacenter blocked]
    ASNCHECK2 -->|No| TXNCHECK{On-chain activity\nthreshold met?}
    TXNCHECK -->|Yes| DAILY25{Daily count\n≥ 25?}
    TXNCHECK -->|No| DAILY10{Daily count\n≥ 10?}
    DAILY25 -->|Yes| DENY429d[429 Daily limit]
    DAILY25 -->|No| CONNECTED[Connected tier]
    DAILY10 -->|Yes| DENY429e[429 Daily limit]
    DAILY10 -->|No| CONNECTED
```

## Notes

**Wallet age gate:** Connected wallets with insufficient on-chain activity on Base receive the same query limit as anonymous users. This mitigates automated abuse via freshly created wallets.

**Datacenter block:** Requests from known datacenter ASNs are blocked on free and connected tiers. Paid users bypass this — agent and automated workloads are a paid use case.

**Session expiry:** Anonymous sessions expire after 1 hour regardless of query count (KV TTL = 3600s). Connected and paid tiers use daily/hourly keys that reset at UTC midnight/hour.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.zdrive.io/architecture/tiers.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.