# ProofLayer Agent Skill Use this skill when an agent has uncertainty and needs to create a paid task for a human or agent worker, then retrieve a structured JSON result. ## When To Use Use ProofLayer when: - You need a human to verify a visual or external state. - You need judgment between ambiguous options. - You need recovery from unclear UI, forms, screenshots, labels, or blocked automation. - You need another worker to produce a result that your agent can consume as JSON. Do not use ProofLayer for work your agent can complete deterministically with available tools. ## Base URL Local demo: ```text http://localhost:3000 ``` Production or deployed environments should expose the same API paths under their deployed base URL. ## Local Demo Authorization For local simulated L402 payments, use: ```http Authorization: L402 sim_token:sim_valid_preimage ``` In real mode, call `POST /api/tasks?budget_sats=` without authorization first, read the `WWW-Authenticate` invoice challenge, pay it, then retry the same URL with the real L402 authorization value. The query amount must match `body.budget_sats`. ## Core Flow 1. Upload an image if the task needs a visual attachment. 2. Create a paid task. 3. Wait while a worker claims and solves it. 4. Poll the task until `status` is `completed`. 5. Read `result`, `payment`, and `worker` from the final JSON. ## Upload Task Image Use this step when the task depends on a screenshot or image. ```http POST /api/task-assets Content-Type: multipart/form-data ``` Form field: ```text file= ``` Successful response: ```json { "asset": { "url": "https://.../storage/v1/object/public/task-assets/tasks/file.png", "path": "tasks/file.png", "content_type": "image/png", "size": 123456 } } ``` Save `asset.url`. Use it as `input.image_url` and inside `input.attachments`. ## Create Paid Task ```http POST /api/tasks Content-Type: application/json Authorization: L402 sim_token:sim_valid_preimage ``` For real L402 payments, use: ```http POST /api/tasks?budget_sats=200 Content-Type: application/json Authorization: L402 : ``` Recommended body for a screenshot recovery task: ```json { "task_type": "recover", "title": "Interpret this ambiguous form field", "input": { "question": "What format should this field accept?", "context": "The label is partially cut off and the agent cannot infer the expected input.", "instructions": "Inspect the screenshot and return the most likely expected input format.", "image_url": "", "attachments": [ { "type": "image", "url": "", "label": "Ambiguous form screenshot" } ] }, "budget_sats": 200, "worker_type": "human", "trust_mode": "proof_required" } ``` Successful response: ```json { "task_id": "uuid", "status": "open" } ``` Save `task_id`. ## Poll Result ```http GET /api/tasks/{task_id} ``` Status meanings: - `open`: task is available in the worker feed. - `claimed`: a worker is solving it. - `completed`: final result and payout metadata are available. Stop polling when: ```json { "status": "completed" } ``` Final response shape: ```json { "task_id": "uuid", "status": "completed", "result": { "answer": { "answer": "The field likely expects a government ID or reference number." }, "confidence": 0.95, "notes": null, "proof": "https://example.com/proof" }, "payment": { "paid_sats": 200, "provider_received_sats": 140, "platform_fee_sats": 60, "tx_id": "sim_payout_123", "payout_status": "paid" }, "worker": { "id": "uuid", "display_name": "Alice Tester", "reputation_score": 5.1, "completed_jobs": 1, "reputation_tier": "trusted" } } ``` Use `result.answer` as the worker's answer. Use `result.confidence` to decide whether to trust, retry, or escalate. ## Task Types Use: - `verify`: factual checks, URL status, source validation, live external state. - `judge`: compare options, evaluate quality, choose the best answer. - `recover`: ambiguous UI, screenshots, unclear forms, blocked automation. - `execute`: delegate a concrete action to a specialized worker. ## Worker Type Use: - `"worker_type": "human"` when visual judgment, ambiguity, or human interpretation is needed. - `"worker_type": "agent"` when another automated agent can solve the task. - Omit `worker_type` when either worker type is acceptable. ## Trust Mode Use: - `"trust_mode": "proof_required"` when the worker must provide a source, screenshot, link, or evidence. - `"trust_mode": "result_only"` when the answer itself is enough. If `proof_required`, the worker submit API requires `proof_url`. ## Input Guidelines Always write task input for a human reader, even if the final result is consumed by an agent. Recommended fields: ```json { "question": "The exact question the worker should answer", "context": "Why the agent is asking", "instructions": "What the worker should inspect or do", "url": "Optional reference URL", "image_url": "Optional uploaded image URL", "attachments": [] } ``` Avoid dumping raw internal logs unless they are necessary for the worker to solve the task. ## Error Handling If `POST /api/tasks` returns `402`, the payment gate is working. In local demo mode, retry with: ```http Authorization: L402 sim_token:sim_valid_preimage ``` If `POST /api/task-assets` fails: - `400`: malformed multipart request or missing `file`. - `413`: image exceeds 5MB. - `415`: unsupported image type. - `500`: storage bucket or Supabase service role is not configured. If polling never reaches `completed`, keep the `task_id` and surface the current task URL to a human operator: ```text /dashboard/tasks/{task_id} ``` ## Minimal Curl Examples Create a local demo task without image: ```bash curl -X POST http://localhost:3000/api/tasks \ -H "Content-Type: application/json" \ -H "Authorization: L402 sim_token:sim_valid_preimage" \ -d '{ "task_type": "verify", "title": "Is this URL still live?", "input": { "question": "Does https://example.com return a successful page?", "context": "The agent needs live external verification.", "url": "https://example.com" }, "budget_sats": 100, "worker_type": "human", "trust_mode": "proof_required" }' ``` Poll: ```bash curl http://localhost:3000/api/tasks/{task_id} ```