Skill: seesayearn-boop/loopuman (version 0.1.0)

--- name: loopuman description: Route tasks to verified human workers worldwide via Loopuman. Use when AI alone can't handle verification, translation, content moderation, image labeling, local knowledge, or subjective judgment. Results in minutes, paid in 8-second cUSD payments on Celo. metadata: { "openclaw": { "emoji": "🌍", "requires": { "bins": ["curl", "jq"] }, }, } --- # Loopuman — The Human Layer for AI Route tasks to verified human workers when AI alone isn't enough. Workers are paid in 8 seconds via cUSD on Celo blockchain. No app download required — workers operate via Telegram and WhatsApp. ## When to Use This Skill Use Loopuman when the task requires **real human judgment, perception, or local knowledge** that AI cannot reliably provide: - **Verification** — "Is this business address real?" "Does this photo match this listing?" - **Translation** — Nuanced, culturally-aware translation (not just word-for-word) - **Content moderation** — "Is this image appropriate?" "Does this review violate guidelines?" - **Image labeling** — "What objects are in this photo?" "Rate this image quality 1-10" - **Local knowledge** — "What's the current price of tomatoes in Nairobi?" - **Surveys & opinions** — "Which logo design is better?" "Rate this product description" - **Data collection** — "Find the phone number for this restaurant" - **Quality assurance** — "Does this AI-generated text sound natural?" **Do NOT use** for tasks AI can handle: math, code generation, summarization, web search, file operations. ## Setup Create the config file with your Loopuman API key: ```bash mkdir -p ~/.openclaw/skills/loopuman cat > ~/.openclaw/skills/loopuman/config.json << 'EOF' { "apiKey": "YOUR_API_KEY", "apiUrl": "https://api.loopuman.com" } EOF ``` Get your API key (one command, no auth needed): ```bash curl -X POST https://api.loopuman.com/api/v1/register \ -H "Content-Type: application/json" \ -d '{"email": "[REDACTED_SECRET]", "company_name": "Your Name", "promo_code": "LOBSTER"}' ``` This returns your `api_key` (starts with `lpm_`). Save it immediately — it cannot be retrieved later. **Promo codes for free credits:** - `CLAW500` — 500 VAE ($5.00) for first 10 OpenClaw testers - `LOBSTER` — 100 VAE ($1.00) for early access (50 spots) - No code — 25 VAE ($0.25) welcome bonus To add more funds, message [@LoopumanBot](https://t.me/LoopumanBot) on Telegram and link your account. ## API Authentication All requests use the `x-api-key` header: ``` x-[REDACTED_SECRET] ``` ## Creating a Task ```bash scripts/loopuman.sh create \ --title "Verify business address" \ --description "Check if this address exists on Google Maps: 123 Main St, Nairobi, Kenya. Reply with YES/NO and a screenshot." \ --category other \ --budget 50 \ --estimated-seconds 120 ``` **Parameters:** - `--title` — Short task title (required) - `--description` — Detailed instructions for the human worker (required, be specific!) - `--category` — One of: `survey`, `labeling`, `translation`, `writing`, `research`, `content_creation`, `ai_training`, `micro`, `other` (default: `other`). Note: for verification tasks use `other`, for moderation use `other`, for data collection use `research`. - `--budget` — Payment in VAE tokens. 100 VAE = $1 USD. (default: 100) - `--estimated-seconds` — Expected time for worker to complete (required for fair pay calculation, default: 120) - `--max-workers` — Number of workers (default: 1, max: 100) - `--priority` — `normal` or `high` (high notifies workers immediately) - `--webhook` — URL for push notifications on completion **Category minimum budgets:** - `survey`, `labeling`, `ai_training`, `micro`: 25 VAE ($0.25) - `research`, `content_creation`: 75 VAE ($0.75) - `writing`, `translation`: 100 VAE ($1.00) **Fair pay enforcement:** Loopuman enforces a $6/hr minimum effective rate. If your budget divided by estimated time is below this, the API will suggest a higher budget. **Writing good task descriptions:** - Be specific about what you need ("Reply YES or NO" not "verify this") - Include all context the worker needs - Specify the expected format of the response - Set clear success criteria ## Checking Task Status + Getting Results ```bash scripts/loopuman.sh status --task-id <TASK_ID> ``` Returns full task details including: - `status`: `active`, `completed`, `expired`, `cancelled` - `progress`: count of approved, pending_review, in_progress submissions - `submissions`: array of approved worker results with content - `pending_submissions`: results awaiting your approval ## Polling for Completion For tasks that need a result before continuing: ```bash # Poll every 30 seconds, timeout after 10 minutes scripts/loopuman.sh wait --task-id <TASK_ID> --interval 30 --timeout 600 ``` Returns the result as soon as an approved submission is available. ## Listing Tasks ```bash scripts/loopuman.sh list ``` ## Cancelling a Task ```bash scripts/loopuman.sh cancel --task-id <TASK_ID> ``` Refunds your balance if no workers have started. ## Task Types and Pricing | Category | Description | Min Budget (VAE) | Typical Completion | |----------|-------------|-----------------|-------------------| | `survey` | Quick responses, opinions | 25 ($0.25) | 1-5 min | | `labeling` | Tag images, categorize content | 25 ($0.25) | 1-5 min | | `micro` | 5-second microtasks | 25 ($0.25) | <1 min | | `ai_training` | RLHF, preference ranking | 25 ($0.25) | 1-5 min | | `research` | Find info, investigate | 75 ($0.75) | 5-20 min | | `content_creation` | Creative work | 75 ($0.75) | 5-20 min | | `writing` | Articles, descriptions | 100 ($1.00) | 10-30 min | | `translation` | Language translation | 100 ($1.00) | 5-15 min | | `other` | Custom tasks | 25 ($0.25) | Varies | ## Examples **Verify an address:** "Create a Loopuman task to verify if '456 Kenyatta Ave, Nairobi' is a real business address" → `create --title "Verify address" --description "Check Google Maps for 456 Kenyatta Ave, Nairobi. Reply YES/NO with screenshot." --category other --budget 30 --estimated-seconds 120` **Translate with cultural context:** "Use Loopuman to translate 'We're excited to launch' into Swahili naturally" → `create --title "Translate to Swahili" --description "Translate to Swahili. Make it sound natural, not robotic: 'We're excited to launch our new product'" --category translation --budget 100 --estimated-seconds 180` **Get a human opinion:** "Ask a real person which logo looks more professional" → `create --title "Logo comparison" --description "Which logo looks more professional? A or B? Explain why in 2 sentences." --category survey --budget 25 --estimated-seconds 60` **Check AI output:** "Have a human verify this AI-generated product description" → `create --title "QA check on AI text" --description "Does this sound natural and accurate? Flag any issues: [paste text]" --category other --budget 30 --estimated-seconds 90` ## Error Handling | HTTP Code | Meaning | Fix | |-----------|---------|-----| | 401 | Invalid API key | Check `x-api-key` in config.json | | 400 | Missing fields or invalid category | Check required params | | 402 | Insufficient VAE balance | Top up via @LoopumanBot | | 404 | Task not found | Verify task ID | | 429 | Rate limit exceeded | Wait and retry | ## Links - Website: https://loopuman.com - Telegram Bot: https://t.me/LoopumanBot - ERC-8004 Agent: https://www.8004scan.io/agents/celo/17 - MCP: https://api.loopuman.com/.well-known/mcp.json - A2A: https://api.loopuman.com/.well-known/agent-card.json ⚠️ **Budget Safety:** Tasks are paid to workers upon completion. Start with small budgets (25-50 VAE) when testing. Loopuman charges 20% commission on top of the budget you set.

path: references/api-reference.md
content: # Loopuman API Reference

Base URL: `https://api.loopuman.com`

All requests require the `x-api-key` header.

## Authentication

```
x-[REDACTED_SECRET]
```

Get your key (no auth needed):
```bash
curl -X POST https://api.loopuman.com/api/v1/register \
  -H "Content-Type: application/json" \
  -d '{"email": "[REDACTED_SECRET]", "company_name": "Your Name"}'
```
Save the returned `api_key` (starts with `lpm_`) — it cannot be retrieved later.

## Endpoints

### POST /api/v1/register

Get an API key. No authentication required.

**Request:**
```json
{
  "email": "[REDACTED_SECRET]",
  "company_name": "Your Name or Company"
}
```

**Response (201):**
```json
{
  "message": "Welcome to Loopuman — The Human Layer for AI",
  "api_key": "lpm_abc123...",
  "user_id": "uuid",
  "important": "⚠️ Save this API key now — it cannot be retrieved later."
}
```

### POST /api/v1/tasks

Create a new human task.

**Request:**
```json
{
  "title": "Verify business address",
  "description": "Check if 123 Main St, Nairobi exists on Google Maps. Reply YES/NO with screenshot.",
  "category": "other",
  "budget_vae": 30,
  "estimated_seconds": 120,
  "max_workers": 1,
  "priority": "normal",
  "webhook_url": "https://your-server.com/webhook"
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `title` | string | yes | Short task title |
| `description` | string | yes | Detailed worker instructions |
| `category` | string | no | `survey`, `labeling`, `translation`, `writing`, `research`, `content_creation`, `ai_training`, `micro`, `other` (default: `other`) |
| `budget_vae` | integer | no | Payment per worker in VAE (default: 100). 100 VAE = $1 USD |
| `budget_usd` | number | no | Alternative: specify budget in USD |
| `estimated_seconds` | integer | yes | Expected completion time. Used for $6/hr minimum rate enforcement |
| `max_workers` | integer | no | Number of workers (default: 1, max: 100) |
| `priority` | string | no | `normal` or `high` (high notifies workers) |
| `webhook_url` | string | no | URL for push notification on completion |
| `auto_approve` | boolean | no | Auto-approve submissions (default: false) |
| `reference_media` | array | no | Array of image/doc URLs for worker reference |

**Response (201):**
```json
{
  "task_id": "uuid-here",
  "status": "active",
  "budget_vae": 30,
  "budget_usd": "0.30",
  "workers_needed": 1,
  "expires_at": "2026-02-14T19:00:00Z"
}
```

### GET /api/v1/tasks/:id

Get task status, progress, and submissions.

**Response:**
```json
{
  "task_id": "uuid-here",
  "title": "Verify business address",
  "description": "...",
  "category": "other",
  "status": "active",
  "budget_vae": 30,
  "budget_usd": "0.30",
  "max_workers": 1,
  "created_at": "2026-02-13T19:00:00Z",
  "expires_at": "2026-02-14T19:00:00Z",
  "progress": {
    "approved": 1,
    "pending_review": 0,
    "in_progress": 0,
    "total_slots": 1
  },
  "submissions": [
    {
      "submission_id": "sub-uuid",
      "content": "YES — the address exists. Commercial building on Kenyatta Ave.",
      "submitted_at": "2026-02-13T19:08:42Z",
      "approved_at": "2026-02-13T19:08:45Z",
      "rating": 5
    }
  ],
  "pending_submissions": []
}
```

**Statuses:** `active` → `completed` | `expired` | `cancelled`

### GET /api/v1/tasks

List all tasks for your API key.

### DELETE /api/v1/tasks/:id

Cancel a task. Refunds your balance if no workers have started.

## Error Codes

| Code | Meaning |
|------|---------|
| 401 | Invalid or missing `x-api-key` |
| 400 | Missing required fields, invalid category, or budget too low |
| 402 | Insufficient VAE balance |
| 404 | Task not found |
| 429 | Rate limit exceeded |
| 500 | Server error |

## Fair Pay

Loopuman enforces a **$6/hr minimum effective rate**. The API calculates: `(budget_vae / 100) / (estimated_seconds / 3600)`. If below $6/hr, it returns an error with a suggested budget.

## Currency

- 100 VAE = $1.00 USD
- New accounts: 100 VAE free
- 20% commission charged on top of budget (requester pays budget × 1.2)
- Workers receive 80% of budget (worker gets budget × 0.8)
- Workers paid in 8 seconds via cUSD on Celo blockchain


path: scripts/loopuman.sh
content: #!/usr/bin/env bash
# Loopuman CLI — Route tasks to verified human workers
# https://loopuman.com | https://www.8004scan.io/agents/celo/17

set -euo pipefail

# --- Config ---
CONFIG_FILE="${LOOPUMAN_CONFIG:-$HOME/.openclaw/skills/loopuman/config.json}"
if [[ ! -f "$CONFIG_FILE" ]]; then
  CONFIG_FILE="$HOME/.clawdbot/skills/loopuman/config.json"
fi

if [[ ! -f "$CONFIG_FILE" ]]; then
  echo "Error: Config file not found. Create one at ~/.openclaw/skills/loopuman/config.json"
  echo ""
  echo "mkdir -p ~/.openclaw/skills/loopuman"
  echo 'cat > ~/.openclaw/skills/loopuman/config.json << EOF'
  echo '{ "apiKey": "YOUR_API_KEY", "apiUrl": "https://api.loopuman.com" }'
  echo 'EOF'
  exit 1
fi

API_KEY=$(jq -r '.apiKey' "$CONFIG_FILE")
API_URL=$(jq -r '.apiUrl // "https://api.loopuman.com"' "$CONFIG_FILE")

if [[ "$API_KEY" == "null" || "$API_KEY" == "YOUR_API_KEY" ]]; then
  echo "Error: Invalid API key. Get one with:"
  echo "curl -X POST https://api.loopuman.com/api/v1/register -H 'Content-Type: application/json' -d '{\"email\":\"[REDACTED_SECRET]\",\"company_name\":\"Your Name\"}'"
  exit 1
fi

# --- Helpers ---
api() {
  local method="$1" endpoint="$2"
  shift 2
  curl -sf -X "$method" \
    -H "x-[REDACTED_SECRET]" \
    -H "Content-Type: application/json" \
    "$API_URL$endpoint" "$@"
}

usage() {
  cat <<EOF
Loopuman CLI — Route tasks to verified human workers

USAGE:
  loopuman.sh <command> [options]

COMMANDS:
  create    Create a new human task
  status    Check task status + get submissions
  wait      Poll until task completes
  list      List your tasks
  cancel    Cancel a task (refund if no workers)
  help      Show this help

EXAMPLES:
  loopuman.sh create --title "Verify address" \\
    --description "Is 123 Main St real? Reply YES/NO" \\
    --category other --budget 30 --estimated-seconds 120

  loopuman.sh status --task-id abc123
  loopuman.sh wait --task-id abc123 --interval 30 --timeout 600
  loopuman.sh list
  loopuman.sh cancel --task-id abc123
EOF
}

# --- Commands ---
cmd_create() {
  local title="" description="" category="other" budget=100 estimated_seconds=120 max_workers=1 webhook_url="" priority="normal"

  while [[ $# -gt 0 ]]; do
    case "$1" in
      --title) title="$2"; shift 2 ;;
      --description) description="$2"; shift 2 ;;
      --category) category="$2"; shift 2 ;;
      --budget) budget="$2"; shift 2 ;;
      --estimated-seconds) estimated_seconds="$2"; shift 2 ;;
      --max-workers) max_workers="$2"; shift 2 ;;
      --webhook) webhook_url="$2"; shift 2 ;;
      --priority) priority="$2"; shift 2 ;;
      *) echo "Unknown option: $1"; exit 1 ;;
    esac
  done

  if [[ -z "$title" ]]; then
    echo "Error: --title is required"; exit 1
  fi
  [[ -z "$description" ]] && description="$title"

  local payload
  payload=$(jq -n \
    --arg title "$title" \
    --arg description "$description" \
    --arg category "$category" \
    --argjson budget_vae "$budget" \
    --argjson estimated_seconds "$estimated_seconds" \
    --argjson max_workers "$max_workers" \
    --arg priority "$priority" \
    --arg webhook_url "$webhook_url" \
    '{
      title: $title,
      description: $description,
      category: $category,
      budget_vae: $budget_vae,
      estimated_seconds: $estimated_seconds,
      max_workers: $max_workers,
      priority: $priority
    } + (if $webhook_url != "" then {webhook_url: $webhook_url} else {} end)')

  local response
  response=$(api POST "/api/v1/tasks" -d "$payload")

  if echo "$response" | jq -e '.task_id' > /dev/null 2>&1; then
    echo "$response" | jq '{task_id: .task_id, status: .status, budget_vae: .budget_vae, budget_usd: .budget_usd}'
  else
    echo "Error creating task:"
    echo "$response" | jq '.' 2>/dev/null || echo "$response"
    exit 1
  fi
}

cmd_status() {
  local task_id=""
  while [[ $# -gt 0 ]]; do
    case "$1" in
      --task-id) task_id="$2"; shift 2 ;;
      *) echo "Unknown option: $1"; exit 1 ;;
    esac
  done
  [[ -z "$task_id" ]] && { echo "Error: --task-id is required"; exit 1; }

  api GET "/api/v1/tasks/$task_id" | jq '.'
}

cmd_wait() {
  local task_id="" interval=30 timeout=600
  while [[ $# -gt 0 ]]; do
    case "$1" in
      --task-id) task_id="$2"; shift 2 ;;
      --interval) interval="$2"; shift 2 ;;
      --timeout) timeout="$2"; shift 2 ;;
      *) echo "Unknown option: $1"; exit 1 ;;
    esac
  done
  [[ -z "$task_id" ]] && { echo "Error: --task-id is required"; exit 1; }

  local elapsed=0
  echo "Waiting for task $task_id (polling every ${interval}s, timeout ${timeout}s)..."

  while [[ $elapsed -lt $timeout ]]; do
    local response
    response=$(api GET "/api/v1/tasks/$task_id" 2>/dev/null || echo '{"status":"error"}')
    local status approved
    status=$(echo "$response" | jq -r '.status // "unknown"')
    approved=$(echo "$response" | jq -r '.progress.approved // 0')

    if [[ "$approved" -gt 0 ]]; then
      echo "✅ Task has approved submissions!"
      echo "$response" | jq '{task_id: .task_id, status: .status, submissions: .submissions}'
      return 0
    fi

    case "$status" in
      expired|cancelled)
        echo "Task $status."
        echo "$response" | jq '{task_id: .task_id, status: .status, progress: .progress}'
        return 1
        ;;
      *)
        echo "  [$elapsed/${timeout}s] Status: $status — approved: $approved"
        ;;
    esac

    sleep "$interval"
    elapsed=$((elapsed + interval))
  done

  echo "Timeout after ${timeout}s. Check later: loopuman.sh status --task-id $task_id"
  return 1
}

cmd_list() {
  api GET "/api/v1/tasks" | jq '.'
}

cmd_cancel() {
  local task_id=""
  while [[ $# -gt 0 ]]; do
    case "$1" in
      --task-id) task_id="$2"; shift 2 ;;
      *) echo "Unknown option: $1"; exit 1 ;;
    esac
  done
  [[ -z "$task_id" ]] && { echo "Error: --task-id is required"; exit 1; }

  api DELETE "/api/v1/tasks/$task_id" | jq '.'
}

# --- Main ---
case "${1:-help}" in
  create)  shift; cmd_create "$@" ;;
  status)  shift; cmd_status "$@" ;;
  wait)    shift; cmd_wait "$@" ;;
  list)    shift; cmd_list ;;
  cancel)  shift; cmd_cancel "$@" ;;
  help|--help|-h) usage ;;
  *) echo "Unknown command: $1"; usage; exit 1 ;;
esac


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)