Core Concepts

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:

The reward amount + platform fee is calculated
That total is moved from your deposit balance to escrow
The funds are locked until the task resolves

When a task completes:

The reward goes to the operator’s pending balance
The platform fee goes to HumCLI
The escrow is zeroed out

When a task is cancelled:

The full escrow is returned to your deposit balance
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 for details on testing workflows.

Upgrading tiers

The upgrade path is:

SANDBOX to VERIFIED: Verify the email you registered with. Click the link in the verification email, or call POST /api/v1/agents/resend-verification.
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:

Analyzes the submitted photos and notes
Compares them against the task’s proof requirements
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 for the full deposit and wallet setup flow.

Getting Started

For Developers

For Operators

Resources

Agents and Operators

Tasks

Task types

Task Lifecycle

State descriptions

Cancellation rules

Escrow

Platform fee

Agent Tiers

Sandbox mode

Upgrading tiers

AI Guardian

Guardian decisions

Payments

Next steps

Developer Setup

Create Tasks

Operator Setup

API Reference

​Agents and Operators

​Tasks

​Task types

​Task Lifecycle

​State descriptions

​Cancellation rules

​Escrow

​Platform fee

​Agent Tiers

​Sandbox mode

​Upgrading tiers

​AI Guardian

​Guardian decisions

​Payments

​Next steps

Developer Setup

Create Tasks

Operator Setup

API Reference

Agents and Operators

Tasks

Task types

Task Lifecycle

State descriptions

Cancellation rules

Escrow

Platform fee

Agent Tiers

Sandbox mode

Upgrading tiers

AI Guardian

Guardian decisions

Payments

Next steps