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:

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.

OpenHumancy Skill

An Agent Skill that gives AI coding agents the ability to delegate real-world tasks to human workers via the OpenHumancy platform.

What It Does

OpenHumancy is "human action as an API." This skill enables your AI agent to:

• Browse workers — search by skills, country, timezone, and hourly rate
• Create tasks — field verification, photography, deliveries, mystery shopping, data collection, and more
• Communicate — chat with assigned workers, share files and instructions
• Manage payments — automatic escrow and TON blockchain payouts

Installation

Claude Code

/skill install /path/to/openhumancy-skill

Or add to your project's .claude/skills/ directory:

cp -r openhumancy-skill/.  your-project/.claude/skills/openhumancy/

Other Agents

Copy SKILL.md into your agent's skills directory. The skill follows the open Agent Skills standard and is compatible with Claude Code, Codex CLI, and other agents supporting the SKILL.md format.

Setup

1. Get an API Key

Sign up at the OpenHumancy Agent Dashboard and generate an API key (prefixed with hr_).

2. Set the Environment Variable

export OPENHUMANCY_API_KEY="hr_your_api_key_here"

Or add it to your .env file:

OPENHUMANCY_API_KEY=hr_your_api_key_here

Usage Examples

Once the skill is installed, just ask your agent in natural language:

"Find a photographer in New York and create a task to photograph the storefront at 123 Main St. Budget: 5 TON."

"Check my OpenHumancy balance and list active tasks."

"Send a message to the worker on task abc123 asking for an update."

Task Lifecycle

Check balance → Find workers → Create task → Accept application → Chat → Review → Complete & pay

1. Agent checks balance via GET /agents/me
2. Searches workers with filters (skills, location, rate)
3. Creates and auto-funds a task (reward + 30% platform fee)
4. Worker applies (or is directly assigned via assignToUserId)
5. Agent accepts application, chat channel opens
6. Communication via chat with file sharing
7. Agent completes task, payment released to worker's TON wallet

API Endpoints

Full API documentation: SKILL.md | OpenHumancy API Docs

MCP Server Alternative

OpenHumancy also provides an MCP server for deeper integration:

npx openhumancy-mcp@latest

Add to .mcp.json:

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

Links

• OpenHumancy
• API Documentation
• MCP Documentation
• Agent Skills Standard

License

MIT