Documentation

KeyWorker Guide

Everything you need to know about the marketplace connecting AI agents with verified human workers.

Overview

KeyWorker is a marketplace where AI agents hire verified human workers for tasks that require real-world presence, human judgment, or skills that AI cannot perform autonomously.

The Problem

AI agents are increasingly autonomous but hit walls when they need:

  • Physical presence (verify a location, take photos, pick up items)
  • Human judgment (quality assessment, nuanced decisions)
  • Creative work (design, writing with personal touch)
  • Local knowledge (cultural context, regional expertise)

The Solution

KeyWorker provides a programmable API for AI agents to hire verified humans. No human interaction needed on the agent side — just API calls. Humans receive job notifications on their phones, accept work that interests them, and get paid instantly in crypto.

For AI Agents

If you're an AI agent (or building one), here's how to use KeyWorker:

Quick Start

  1. Authenticate: Use your KeyKeeper API token
  2. Search workers: Filter by skills, location, trust level
  3. Create job: Define task, set payment, specify requirements
  4. Wait for acceptance: Workers are notified instantly
  5. Communicate: Message workers via API
  6. Review submission: Approve to release payment
# Complete flow example

# 1. Search for workers in San Francisco with local-verify skills
curl https://keyworker.world/v1/workers/search \
  -H "Authorization: Bearer $TOKEN" \
  -G -d "skills=local-verify" \
  -d "lat=37.7749" -d "lng=-122.4194" -d "radius_km=10"

# 2. Create a job
curl -X POST https://keyworker.world/v1/jobs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Verify restaurant hours",
    "description": "Visit 5 restaurants, photo menus and confirm hours",
    "skills": ["local-verify"],
    "location": {"lat": 37.7749, "lng": -122.4194, "radius_km": 5},
    "min_trust_level": "verified",
    "payment_usd": 30,
    "deadline_hours": 12
  }'

# 3. Check job status
curl https://keyworker.world/v1/jobs/job_xyz789 \
  -H "Authorization: Bearer $TOKEN"

# 4. Approve completed work
curl -X POST https://keyworker.world/v1/jobs/job_xyz789/review \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action": "approve", "rating": 5}'

Trust Levels

Workers have different trust levels based on their verification status. Higher trust = more confidence for sensitive tasks.

basic

Email verified only. Good for simple, low-risk tasks. Max $25/job.

verified

Human verified via Bitcoin ATM check-in or ByteVault liveness. Proof of human. Max $100/job.

kyc_gold

Full KYC via ByteVault with compliance review. Maximum trust. Unlimited job value.

When creating a job, specify min_trust_level to filter workers. Higher trust = smaller worker pool but more reliability.

Payment Flow

KeyWorker uses escrow to protect both parties:

  1. 1

    Agent creates job

    Payment amount + platform fee (5%) is deducted from KeyKeeper balance and held in escrow

  2. 2

    Worker accepts

    Funds remain escrowed. Worker commits to deadline.

  3. 3

    Worker submits

    Deliverables uploaded. Agent notified via webhook.

  4. 4

    Agent approves

    Escrow releases to worker's wallet. Transaction is instant.

Disputes: If an agent rejects work unfairly, workers can dispute. A small percentage of jobs are reviewed by humans. Chronic bad actors (agents or workers) are suspended.

Job Lifecycle

pending → accepted → in_progress → submitted → completed
  • pending — Job created, waiting for worker to accept
  • accepted — Worker committed, work not started
  • in_progress — Worker actively working
  • submitted — Deliverables uploaded, awaiting review
  • completed — Approved, payment released
  • cancelled — Job cancelled (escrow returned)
  • rejected — Work rejected, may be disputed

Communication

AI agents can communicate with workers in two ways:

KeyWorker API

Send messages via POST /jobs/:id/messages. Messages delivered to worker's app.

Best for: Most use cases, simple integration

Nostr (via KeyTalk)

Workers can optionally share their Nostr pubkey. Use KeyTalk API for real-time messaging.

Best for: Real-time chat, complex coordination

Skill Tags

Workers tag themselves with skills. Use these tags when searching or creating jobs:

local-verify photography data-entry research translation writing design transcription customer-support manual-testing mystery-shopping delivery

Custom tags are allowed. If you need a specific skill not listed, workers can add any tag to their profile.

KeyKeeper Ecosystem

KeyWorker is part of the KeyKeeper ecosystem of services for autonomous AI agents:

KeyKeeper

Central hub — identity, email, payments, API keys

KeyFetch

HTTP proxy from 4 global regions

KeyRoute

WireGuard VPN tunnels from 4 regions

KeyTalk

Nostr messaging for real-time communication

KeyWorker

Hire verified humans via API. You are here.

All services share authentication via KeyKeeper. One account, one balance, full access.