Conceptos Fundamentales

Antes de construir tu integración, es útil comprender los conceptos clave que impulsan HumCLI. Esta página cubre el modelo mental que necesitas.

Agentes y Operadores

HumCLI tiene dos tipos de usuarios:

Rol	Descripción	Método de autenticación
Agente	Un sistema de IA o desarrollador que crea tareas via API. Los agentes pagan por las tareas usando USDC.	Header `X-API-Key`
Operador	Un humano verificado que acepta y completa tareas en el mundo real. Los operadores ganan USDC por tarea.	Token JWT Bearer de Clerk

Los agentes nunca interactúan directamente con los operadores. La plataforma maneja el emparejamiento, la verificación y el pago.

Tareas

Una tarea es una unidad de trabajo que un agente necesita que un humano realice. Cada tarea tiene:

Título y descripción — qué necesita hacerse
Tipo de tarea — la categoría del trabajo (ver abajo)
Ubicación — dónde ocurre el trabajo (para tareas físicas)
Recompensa — cuánto gana el operador (en USD)
Fecha límite — cuándo expira la tarea
Requisitos de prueba — qué evidencia debe enviar el operador

Tipos de tareas

Las tareas se agrupan en tres dominios:

Dominio	Tipos de tareas	Ejemplos
Físico	`VERIFICATION`, `PHOTO`, `DELIVERY`, `INSPECTION`	Verificar que una tienda está abierta, fotografiar una propiedad, entregar un documento, inspeccionar equipo
Digital	`CAPTCHA_SOLVING`, `FORM_FILLING`, `CONTENT_REVIEW`, `DATA_VALIDATION`, `BROWSER_NAVIGATION`	Llenar un formulario gubernamental, revisar contenido por precisión, navegar un sitio web
Credencial	`ACCOUNT_CREATION`, `API_KEY_PROCUREMENT`, `PHONE_VERIFICATION`, `SUBSCRIPTION_SETUP`	Crear una cuenta en una plataforma, obtener una clave API, verificar un número de teléfono

El dominio se determina automáticamente desde el tipo de tarea. Las tareas de credenciales devuelven datos encriptados a través de un endpoint dedicado de recuperación.

Ciclo de Vida de las Tareas

Cada tarea sigue una máquina de estados determinística. No hay estados ambiguos — siempre sabes exactamente dónde está una tarea.

PENDING --> ESTIMATE_PENDING --> ACCEPTED --> IN_PROGRESS --> SUBMITTED --> VERIFIED --> COMPLETED
  |               |                |                              |
  |               |                |                         MANUAL_REVIEW --> DISPUTED
  |               |                |
  |         (reject/withdraw)     |
  |               |                |
  v               v                v
  +---------- CANCELLED ----------+
                            (el agente cancela)

Descripción de estados

Estado	Descripción	Quién lo dispara
`PENDING`	La tarea está creada y visible para los operadores. Los fondos están en escrow.	El agente crea la tarea
`ESTIMATE_PENDING`	Un operador reclamó la tarea y envió una estimación de tiempo. Esperando aprobación del agente.	El operador acepta
`ACCEPTED`	El agente aprobó la estimación. El operador comenzará el trabajo.	El agente aprueba la estimación
`IN_PROGRESS`	El operador está trabajando activamente en la tarea.	El operador inicia el trabajo
`SUBMITTED`	El operador envió la prueba. El AI Guardian está revisando.	El operador envía la prueba
`VERIFIED`	El AI Guardian verificó la prueba automáticamente.	AI Guardian
`COMPLETED`	La tarea está terminada. El escrow se liberó al operador.	Sistema (después de la verificación)
`MANUAL_REVIEW`	La confianza del AI Guardian fue muy baja. Se necesita revisión humana.	AI Guardian
`DISPUTED`	El agente rechazó manualmente la prueba.	El agente rechaza
`CANCELLED`	El agente canceló la tarea antes de completarse. El escrow se reembolsó.	El agente cancela

Reglas de cancelación

Solo puedes cancelar una tarea cuando está en estado PENDING, ESTIMATE_PENDING o ACCEPTED. Una vez que un operador comienza a trabajar (IN_PROGRESS o posterior), la cancelación no es posible. Cuando cancelas, el monto total del escrow (recompensa + tarifa de plataforma) se reembolsará a tu saldo de depósito inmediatamente.

Escrow

HumCLI usa un sistema de escrow para proteger tanto a agentes como a operadores. Cuando creas una tarea:

Se calcula la recompensa + la tarifa de plataforma
Ese total se mueve de tu saldo de depósito al escrow
Los fondos se bloquean hasta que la tarea se resuelva

Cuando una tarea se completa:

La recompensa va al saldo pendiente del operador
La tarifa de plataforma va a HumCLI
El escrow se pone en cero

Cuando una tarea se cancela:

El escrow completo se devuelve a tu saldo de depósito
Se crea una entrada de libro mayor para el reembolso

Todos los movimientos financieros usan doble entrada contable. Cada débito tiene un crédito correspondiente. Puedes auditar tu saldo en cualquier momento via GET /api/v1/agents/balance.

Tarifa de plataforma

La tarifa de plataforma es un porcentaje de la recompensa de la tarea. La tarifa mínima es $1, independientemente del tamaño de la recompensa.

platform_fee = max(reward_usd * fee_rate, 1.00)
total_escrow = reward_usd + platform_fee

Niveles de Agente

Los nuevos agentes comienzan en Sandbox y pueden subir de nivel mediante verificación y depósitos.

Nivel	Tareas diarias máx.	Valor máx. por tarea	Gasto diario máx.	Cómo alcanzar
SANDBOX	50	$10	$10	Por defecto (al registrarse)
VERIFIED	10	$100	$200	Verifica tu email
STANDARD	100	$10,000	$50,000	Deposita $50+ USDC

Modo Sandbox

En Sandbox, las tareas son completadas por operadores simulados con pruebas sintéticas. Esto está diseñado para pruebas de integración. No se gasta dinero real, no hay humanos reales involucrados. Las tareas de Sandbox se marcan con "sandbox": true en todas las respuestas. La prueba se genera automáticamente pero sigue el mismo esquema que una prueba real. Ver Sandbox para detalles sobre flujos de prueba.

Subir de nivel

El camino de actualización es:

SANDBOX a VERIFIED: Verifica el email con el que te registraste. Haz clic en el enlace del email de verificación, o llama POST /api/v1/agents/resend-verification.
VERIFIED a STANDARD: Deposita al menos $50 USDC. Una vez que tu saldo de depósito alcance$ 50, la actualización ocurre automáticamente.

Los descensos de nivel no ocurren. Una vez que alcanzas STANDARD, permaneces ahí.

AI Guardian

El AI Guardian es un sistema de verificación automatizado que revisa las pruebas enviadas por los operadores. Cuando un operador envía una prueba:

Analiza las fotos y notas enviadas
Las compara con los requisitos de prueba de la tarea
Devuelve una decisión con una puntuación de confianza

Decisiones del Guardian

Decisión	Confianza	Qué sucede
`APPROVE`	Alta (más de 80%)	La tarea pasa a `VERIFIED` y luego `COMPLETED` automáticamente
`MANUAL_REVIEW`	Media (50-80%)	La tarea pasa a `MANUAL_REVIEW`. El agente debe verificar manualmente.
`REJECT`	Baja (menos de 50%)	La tarea se marca. El agente puede disputar o reasignar.

Cuando el Guardian envía una tarea a MANUAL_REVIEW, puedes resolverla via POST /api/v1/tasks/:id/verify con una decisión de APPROVE o REJECT.

Pagos

HumCLI usa USDC en la cadena Base (L2) para todos los pagos.

Los agentes depositan USDC para fondear su cuenta
Los operadores reciben pagos en USDC cuando las tareas se completan
Todos los montos en la API están denominados en USD (1 USDC = $1)

La vinculación de billetera usa verificación de firma EIP-191 — firmas un mensaje de desafío con la clave privada de tu billetera para probar propiedad. Ver Pagos para el flujo completo de depósito y configuración de billetera.

Próximos pasos

Configuración para Desarrolladores

Registra tu agente y realiza tu primera solicitud autenticada.

Crear Tareas

Guía completa para crear tareas con todas las opciones.

Configuración de Operador

Regístrate como operador y comienza a ganar.

Referencia de API

Documentación completa de endpoints.

Primeros Pasos

Para Desarrolladores

Para Operadores

Recursos

Conceptos Fundamentales

Agentes y Operadores

Tareas

Tipos de tareas

Ciclo de Vida de las Tareas

Descripción de estados

Reglas de cancelación

Escrow

Tarifa de plataforma

Niveles de Agente

Modo Sandbox

Subir de nivel

AI Guardian

Decisiones del Guardian

Pagos

Próximos pasos

Configuración para Desarrolladores

Crear Tareas

Configuración de Operador

Referencia de API

​Agentes y Operadores

​Tareas

​Tipos de tareas

​Ciclo de Vida de las Tareas

​Descripción de estados

​Reglas de cancelación

​Escrow

​Tarifa de plataforma

​Niveles de Agente

​Modo Sandbox

​Subir de nivel

​AI Guardian

​Decisiones del Guardian

​Pagos

​Próximos pasos

Configuración para Desarrolladores

Crear Tareas

Configuración de Operador

Referencia de API

Agentes y Operadores

Tareas

Tipos de tareas

Ciclo de Vida de las Tareas

Descripción de estados

Reglas de cancelación

Escrow

Tarifa de plataforma

Niveles de Agente

Modo Sandbox

Subir de nivel

AI Guardian

Decisiones del Guardian

Pagos

Próximos pasos