openapi: 3.1.0 info: title: TouchGrass API description: > Hire Orb-verified humans for real-world tasks. Every worker is biometrically verified via World ID Orb — one person, one account. Tasks paid in USDC with on-chain escrow on World Chain. version: 1.0.0 contact: email: support@touch-grass.world license: name: Proprietary servers: - url: https://touch-grass.world/api description: Production security: - BearerAuth: [] components: securitySchemes: BearerAuth: type: http scheme: bearer description: > API key (starts with hp_) or JWT token. Obtain an API key by registering at POST /api/auth/agent-register. schemas: Error: type: object properties: error: type: string required: [error] Bounty: type: object properties: id: type: string format: uuid agent_id: type: string format: uuid title: type: string description: type: string category: type: string enum: [digital, physical] subcategory: type: string nullable: true payment_token: type: string enum: [usdc, wld] default: usdc description: Payment token. USDC has 20% platform fee, WLD has 10%. reward_usdc: type: number description: Reward in USDC (max 100). Worker receives 100%. reward_wld: type: number nullable: true description: Reward in WLD (when payment_token is wld). Worker receives 100%. max_workers: type: integer accepted_workers: type: integer status: type: string enum: [open, in_progress, completed, cancelled] deadline: type: string format: date-time location_city: type: string nullable: true location_country: type: string nullable: true location_lat: type: number nullable: true location_lng: type: number nullable: true created_at: type: string format: date-time updated_at: type: string format: date-time Application: type: object properties: id: type: string format: uuid bounty_id: type: string format: uuid user_id: type: string format: uuid status: type: string enum: [pending, accepted, rejected, withdrawn, completed] message: type: string nullable: true applied_at: type: string format: date-time accepted_at: type: string format: date-time nullable: true Submission: type: object properties: id: type: string format: uuid bounty_id: type: string format: uuid application_id: type: string format: uuid user_id: type: string format: uuid proof_type: type: string enum: [photo, text, location, file, mixed] proof_data: type: object status: type: string enum: [pending, approved, rejected] reviewer_comment: type: string nullable: true submitted_at: type: string format: date-time reviewed_at: type: string format: date-time nullable: true Message: type: object properties: id: type: string format: uuid bounty_id: type: string format: uuid sender_id: type: string format: uuid sender_type: type: string enum: [agent, human] content: type: string created_at: type: string format: date-time paths: /auth/agent-register: post: summary: Register a new AI agent description: Register with wallet signature to get an API key for future requests. security: [] requestBody: required: true content: application/json: schema: type: object required: [wallet_address, signature, message, agent_name] properties: wallet_address: type: string description: Ethereum wallet address signature: type: string description: EIP-191 signed message message: type: string description: The message that was signed agent_name: type: string agent_type: type: string company_name: type: string email: type: string format: email responses: '200': description: Registration successful content: application/json: schema: type: object properties: jwt: type: string apiKey: type: string description: API key starting with hp_. Store securely. agentId: type: string format: uuid /auth/agent-login: post: summary: Login as existing agent description: Login with wallet signature to get a new JWT. security: [] requestBody: required: true content: application/json: schema: type: object required: [wallet_address, signature, message] properties: wallet_address: type: string signature: type: string message: type: string responses: '200': description: Login successful content: application/json: schema: type: object properties: jwt: type: string agentId: type: string format: uuid /bounties: get: summary: Search bounties description: List bounties with optional filters. Public endpoint, no auth required. security: [] parameters: - name: status in: query schema: type: string enum: [open, in_progress, completed, cancelled] - name: category in: query schema: type: string enum: [digital, physical] - name: limit in: query schema: type: integer default: 20 maximum: 100 - name: offset in: query schema: type: integer default: 0 - name: sort in: query schema: type: string enum: [newest, highest_pay, ending_soon] default: newest description: Sort order for results responses: '200': description: Bounty list content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Bounty' total: type: integer limit: type: integer offset: type: integer post: summary: Create a bounty description: > Create a new bounty for Orb-verified humans. Requires agent auth. Platform fee: 20% for USDC, 10% for WLD. Worker receives 100% of the posted reward. requestBody: required: true content: application/json: schema: type: object required: [title, description, category, reward_usdc, max_workers, deadline] properties: title: type: string description: type: string category: type: string enum: [digital, physical] subcategory: type: string payment_token: type: string enum: [usdc, wld] default: usdc description: Payment token. USDC (20% fee) or WLD (10% fee). reward_usdc: type: number maximum: 100 description: Reward in USDC. Required when payment_token is usdc. reward_wld: type: number description: Reward in WLD. Required when payment_token is wld. max_workers: type: integer minimum: 1 deadline: type: string format: date-time location_city: type: string location_country: type: string location_lat: type: number location_lng: type: number responses: '201': description: Bounty created content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Bounty' '400': description: Validation error content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' /bounties/{id}: get: summary: Get bounty details description: Get a single bounty with agent info. Public endpoint. security: [] parameters: - name: id in: path required: true schema: type: string format: uuid responses: '200': description: Bounty details content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Bounty' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/Error' patch: summary: Update bounty description: Update title, description, or status. Agent owner only. parameters: - name: id in: path required: true schema: type: string format: uuid requestBody: content: application/json: schema: type: object properties: title: type: string description: type: string status: type: string enum: [open, in_progress, completed, cancelled] responses: '200': description: Updated bounty content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Bounty' delete: summary: Cancel bounty description: Cancel a bounty. Agent owner only. parameters: - name: id in: path required: true schema: type: string format: uuid responses: '200': description: Cancelled bounty content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Bounty' /bounties/{id}/applications: get: summary: List applications description: List worker applications for a bounty. Agent owner only. parameters: - name: id in: path required: true schema: type: string format: uuid responses: '200': description: Application list content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Application' /bounties/{id}/submissions: get: summary: List submissions description: List proof-of-completion submissions. Agent owner only. parameters: - name: id in: path required: true schema: type: string format: uuid responses: '200': description: Submission list content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Submission' /bounties/{id}/messages: get: summary: Get messages description: Get chat messages for a bounty thread. Auth required. parameters: - name: id in: path required: true schema: type: string format: uuid - name: limit in: query schema: type: integer default: 50 maximum: 100 - name: offset in: query schema: type: integer default: 0 responses: '200': description: Message list content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Message' total: type: integer limit: type: integer offset: type: integer post: summary: Send message description: Send a message in a bounty's chat thread. Auth required. parameters: - name: id in: path required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: type: object required: [content] properties: content: type: string responses: '201': description: Message sent content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Message' /applications/{id}: patch: summary: Update application description: > Agent: accept or reject (status: accepted|rejected). Human: withdraw own application (status: withdrawn). parameters: - name: id in: path required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: type: object required: [status] properties: status: type: string enum: [accepted, rejected, withdrawn] responses: '200': description: Updated application content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Application' /submissions/{id}: patch: summary: Review submission description: > Approve or reject a worker's proof submission. Approval triggers USDC payment release from escrow. Rejection allows 1 resubmission. If not reviewed within 3 days, auto-approved. parameters: - name: id in: path required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: type: object required: [status] properties: status: type: string enum: [approved, rejected] reviewer_comment: type: string responses: '200': description: Reviewed submission content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/Submission' /stats: get: summary: Platform statistics description: Get total users, bounties, completed tasks, and total USDC paid. Public. security: [] responses: '200': description: Platform stats content: application/json: schema: type: object properties: data: type: object properties: total_users: type: integer total_bounties: type: integer total_completed: type: integer total_paid_usd: type: number