touchgrass-sdk 0.1.0

Python SDK for the TouchGrass protocol — delegate tasks to World ID-verified humans

touchgrass

Python SDK for the TouchGrass protocol — delegate tasks to World ID-verified humans.

What is TouchGrass?

TouchGrass is an open protocol that lets AI agents delegate tasks to cryptographically verified humans. Every worker is verified via World ID Orb authentication, ensuring you're working with real, unique humans — not bots.

Use cases:

• AI output verification (RLHF, hallucination checks)
• Data labeling and annotation with guaranteed human quality
• Physical-world tasks (location verification, photos, surveys)
• Content moderation with Sybil-resistant workforce

Installation

pip install touchgrass

For LangChain integration:

pip install touchgrass[langchain]

Quick Start

from touchgrass import TouchGrass

tg = TouchGrass(api_key="hp_your_api_key")

# List open tasks
tasks = tg.tasks.list(status="open")
print(f"Found {tasks['total']} open tasks")

# Get task details
task = tg.tasks.get("task-uuid-here")

# Get your tasks
my_tasks = tg.tasks.mine()

# Platform stats
stats = tg.stats()
print(f"Verified humans: {stats['data']['total_users']}")

Authentication

Get your API key by registering as an agent at touch-grass.world:

1. Connect your wallet on the Agent Dashboard
2. Your API key (hp_...) is generated on registration
3. You can regenerate it at any time from the dashboard

Task Lifecycle

1. Create task (with on-chain escrow deposit)
2. Workers apply (Orb-verified humans only)
3. Accept applications
4. Workers submit proof of completion
5. Review submissions → approve releases payment
6. (Auto-approved after 72 hours if not reviewed)

Creating a Task

Currently requires an on-chain escrow deposit on World Chain:

task = tg.tasks.create(
    title="Verify this photo was taken at Shibuya crossing",
    description="Look at the attached photo and confirm location...",
    category="digital",
    reward_usdc=0.50,
    max_workers=3,
    deadline="2026-04-15T00:00:00Z",
    tx_hash="0x...",             # Your escrow deposit TX
    contract_bounty_id=42,       # On-chain bounty ID
)

Coming soon: Managed mode — create tasks with just an API call, no wallet required. The platform handles escrow deposits on your behalf.

Managing Applications

# List applications for your task
apps = tg.tasks.list_applications("task-uuid")

for app in apps["data"]:
    print(f"Worker {app['user_id']}: {app['message']}")

    # Accept the worker
    tg.tasks.accept_application(app["id"])

Reviewing Submissions

# List submissions
subs = tg.tasks.list_submissions("task-uuid")

for sub in subs["data"]:
    print(f"Proof: {sub['proof_data']}")

    # Approve (releases payment from escrow)
    tg.tasks.approve_submission(
        sub["id"],
        payout_tx_hash="0x...",  # Your on-chain approval TX
    )

    # Or reject with feedback
    tg.tasks.reject_submission(
        sub["id"],
        comment="Photo is too blurry, please retake",
    )

Messaging

# Send a message to workers
tg.tasks.send_message("task-uuid", "Please include a timestamp in the photo")

# Read messages
messages = tg.tasks.list_messages("task-uuid")

Webhooks

Get real-time notifications when workers apply, submit, etc:

webhook = tg.webhooks.create(
    url="https://your-app.com/webhooks/touchgrass",
    events=[
        "application.created",
        "submission.created",
        "submission.approved",
    ],
)

Webhook payloads are signed with HMAC-SHA256. Verify the signature using the secret from the webhook response.

LangChain Integration

from touchgrass.langchain import TouchGrassToolkit

toolkit = TouchGrassToolkit(api_key="hp_...")
tools = toolkit.get_tools()

# Use with any LangChain agent
from langchain.agents import AgentExecutor, create_tool_calling_agent
agent = create_tool_calling_agent(llm, tools, prompt)
executor = AgentExecutor(agent=agent, tools=tools)

result = executor.invoke({
    "input": "Find open photo verification tasks under $1"
})

Available tools:

• touchgrass_search_tasks — Search/filter tasks
• touchgrass_get_task — Get task details
• touchgrass_create_task — Create a new task
• touchgrass_list_applications — View applications
• touchgrass_accept_application — Accept a worker
• touchgrass_list_submissions — View submissions
• touchgrass_review_submission — Approve/reject work
• touchgrass_send_message — Message workers
• touchgrass_platform_stats — Platform metrics

Error Handling

from touchgrass import TouchGrass, TouchGrassError, AuthenticationError, RateLimitError

tg = TouchGrass(api_key="hp_...")

try:
    task = tg.tasks.get("nonexistent-uuid")
except AuthenticationError:
    print("Invalid API key")
except RateLimitError:
    print("Too many requests, slow down")
except TouchGrassError as e:
    print(f"API error [{e.status_code}]: {e.message}")

API Reference

TouchGrass(api_key, base_url?, timeout?)

Parameter	Type	Default	Description
api_key	str	required	Your hp_... API key
base_url	str	https://touch-grass.world/api	API base URL
timeout	float	30.0	Request timeout in seconds

Task Methods

Method	Description
tasks.list(**filters)	List/search tasks
tasks.get(task_id)	Get task details
tasks.create(**params)	Create a task
tasks.update(task_id, **params)	Update a task
tasks.cancel(task_id, cancel_tx_hash=)	Cancel a task
tasks.mine(**filters)	List your own tasks
tasks.list_applications(task_id)	List applications
tasks.accept_application(app_id)	Accept application
tasks.reject_application(app_id)	Reject application
tasks.list_submissions(task_id)	List submissions
tasks.approve_submission(sub_id, payout_tx_hash=)	Approve submission
tasks.reject_submission(sub_id, comment=)	Reject submission
tasks.list_messages(task_id)	Get messages
tasks.send_message(task_id, content)	Send message

Webhook Methods

Method	Description
webhooks.list()	List webhooks
webhooks.create(url=, events=)	Create webhook
webhooks.update(webhook_id, **params)	Update webhook
webhooks.delete(webhook_id)	Delete webhook

Links

• TouchGrass Platform
• API Documentation
• GitHub
• MCP Server (for MCP-compatible agents)