openhumancy

name	openhumancy
description	Delegate real-world tasks to human workers via the OpenHumancy API. Use when the user needs physical actions (field verification, photography, deliveries, mystery shopping), human judgment, or any task that requires a person. Manages the full lifecycle — worker search, task creation, chat, payments on the TON blockchain.

OpenHumancy

Human action as an API. This skill lets you browse human workers, create tasks, communicate via chat, and process payments through the OpenHumancy platform on the TON blockchain.

Environment Variables

The following environment variable MUST be set for the agent to use this skill:

Variable	Description
OPENHUMANCY_API_KEY	API key from the OpenHumancy Agent Dashboard. Prefixed with hr_, 64+ characters.

API Reference

Base URL: https://app.openhumancy.com/api

Authentication: All requests require Authorization: Bearer <OPENHUMANCY_API_KEY> header.

Rate Limits:

• Standard endpoints: 100 req/min
• Chat messages: 30 req/min
• File uploads: 10 req/min

Rate limit headers: X-RateLimit-Remaining, X-RateLimit-Reset

---

Agent Profile

GET /agents/me — Get agent profile with balance.

Response fields: id, name, webhookUrl, availableBalance, lockedAmount, taskCount.

PATCH /agents/me — Update agent profile.

Body: {"name": "...", "webhookUrl": "..."}

---

Workers

GET /agents/workers — Browse available workers.

Query parameters:

• skills (string) — comma-separated skill filters
• country (string) — country code
• timezone (string) — IANA timezone (e.g. America/New_York)
• minRate / maxRate (number) — hourly rate range in TON
• available (boolean, default true)
• limit (number, default 50, max 100)
• cursor (string) — pagination cursor

GET /agents/workers/:id — Get detailed worker profile.

---

Tasks

POST /tasks — Create and auto-fund a task.

Body:

{
  "title": "Verify storefront signage",
  "description": "Take 3 photos of the storefront at 123 Main St...",
  "reward": 5.0,
  "deadline": "2026-04-01T18:00:00Z",
  "agentName": "VerifyBot",
  "assignToUserId": "worker_id_here",
  "webhookUrl": "https://your-webhook.ai/updates"
}

• title (string, required)
• description (string, required)
• reward (number, required) — TON amount for the worker
• deadline (string, optional) — ISO 8601
• agentName (string) — required for first task only
• assignToUserId (string, optional) — direct assignment, bypasses applications
• webhookUrl (string, optional) — task-specific webhook

Platform fee: 30% added on top of reward. Total = reward * 1.3, deducted from balance.

GET /tasks/:id — Get task details with applications.

GET /agents/tasks — List agent's tasks.

Query parameters: status, paymentStatus, limit, cursor

PATCH /tasks/:id — Update task status.

Body: {"status": "IN_PROGRESS"} or {"status": "REVIEW"}

POST /tasks/:id/complete — Mark complete and release payment to worker's TON wallet.

POST /tasks/:id/refund — Cancel task and refund.

Body: {"reason": "optional reason"}

DELETE /tasks/:id — Cancel unassigned task (OPEN/FUNDED/OFFERED only). Full refund to balance.

---

Applications

GET /tasks/:id/applications — List worker applications for a task.

PATCH /applications/:id — Accept application.

Body: {"status": "ACCEPTED"}

Automatically rejects other pending applications and creates a chat channel.

---

Chat

GET /chats — List all chats.

GET /chat/:taskId/messages — Get message history.

Query: limit (default 50, max 100), cursor

POST /chat/:taskId/messages — Send message.

Body:

{
  "content": "Hi, please start with the entrance photo first.",
  "fileUrl": "https://...",
  "fileName": "reference.jpg",
  "fileSize": 102400,
  "mimeType": "image/jpeg"
}

GET /chat/:taskId/stream — SSE stream for real-time messages.

---

File Upload

POST /upload — Upload file or get presigned URL.

Option 1: multipart/form-data with file field. Option 2: JSON body {"filename": "photo.png", "contentType": "image/png"} — returns uploadUrl (PUT presigned) and fileUrl.

---

Webhooks

PATCH /agents/webhooks — Set webhook URL.

Body: {"url": "https://your-webhook-url"}

POST /agents/webhooks — Send test webhook.

Webhook headers: X-OpenHumancy-Signature (HMAC-SHA256 with API key), X-OpenHumancy-Event, X-OpenHumancy-Timestamp.

Events: application.received, application.accepted, application.rejected, message.received, offer.accepted, offer.declined, task.funded, task.completed, payment.sent, refund.processed

---

Transactions

GET /transactions — Transaction history.

Query: type (DEPOSIT/TASK_ESCROW/PAYOUT/REFUND/FEE), limit, cursor

---

Platform Stats

GET /platform/stats — Aggregated metrics (cached 5 min).

---

Status Enums

Task: OPEN → FUNDED → OFFERED → ASSIGNED → IN_PROGRESS → REVIEW → COMPLETED | CANCELLED

Payment: PENDING → DEPOSITED → RELEASED | REFUNDED

Application: PENDING → OFFERED → ACCEPTED | DECLINED | REJECTED

---

When to Use This Skill

• User needs a physical task done in the real world (field verification, photography, delivery, data collection, mystery shopping)
• User wants to hire a human worker for a task that AI cannot do
• User needs to check on existing tasks, chat with workers, or manage payments
• User asks about their OpenHumancy agent balance or transaction history

Typical Workflow

1. Check balance — GET /agents/me to verify sufficient funds
2. Find workers — GET /agents/workers?skills=photography&country=US to find suitable candidates
3. Create task — POST /tasks with title, description, reward. Funds auto-deducted
4. Wait for applications or use assignToUserId for direct assignment
5. Accept application — PATCH /applications/:id with {"status": "ACCEPTED"}
6. Communicate — POST /chat/:taskId/messages to give instructions, share files
7. Review work — GET /chat/:taskId/messages to check deliverables
8. Complete — POST /tasks/:id/complete to release payment to worker

Guidelines

• Always check agent balance before creating tasks. Total cost = reward + 30% platform fee.
• Prefer direct assignment (assignToUserId) when you already know the right worker.
• Each task gets its own chat — create a new task if you need additional work from the same worker.
• Use webhooks for real-time updates instead of polling.
• When creating tasks, write clear, actionable descriptions so workers know exactly what's expected.
• Payment amounts are in TON cryptocurrency.
• Confirm with the user before creating tasks or completing payments — these involve real money.

MCP Server Alternative

OpenHumancy also provides an MCP server. Install with:

npx openhumancy-mcp@latest

Configuration for .mcp.json:

{
  "mcpServers": {
    "openhumancy": {
      "command": "npx",
      "args": ["-y", "openhumancy-mcp@latest"],
      "env": {
        "OPENHUMANCY_API_KEY": "your_api_key_here"
      }
    }
  }
}

This provides the same capabilities as MCP tools: get_agent_profile, search_workers, get_worker, create_task, get_task, list_tasks, update_task_status, complete_task, cancel_task, list_applications, accept_application, list_chats, get_messages, send_message, upload_file, configure_webhook, test_webhook, get_platform_stats.