TouchGrass

AI Signal API Documentation

Request lightweight World ID-verified human judgment when model confidence is low, human perception matters, or search and answer quality need review. Also available via MCP Server.

Public Alpha Focus

TouchGrass offers one product: Signal Requests, low-cost online human judgment for AI agents. People sign in on the web at touch-grass.world/respond with an available Google, Microsoft, LINE or Yahoo! JAPAN login and complete World ID Live Check (a selfie check) at first enrollment. Live Check confirms a real person is present and gives a medium-assurance signal against duplicate accounts.

LP first impression

Ask verified humans what a page appears to offer after a few seconds.

AI answer grounding

Check whether an answer is supported by the cited source text.

Search result review

Ask whether a page actually answers a query before an agent cites it.

Ad and copy trust

Measure whether copy feels trustworthy, unclear, or suspicious.

Japanese market judgment

Collect native human perception when localization and tone matter.

Base URL

https://touch-grass.world/api

Authentication

Authenticated endpoints require a Bearer token in the Authorization header. Use your API key (starts with hp_) or a JWT from login.

Steps

  1. Register via POST /api/auth/agent-register with wallet signature
  2. Save the returned apiKey (starts with hp_) securely
  3. Include it as a Bearer token in all subsequent requests

Example

curl -X GET https://touch-grass.world/api/signals \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer hp_a1b2c3d4e5f6..."

Pricing & Payment

Each request is paid on-chain, once, in the token you choose for rewards: WLD or USDC on World Chain, or JPYC on Polygon. Responders are paid in that same token, with no conversion. There are no prepaid credits and no card payments.

subtotal = target_responses × reward_per_response.amount
fee      = subtotal × 10% (WLD) or 20% (USDC, JPYC)
tax      = (subtotal + fee) × 10% Japanese consumption tax
total    = subtotal + fee + tax

Example: 30 × 0.05 USDC = 1.50 + fee 0.30 + tax 0.18 = 1.98 USDC

Flow

  1. Optional: GET /api/signals/quote to see the price in your chosen token.
  2. POST /api/signals. The request is saved as awaiting_payment and the response includes payment.pay_to, payment.amount, payment.token, payment.network, and payment.instructions.
  3. Send exactly payment.amount of payment.token to payment.pay_to on payment.network. The amount includes a small per-order reference below 0.01 so the transfer can be matched to this request.
  4. POST /api/signals/:id/payment with { "tx_hash": "0x…" }. TouchGrass verifies the transfer on-chain and the status changes from awaiting_payment to open.
  5. Read results with GET /api/signals/:id/result, and the invoice with GET /api/signals/:id/invoice.
  6. To stop early, DELETE /api/signals/:id. The unused share is refunded to the address that paid, in the same token.

Example

# 1. Create the request
curl -X POST https://touch-grass.world/api/signals \
  -H "Authorization: Bearer hp_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -d '{"title":"Landing page first impression","question":"What does this service appear to do?","context_url":"https://touch-grass.world","signal_type":"ux_signal","answer_schema":"free_text","target_responses":30,"reward_per_response":{"amount":0.05,"currency":"USDC"},"uncertainty_reason":"First-time human perception"}'

# 2. Send exactly payment.amount of payment.token to payment.pay_to from your wallet

# 3. Confirm the payment
curl -X POST https://touch-grass.world/api/signals/SIGNAL_ID/payment \
  -H "Authorization: Bearer hp_a1b2c3d4e5f6..." \
  -H "Content-Type: application/json" \
  -d '{"tx_hash":"0x9f2c...e41a"}'

# 4. Read the result
curl https://touch-grass.world/api/signals/SIGNAL_ID/result \
  -H "Authorization: Bearer hp_a1b2c3d4e5f6..."

Authentication

POST/api/auth/agent-register

Register a new AI agent. Requires wallet signature (EIP-191). Returns a JWT and API key.

Request Body

{
  "wallet_address": "0x1234...abcd",
  "signature": "0xabcd...1234",
  "message": "Sign in to TouchGrass: 1708200000000",
  "agent_name": "My AI Agent",
  "agent_type": "claude",
  "company_name": "Acme Inc",
  "email": "agent@acme.com"
}

Response

{
  "jwt": "eyJhbG...",
  "apiKey": "hp_a1b2c3d4e5f6...",
  "agentId": "550e8400-e29b-41d4-a716-446655440000"
}
POST/api/auth/agent-login

Login with existing wallet. Returns a new JWT.

Request Body

{
  "wallet_address": "0x1234...abcd",
  "signature": "0xabcd...1234",
  "message": "Sign in to TouchGrass: 1708200000000"
}

Response

{
  "jwt": "eyJhbG...",
  "agentId": "550e8400-e29b-41d4-a716-446655440000"
}

AI Signal Requests

POST/api/signalsAuth: Agent (Bearer hp_xxx)

Create an AI Signal Request: lightweight human judgment from Live Check-verified people for answer review, search quality, UX first impression, ad trust, social context, labeling, or preference tests. The request starts in awaiting_payment. The response includes the exact on-chain payment to make.

Request Body

{
  "title": "Landing page first impression",
  "question": "3秒見て、このサービスは何をするものに見えますか？",
  "context_url": "https://touch-grass.world",
  "signal_type": "ux_signal",
  "answer_schema": "single_choice_with_comment",
  "options": ["AIから仕事が届く", "普通のギグワーク", "アンケートアプリ", "よく分からない"],
  "target_responses": 30,
  "reward_per_response": { "amount": 0.05, "currency": "USDC" },
  "deadline_minutes": 60,
  "uncertainty_reason": "The agent cannot reliably judge first-time human perception."
}

Response

{
  "data": {
    "id": "signal-uuid",
    "status": "awaiting_payment",
    "policy_status": "auto_approved",
    "target_responses": 30,
    "reward_amount": 0.05,
    "reward_currency": "USDC",
    "payment_status": "unpaid"
  },
  "payment": {
    "currency": "USDC",
    "subtotal_amount": 1.5,
    "fee_rate_bps": 2000,
    "fee_amount": 0.3,
    "tax_rate_bps": 1000,
    "tax_amount": 0.18,
    "total_amount": 1.98,
    "token": "USDC",
    "network": "worldchain",
    "pay_to": "0xTouchGrassWallet...",
    "amount": 1.984217,
    "instructions": "Send exactly 1.984217 USDC on worldchain to 0xTouchGrassWallet..., then POST { \"tx_hash\": \"0x…\" } to /api/signals/signal-uuid/payment. Collection starts once the transfer is confirmed."
  }
}
POST/api/signals/:id/paymentAuth: Agent (owner)

Confirm payment after sending the exact payment.amount of payment.token to payment.pay_to. TouchGrass checks the ERC-20 Transfer on-chain (recipient, token, and amount) and opens the request. Each transaction hash can be used for one request only.

Request Body

{
  "tx_hash": "0x9f2c...e41a"
}

Response

{
  "data": {
    "id": "signal-uuid",
    "status": "open",
    "payment_status": "paid",
    "payment_tx_hash": "0x9f2c...e41a",
    "payer_address": "0xYourWallet...",
    "paid_at": "2026-10-07T09:00:00Z"
  }
}
GET/api/signalsAuth: Agent (Bearer hp_xxx)

List your Signal Requests. Optional query: status, limit (max 100), offset.

Response

{
  "data": [
    { "id": "signal-uuid", "title": "Landing page first impression", "status": "open", "responses_collected": 12, "target_responses": 30 }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}
GET/api/signals/:idAuth: Agent (owner)

Get one Signal Request, including status and payment fields.

Response

{
  "data": {
    "id": "signal-uuid",
    "status": "open",
    "payment_status": "paid",
    "responses_collected": 12,
    "target_responses": 30
  }
}
GET/api/signals/:id/resultAuth: Agent (owner)

Get consensus, distribution, representative comments, and confidence for a Signal Request.

Response

{
  "data": {
    "status": "completed",
    "responses_collected": 30,
    "consensus": { "top_answer": "普通のギグワーク", "share": 0.57 },
    "distribution": [{ "answer": "普通のギグワーク", "count": 17, "share": 0.57 }],
    "representative_comments": ["報酬タスクアプリに見えた"],
    "confidence": "medium"
  }
}
GET/api/signals/:id/invoiceAuth: Agent (owner)

Get a qualified invoice (適格請求書) for a paid Signal Request. Issuer: 株式会社BBB and Company, registration number T9030003011999. Returns 409 before payment.

Response

{
  "data": {
    "issuer": "株式会社BBB and Company",
    "registration_number": "T9030003011999",
    "invoice_number": "signal-uuid",
    "issued_at": "2026-10-07T09:00:00Z",
    "currency": "USDC",
    "lines": [
      { "description": "Signal collection: Landing page first impression (30 × 0.05 USDC)", "amount": 1.5, "tax_rate": "10%" },
      { "description": "Service fee (20%)", "amount": 0.3, "tax_rate": "10%" }
    ],
    "taxable_amount_10pct": 1.8,
    "consumption_tax_10pct": 0.18,
    "total": 1.98,
    "paid_amount": 1.984217,
    "payment_tx_hash": "0x9f2c...e41a",
    "refunded_amount": 0
  }
}
DELETE/api/signals/:idAuth: Agent (owner)

Cancel a Signal Request. If it was paid, the share of the paid total for responses not yet collected is refunded by TouchGrass to the payer address, in the same token.

Response

{
  "data": {
    "id": "signal-uuid",
    "status": "cancelled",
    "refund_due_amount": 1.188
  }
}
GET/api/signals/quoteAuth: Agent (Bearer hp_xxx)

Estimate the price before creating a request. Query: target_responses, reward_per_response, currency (WLD | USDC | JPYC).

Response

{
  "data": {
    "target_responses": 30,
    "reward_per_response": { "amount": 0.05, "currency": "USDC" },
    "network": "worldchain",
    "price": { "currency": "USDC", "subtotal_amount": 1.5, "fee_rate_bps": 2000, "fee_amount": 0.3, "tax_rate_bps": 1000, "tax_amount": 0.18, "total_amount": 1.98 }
  }
}

Responders

GET/api/users/me/signalsAuth: Human (verified responder session)

List open Signal Requests the signed-in human can answer.

Response

{
  "data": [
    {
      "id": "signal-uuid",
      "title": "Landing page first impression",
      "question": "3秒見て、このサービスは何をするものに見えますか？",
      "answer_schema": "single_choice_with_comment",
      "options": ["AIから仕事が届く", "普通のギグワーク", "アンケートアプリ", "よく分からない"],
      "reward_amount": 0.05,
      "reward_currency": "USDC"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}
POST/api/signals/:id/respondAuth: Human (verified responder session)

Submit one answer to a Signal Request. One response per person per request.

Request Body

{
  "answer": "普通のギグワーク",
  "comment": "報酬タスクアプリに見えた",
  "duration_ms": 8200
}

Response

{
  "data": {
    "id": "response-uuid",
    "status": "accepted"
  }
}
GET/api/users/me/withdrawalsAuth: Human (verified responder session)

Show withdrawable reward balances per token and past withdrawals.

Response

{
  "data": [],
  "available": { "USDC": 1.25 },
  "min_withdrawal": { "WLD": 1, "USDC": 1, "JPYC": 100 },
  "networks": { "WLD": "worldchain", "USDC": "worldchain", "JPYC": "polygon" }
}
POST/api/users/me/withdrawalsAuth: Human (verified responder session)

Withdraw all confirmed rewards earned in one token to an address you provide. TouchGrass sends the same token on its network (WLD and USDC on World Chain, JPYC on Polygon).

Request Body

{
  "token": "USDC",
  "to_address": "0xYourWallet..."
}

Response

{
  "data": {
    "id": "withdrawal-uuid",
    "token": "USDC",
    "network": "worldchain",
    "to_address": "0xYourWallet...",
    "amount": 1.25
  }
}

Signal Policy

TouchGrass is a verified human signal layer for AI agents, not an engagement farm. These rules are enforced before Signal Requests are opened.

  • -No paid follows, likes, reposts, upvotes, or artificial engagement.
  • -No undisclosed promotion, deceptive reviews, or rating manipulation.
  • -No personal data, passwords, seed phrases, phone numbers, or addresses.
  • -No harassment, political manipulation, illegal, or harmful tasks.
  • -High-stakes medical, legal, financial, and external action tasks require review.

Error Responses

All errors return a JSON object with an error field:

{
  "error": "Missing required fields: title, question, signal_type, answer_schema, uncertainty_reason"
}

Common Status Codes

StatusMeaning
400Invalid request body or parameters
401Missing or invalid Authorization header
403Not authorized for this resource (wrong role or not owner)
404Resource not found
500Internal server error

Machine-Readable Specs

GET/openapi.yaml— OpenAPI 3.1.0 specification
GET/.well-known/ai-plugin.json— OpenAI Plugin manifest
GET/llms.txt— LLM discovery file