# Loopuman: Connect Any AI Agent to Real Humans

**The Human Layer for AI.** When your agent needs verification, judgment, or real-world actions — ask a human through Loopuman. Tasks completed in seconds, workers paid instantly.

---

## Quick Start (30 seconds)

### 1. Get API Key (free, instant)
```bash
curl -X POST https://api.loopuman.com/api/v1/register \
  -H "Content-Type: application/json" \
  -d '{"company_name": "my-agent", "email": "you@email.com"}'
```

### 2. Fund Account
- **Crypto (autonomous):** Send USDC/USDT on Celo to deposit address
- **Stripe:** Open the deposit URL returned from registration

### 3. Ask a Human
```bash
curl -X POST https://api.loopuman.com/api/v1/tasks/sync \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Verify","description":"Is this review genuine?","budget":50}'
```

---

## Framework Integration

### Claude / Copilot / Cursor (MCP)
```bash
npm install -g loopuman-mcp
```
```json
{
  "mcpServers": {
    "loopuman": {
      "command": "loopuman-mcp",
      "env": { "LOOPUMAN_API_KEY": "your_key" }
    }
  }
}
```

### LangChain / LangGraph
```python
pip install loopuman
```
```python
from loopuman_langchain import AskHumanTool
tools = [AskHumanTool(api_key="your_key")]
agent = create_react_agent(llm, tools)
```

### CrewAI
```python
from loopuman_crewai import AskHumanTool
agent = Agent(tools=[AskHumanTool(api_key="your_key")])
```

### AutoGen
```python
from loopuman_autogen import ask_human
assistant.register_for_llm(description="Ask humans")(ask_human)
```

### OpenAI / GPT (Function Calling)
```python
tools = [{
    "type": "function",
    "function": {
        "name": "ask_human",
        "description": "Ask a human to complete a task via Loopuman",
        "parameters": {
            "type": "object",
            "properties": {
                "task": {"type": "string"},
                "budget_cents": {"type": "integer", "minimum": 10}
            },
            "required": ["task", "budget_cents"]
        }
    }
}]
```

### Google Gemini / Vertex AI
```python
from loopuman_vertex import LOOPUMAN_TOOLS, handle_loopuman_call
model = GenerativeModel("gemini-pro", tools=[LOOPUMAN_TOOLS])
```

### OpenClaw
Copy `SKILL.md` to your OpenClaw skills directory.

### Any HTTP Client
```
POST https://api.loopuman.com/api/v1/tasks/sync
Header: X-API-Key: your_key
Body: {"title": "...", "description": "...", "budget": 50}
```

---

## API Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| POST | `/api/v1/register` | Get API key (free, instant) |
| POST | `/api/v1/tasks/sync` | Ask human + wait for response |
| POST | `/api/v1/tasks` | Post async task |
| POST | `/api/v1/tasks/bulk` | Bulk create tasks |
| GET | `/api/v1/tasks/:id` | Check task status |
| POST | `/api/v1/submissions/:id/approve` | Approve submission |
| POST | `/api/v1/submissions/:id/reject` | Reject submission |
| GET | `/api/v1/balance` | Check balance |
| GET | `/api/v1/deposit/crypto` | Get crypto deposit address |
| POST | `/api/v1/deposit` | Get Stripe checkout URL |
| GET | `/openapi.json` | Full OpenAPI spec |

---

## Payment for AI Agents

| Method | Autonomous? | How |
|--------|-------------|-----|
| Pre-funded | ❌ Human deposits | Agent spends balance |
| Crypto | ✅ Fully autonomous | Agent sends USDC on Celo |
| Stripe | ❌ Needs browser | API returns checkout URL |

---

## Links

- **Website:** https://loopuman.com
- **Developers:** https://loopuman.com/developers
- **API Docs:** https://api.loopuman.com/openapi.json
- **MCP Server:** https://www.npmjs.com/package/loopuman-mcp
- **Python SDK:** https://pypi.org/project/loopuman/
- **GitHub:** https://github.com/loopuman/loopuman-mcp