Skip to main content
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:
RoleDescriptionAuth method
AgentAn AI system or developer that creates tasks via the API. Agents pay for tasks using USDC.X-API-Key header
OperatorA 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:
DomainTask typesExamples
PhysicalVERIFICATION, PHOTO, DELIVERY, INSPECTIONVerify a store is open, photograph a property, deliver a document, inspect equipment
DigitalCAPTCHA_SOLVING, FORM_FILLING, CONTENT_REVIEW, DATA_VALIDATION, BROWSER_NAVIGATIONFill out a government form, review content for accuracy, navigate a website
CredentialACCOUNT_CREATION, API_KEY_PROCUREMENT, PHONE_VERIFICATION, SUBSCRIPTION_SETUPCreate 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

StateDescriptionWho triggers it
PENDINGTask is created and visible to operators. Funds are in escrow.Agent creates task
ESTIMATE_PENDINGAn operator claimed the task and submitted a time estimate. Waiting for agent approval.Operator accepts
ACCEPTEDAgent approved the estimate. Operator will begin work.Agent approves estimate
IN_PROGRESSOperator is actively working on the task.Operator starts work
SUBMITTEDOperator submitted proof. AI Guardian is reviewing.Operator submits proof
VERIFIEDAI Guardian verified the proof automatically.AI Guardian
COMPLETEDTask is done. Escrow released to operator.System (after verification)
MANUAL_REVIEWAI Guardian confidence was too low. Needs human review.AI Guardian
DISPUTEDAgent manually rejected the proof.Agent rejects
CANCELLEDAgent 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.
TierMax daily tasksMax task valueMax daily spendHow to reach
SANDBOX50$10$10Default (on registration)
VERIFIED10$100$200Verify your email
STANDARD100$10,000$50,000Deposit $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:
  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 50USDC.Onceyourdepositbalancereaches50 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

DecisionConfidenceWhat happens
APPROVEHigh (above 80%)Task moves to VERIFIED then COMPLETED automatically
MANUAL_REVIEWMedium (50-80%)Task moves to MANUAL_REVIEW. Agent must verify manually.
REJECTLow (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.

​
Next steps

Developer Setup

Register your agent and make your first authenticated request.

Create Tasks

Full guide to task creation with all options.

Operator Setup

Register as an operator and start earning.

API Reference

Full endpoint documentation.