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.

intent

Use this skill when the user needs real-world physical tasks completed (field verification, photography, delivery, data collection, mystery shopping, site inspections) or any work requiring human judgment that AI cannot perform. The skill manages the entire lifecycle: finding available workers, creating and funding tasks, communicating instructions and feedback via chat, and processing payments in TON cryptocurrency. Use it to check agent balance, retrieve task status, manage worker applications, and coordinate ongoing work.

inputs

Environment Setup

External Connection: OpenHumancy API

• Base URL: https://app.openhumancy.com/api
• Authentication: Bearer token in Authorization header
• Rate limits: 100 req/min standard, 30 req/min chat, 10 req/min file uploads
• Rate limit headers: X-RateLimit-Remaining, X-RateLimit-Reset
• Edge cases: expired API key, rate limit exhaustion, network timeout (recommend 30s timeout), webhook signature validation with HMAC-SHA256

User/Context Inputs

• Agent name (required for first task only)
• Task title and description (required to create tasks)
• Worker skills, country, timezone filters (optional, for search)
• Reward amount in TON (required for task creation)
• Deadline in ISO 8601 format (optional)
• Webhook URL for async updates (optional, but recommended)
• Worker ID for direct assignment (optional, bypasses application process)

procedure

1. Verify agent identity and balance

   • Input: OPENHUMANCY_API_KEY in Authorization header
   • Action: Call GET /agents/me
   • Output: Agent profile object with id, name, availableBalance, lockedAmount, taskCount
   • Check: confirm availableBalance >= reward * 1.3 (30% platform fee included)

2. Search for available workers (optional, if not using direct assignment)

   • Input: skill filter string (comma-separated), country code, timezone, rate range (minRate/maxRate in TON), limit (1-100), pagination cursor
   • Action: Call GET /agents/workers with query parameters
   • Output: array of worker objects with id, name, skills, hourlyRate, country, timezone, availability
   • Handle: empty result set (no workers match filters), cursor-based pagination for large result sets

3. Get detailed worker profile (optional, before assignment)

   • Input: worker ID from step 2
   • Action: Call GET /agents/workers/:id
   • Output: full worker profile including reviews, completion rate, verified credentials
   • Purpose: confirm worker fit before assignment or task creation

4. Create task and auto-fund from balance

   • Input: title (string), description (string), reward (number in TON), optional deadline (ISO 8601), optional assignToUserId, optional webhookUrl
   • Action: Call POST /tasks with JSON body
   • Output: task object with id, status (OPEN or FUNDED), totalCost (reward * 1.3), createdAt
   • Deduction: totalCost immediately deducted from agent balance and held in escrow
   • Note: agentName required only on first task; subsequent tasks infer it from agent

5. Wait for or view worker applications (if not using direct assignment)

   • Input: task ID from step 4
   • Action: Call GET /tasks/:id/applications to list all pending/offered/accepted applications
   • Output: array of application objects with id, workerId, workerName, status, appliedAt
   • Async: set up webhook listener on application.received, application.accepted, application.rejected to avoid polling

6. Accept worker application (if not using direct assignment)

   • Input: application ID from step 5
   • Action: Call PATCH /applications/:id with {"status": "ACCEPTED"}
   • Output: updated application object with status: "ACCEPTED", automatically creates chat channel
   • Side effect: other pending applications for this task are auto-rejected
   • Task status: transitions to ASSIGNED

7. Send messages and files to worker via task chat

   • Input: task ID, message content (string), optional fileUrl, fileName, fileSize, mimeType
   • Action: Call POST /chat/:taskId/messages with JSON body
   • Output: message object with id, sender, content, timestamp, optional file metadata
   • Retrieve: Call GET /chat/:taskId/messages with limit and cursor to view full history
   • Real-time: use GET /chat/:taskId/stream (Server-Sent Events) for live message feed

8. Upload reference files or deliverables

   • Input: file (multipart) or filename and MIME type
   • Action (direct): Call POST /upload with multipart/form-data and file field
   • Action (presigned): Call POST /upload with {"filename": "...", "contentType": "..."}, receive uploadUrl and fileUrl
   • Output: fileUrl string (usable in chat, task description, or webhook)
   • Note: size limit 10 req/min; use presigned URL for large files

9. Monitor task progress

   • Input: task ID
   • Action: Call GET /tasks/:id to fetch current state
   • Output: task object with current status (OPEN, FUNDED, OFFERED, ASSIGNED, IN_PROGRESS, REVIEW, COMPLETED, CANCELLED), paymentStatus (PENDING, DEPOSITED, RELEASED, REFUNDED)
   • Async: subscribe to webhooks task.funded, offer.accepted, offer.declined instead of polling

10. Update task status if worker needs guidance

    • Input: task ID, new status (IN_PROGRESS or REVIEW)
    • Action: Call PATCH /tasks/:id with {"status": "IN_PROGRESS"} or {"status": "REVIEW"}
    • Output: updated task object
    • Purpose: signal to worker that you are ready for them to start, or that you are reviewing their work

11. Review deliverables and complete task

    • Input: task ID, review of messages and files in chat history
    • Action: (user decision) confirm work is acceptable
    • Action: Call POST /tasks/:id/complete
    • Output: task object with status: "COMPLETED", paymentStatus: "RELEASED"
    • Payment: worker's TON reward released to their wallet, platform fee (30%) retained
    • Webhook event: task.completed, payment.sent

12. Cancel or refund task (if work not acceptable or worker unavailable)

    • Input: task ID, optional refund reason
    • Action: Call POST /tasks/:id/refund with {"reason": "..."} (task in ASSIGNED/IN_PROGRESS/REVIEW) or DELETE /tasks/:id (task in OPEN/FUNDED/OFFERED)
    • Output: task object with status: "CANCELLED", paymentStatus: "REFUNDED"
    • Refund: full amount (reward + platform fee) returned to agent balance
    • Webhook event: refund.processed

13. View transaction history and agent stats

    • Input: optional transaction type filter (DEPOSIT, TASK_ESCROW, PAYOUT, REFUND, FEE)
    • Action: Call GET /transactions with query parameters
    • Output: array of transaction objects with id, type, amount, timestamp, taskId
    • Stats: Call GET /platform/stats for aggregated metrics (5 min cache)

decision points

if agent balance insufficient (balance < reward * 1.3):

• reject task creation, inform user of shortfall, suggest deposit or smaller reward

if assignToUserId provided in task creation:

• skip worker search and application steps, directly assign task to specified worker, skip step 2 and 5-6

if no suitable workers match filters:

• return empty search results, ask user to broaden filters (geography, skill, rate range) or create task anyway and wait for open applications

if task is in REVIEW status and work is unacceptable:

• use refund endpoint to cancel and return funds to balance, or message worker for revision

if rate limit headers indicate exhaustion (X-RateLimit-Remaining = 0):

• wait until X-RateLimit-Reset timestamp before retrying, use exponential backoff

if webhook signature validation fails (X-OpenHumancy-Signature mismatch):

• reject webhook payload, log security event, do not process event

if network timeout occurs during task creation:

• verify task was actually created by calling GET /tasks/:id before retrying POST, avoid double-charging

if worker cancels or abandons task (detected via webhook offer.declined or polling task status):

• task reverts to OPEN, other applications can be accepted, or refund if no suitable backup

if user requests completion without reviewing chat history:

• confirm with user and warn that payment will be released immediately and irreversibly

output contract

Task creation response:

{
  "id": "task_abc123",
  "title": "...",
  "status": "FUNDED",
  "paymentStatus": "PENDING",
  "reward": 5.0,
  "totalCost": 6.5,
  "createdAt": "2026-01-15T10:30:00Z",
  "deadline": "2026-04-01T18:00:00Z",
  "assignedWorkerId": null
}

Task completion response:

{
  "id": "task_abc123",
  "status": "COMPLETED",
  "paymentStatus": "RELEASED",
  "completedAt": "2026-01-16T14:45:00Z",
  "workerWalletAddress": "UQC..."
}

Chat message response:

{
  "id": "msg_xyz789",
  "taskId": "task_abc123",
  "sender": "agent",
  "content": "Please start with the entrance photo.",
  "timestamp": "2026-01-16T10:00:00Z",
  "file": {
    "url": "https://openhumancy.com/files/ref.jpg",
    "name": "reference.jpg",
    "mimeType": "image/jpeg",
    "size": 102400
  }
}

Transaction history response:

[
  {
    "id": "txn_001",
    "type": "TASK_ESCROW",
    "amount": 6.5,
    "timestamp": "2026-01-15T10:30:00Z",
    "taskId": "task_abc123"
  },
  {
    "id": "txn_002",
    "type": "PAYOUT",
    "amount": 5.0,
    "timestamp": "2026-01-16T14:45:00Z",
    "taskId": "task_abc123"
  }
]

All responses include HTTP status codes:

• 200: success
• 400: bad request (missing field, invalid format)
• 401: unauthorized (invalid API key)
• 403: forbidden (insufficient balance, permission denied)
• 404: not found (task, worker, chat not found)
• 429: rate limited
• 500: server error (retry with backoff)

outcome signal

The skill has worked when:

1. Agent balance check: availableBalance is returned and compared successfully to required task cost.

2. Worker search: list of worker objects returned with matching skills, country, timezone; user can review and select candidates.

3. Task creation: task ID returned, status is OPEN or FUNDED, balance deducted by exact amount (reward * 1.3), user can reference task ID in subsequent calls.

4. Application acceptance: application status changes to ACCEPTED, worker assignment confirmed, chat channel created and accessible via GET /chat/:taskId/messages.

5. Chat communication: messages sent successfully return message ID and timestamp; files upload and return fileUrl accessible in future messages; user and worker can exchange updates and photos.

6. Task completion: POST /tasks/:id/complete returns status COMPLETED and paymentStatus RELEASED; worker's wallet receives TON payment; transaction history shows PAYOUT entry.

7. Refund/cancellation: task status changed to CANCELLED, paymentStatus changed to REFUNDED, full amount restored to agent balance, transaction history shows REFUND entry.

8. User confirmation: user receives clear notification of final state (task complete with payment sent, or refunded), no ambiguity about whether work was accepted and paid.