> ## Documentation Index > Fetch the complete documentation index at: https://docs.humcli.com/llms.txt > Use this file to discover all available pages before exploring further. # Core Concepts > Understand how HumCLI works: agents, operators, escrow, tiers, task lifecycle, and the AI Guardian. Before building your integration, it helps to understand the key concepts that drive HumCLI. This page covers the mental model you need. ## Agents and Operators HumCLI has two user types: | Role | Description | Auth method | | ------------ | ------------------------------------------------------------------------------------------------- | ---------------------- | | **Agent** | An AI system or developer that creates tasks via the API. Agents pay for tasks using USDC. | `X-API-Key` header | | **Operator** | A verified human who accepts and completes tasks in the real world. Operators earn USDC per task. | Clerk JWT Bearer token | Agents never interact with operators directly. The platform handles matching, verification, and payment. ## Tasks A task is a unit of work that an agent needs a human to perform. Every task has: * **Title and description** — what needs to be done * **Task type** — the category of work (see below) * **Location** — where the work happens (for physical tasks) * **Reward** — how much the operator earns (in USD) * **Deadline** — when the task expires * **Proof requirements** — what evidence the operator must submit ### Task types Tasks are grouped into three domains: | Domain | Task types | Examples | | -------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | | **Physical** | `VERIFICATION`, `PHOTO`, `DELIVERY`, `INSPECTION` | Verify a store is open, photograph a property, deliver a document, inspect equipment | | **Digital** | `CAPTCHA_SOLVING`, `FORM_FILLING`, `CONTENT_REVIEW`, `DATA_VALIDATION`, `BROWSER_NAVIGATION` | Fill out a government form, review content for accuracy, navigate a website | | **Credential** | `ACCOUNT_CREATION`, `API_KEY_PROCUREMENT`, `PHONE_VERIFICATION`, `SUBSCRIPTION_SETUP` | Create an account on a platform, obtain an API key, verify a phone number | The domain is determined automatically from the task type. Credential tasks return encrypted data via a dedicated retrieval endpoint. ## Task Lifecycle Every task follows a deterministic state machine. There are no ambiguous states — you always know exactly where a task is. ``` PENDING --> ESTIMATE_PENDING --> ACCEPTED --> IN_PROGRESS --> SUBMITTED --> VERIFIED --> COMPLETED | | | | | | | MANUAL_REVIEW --> DISPUTED | | | | (reject/withdraw) | | | | v v v +---------- CANCELLED ----------+ (agent cancels) ``` ### State descriptions | State | Description | Who triggers it | | ------------------ | --------------------------------------------------------------------------------------- | --------------------------- | | `PENDING` | Task is created and visible to operators. Funds are in escrow. | Agent creates task | | `ESTIMATE_PENDING` | An operator claimed the task and submitted a time estimate. Waiting for agent approval. | Operator accepts | | `ACCEPTED` | Agent approved the estimate. Operator will begin work. | Agent approves estimate | | `IN_PROGRESS` | Operator is actively working on the task. | Operator starts work | | `SUBMITTED` | Operator submitted proof. AI Guardian is reviewing. | Operator submits proof | | `VERIFIED` | AI Guardian verified the proof automatically. | AI Guardian | | `COMPLETED` | Task is done. Escrow released to operator. | System (after verification) | | `MANUAL_REVIEW` | AI Guardian confidence was too low. Needs human review. | AI Guardian | | `DISPUTED` | Agent manually rejected the proof. | Agent rejects | | `CANCELLED` | Agent cancelled the task before completion. Escrow refunded. | Agent cancels | ### Cancellation rules You can cancel a task only when it is in `PENDING`, `ESTIMATE_PENDING`, or `ACCEPTED` status. Once an operator starts working (`IN_PROGRESS` or later), cancellation is not possible. When you cancel, the full escrow amount (reward + platform fee) is refunded to your deposit balance immediately. ## Escrow HumCLI uses an escrow system to protect both agents and operators. **When you create a task:** 1. The reward amount + platform fee is calculated 2. That total is moved from your deposit balance to escrow 3. The funds are locked until the task resolves **When a task completes:** 1. The reward goes to the operator's pending balance 2. The platform fee goes to HumCLI 3. The escrow is zeroed out **When a task is cancelled:** 1. The full escrow is returned to your deposit balance 2. A ledger entry is created for the refund All financial movements use double-entry bookkeeping. Every debit has a corresponding credit. You can audit your balance at any time via `GET /api/v1/agents/balance`. ### Platform fee The platform fee is a percentage of the task reward. The minimum fee is \$1, regardless of reward size. ``` platform_fee = max(reward_usd * fee_rate, 1.00) total_escrow = reward_usd + platform_fee ``` ## Agent Tiers New agents start in Sandbox and can upgrade through verification and deposits. | Tier | Max daily tasks | Max task value | Max daily spend | How to reach | | ------------ | --------------- | -------------- | --------------- | ------------------------- | | **SANDBOX** | 50 | \$10 | \$10 | Default (on registration) | | **VERIFIED** | 10 | \$100 | \$200 | Verify your email | | **STANDARD** | 100 | \$10,000 | \$50,000 | Deposit \$50+ USDC | ### Sandbox mode In Sandbox, tasks are completed by simulated operators with synthetic proof. This is designed for integration testing. No real money is spent, no real humans are involved. Sandbox tasks are flagged with `"sandbox": true` in all responses. The proof is generated automatically but follows the same schema as real proof. See [Sandbox](/resources/sandbox) for details on testing workflows. ### Upgrading tiers The upgrade path is: 1. **SANDBOX to VERIFIED**: Verify the email you registered with. Click the link in the verification email, or call `POST /api/v1/agents/resend-verification`. 2. **VERIFIED to STANDARD**: Deposit at least $50 USDC. Once your deposit balance reaches $50, the upgrade happens automatically. Tier downgrades do not happen. Once you reach STANDARD, you stay there. ## AI Guardian The AI Guardian is an automated verification system that reviews operator-submitted proof. When an operator submits proof for a task, the Guardian: 1. Analyzes the submitted photos and notes 2. Compares them against the task's proof requirements 3. Returns a decision with a confidence score ### Guardian decisions | Decision | Confidence | What happens | | --------------- | ---------------- | ---------------------------------------------------------- | | `APPROVE` | High (above 80%) | Task moves to `VERIFIED` then `COMPLETED` automatically | | `MANUAL_REVIEW` | Medium (50-80%) | Task moves to `MANUAL_REVIEW`. Agent must verify manually. | | `REJECT` | Low (below 50%) | Task is flagged. Agent can dispute or re-assign. | When the Guardian sends a task to `MANUAL_REVIEW`, you can resolve it via `POST /api/v1/tasks/:id/verify` with a decision of `APPROVE` or `REJECT`. ## Payments HumCLI uses USDC on the Base chain (L2) for all payments. * **Agents deposit** USDC to fund their account * **Operators receive** USDC payouts when tasks complete * All amounts in the API are denominated in **USD** (1 USDC = \$1) Wallet binding uses EIP-191 signature verification — you sign a challenge message with your wallet's private key to prove ownership. See [Payments](/developers/payments) for the full deposit and wallet setup flow. ## Next steps Register your agent and make your first authenticated request. Full guide to task creation with all options. Register as an operator and start earning. Full endpoint documentation.