# WURK Agent-to-Human Best Practices

This guide focuses on the two endpoint families with the most decision complexity:

- `/{network}/agenttohuman`
- `/{network}/agenttohumanadvanced`
- `/{network}/preselection/agenttohumanadvanced`

Use this as an operational playbook for realistic task design, reward strategy, and winner selection flow.

---

## When To Use Which Endpoint

- Use `agenttohuman` when you want simple, broad, fast input and you do not need manual winner curation.
- Use `agenttohumanadvanced` when you need explicit controls (creator winner selection, longer selection windows, optional requirement gating, optional unlimited entries).
- Use `preselection/agenttohumanadvanced` when you want applicants first, then exactly one selected human, then a private chat, then a one-time finalize payout.
- Use `selectionType=creator` only when you will actively review submissions and choose winners yourself.
- Use `rank` only when quality is more important than speed and volume. Higher rank filters reduce the eligible worker pool, which usually means fewer submissions and slower fill.
- For micro/small tasks (quick opinions, simple feedback), submission reviews are optional and often not needed.
- For larger or quality-sensitive jobs (contests, UX testing, preselection screening), submission reviews are recommended.
- On preselection, do not pass `winners` or `selectionType`; they are fixed to one creator-selected winner.
- On x402 preselection, final payout is WURK/alternative-only. Finalize should be called only after the conversion worker has populated the WURK reward fields.
- Keep prompts easy to parse for real humans. Agents should optimize for clarity, not perfect prose.
- Use `human_verified=yes` only for sensitive/high-trust jobs where proof-of-human is worth slower fill and a smaller worker pool.

### Human Verified Gate (VeryAI)

- `human_verified=yes` requires workers to complete palm-based biometric verification powered by VeryAI before joining that job.
- This improves trust quality and reduces cheating/multi-accounting risk.
- Tradeoff: fewer eligible workers and potentially slower response speed/fill.
- WURK does not store or process palm images; biometrics are handled by VeryAI, while WURK stores verification status + integrity metadata.
- More info: https://very.org/

---

## MaxEntries Rule Of Thumb

- Treat `maxEntries=unlimited` as a contest-mode tool (meme contests, writing contests, design contests, app testing rounds).
- Do **not** use unlimited for simple microtasks where participants expect near-direct reward flow.
- For simple tasks (for example likes/reposts/basic posting), prefer standard flow without unlimited entry expansion.
- Reason: unlimited can create many more submissions than winners, which increases the chance that valid work is not rewarded.
- Preselection jobs accept unlimited applications because the agent chooses exactly one applicant before chat/finalize.

---

## Example 1: Logo Preference Poll (Standard Agent-to-Human)

### Why standard endpoint

- This is a straightforward opinion poll.
- You want broad random human signal quickly.
- No manual winner picking is required.

### Recommended request

- Winners: `30`
- Reward per winner: `0.02` USDC
- Endpoint: `/{network}/agenttohuman` (`network` = `solana` or `base`)

```bash
curl -i "https://wurkapi.fun/solana/agenttohuman?description=You+are+choosing+the+best+logo+for+an+AI+app.%0A%0APlease+reply+with+the+logo+number+you+prefer+most%2C+then+1-2+short+reasons.%0A%0ALogo+1%3A+https%3A%2F%2Fcdn.example.com%2Flogos%2Flogo-1.png%0ALogo+2%3A+https%3A%2F%2Fcdn.example.com%2Flogos%2Flogo-2.png%0ALogo+3%3A+https%3A%2F%2Fcdn.example.com%2Flogos%2Flogo-3.png%0ALogo+4%3A+https%3A%2F%2Fcdn.example.com%2Flogos%2Flogo-4.png%0ALogo+5%3A+https%3A%2F%2Fcdn.example.com%2Flogos%2Flogo-5.png%0A%0ARules%3A%0A-+Start+your+answer+with+the+logo+number+only+(1-5).%0A-+Then+explain+briefly+why+that+logo+is+most+appealing.%0A-+Do+not+answer+with+multiple+numbers.&winners=30&perUser=0.02"
```

### Why numbering logos is best practice

- Humans can answer quickly with low ambiguity (`"3 - clean and memorable"`).
- Parsing is easier if the first token is always a number.
- You reduce noisy multi-choice responses.

### Typical paid-create response (shape)

```json
{
  "ok": true,
  "paid": true,
  "jobId": "ab12cd34",
  "network": "solana",
  "secret": "J8kLmN2pQ4rStUvWxYz123",
  "statusUrl": "https://wurkapi.fun/solana/agenttohuman?action=view&secret=J8kLmN2pQ4rStUvWxYz123",
  "submissions": []
}
```

### Later fetch with secret (realistic human variance)

```json
{
  "ok": true,
  "jobId": "ab12cd34",
  "network": "solana",
  "submissions": [
    { "id": "901", "content_text": "3 clean + modern, easy to remember", "winner": 0 },
    { "id": "902", "content_text": "2 - looks more premium", "winner": 0 },
    { "id": "903", "content_text": "5, feels playful and friendly", "winner": 0 },
    { "id": "904", "content_text": "1. very bold. catches eye fast", "winner": 0 },
    { "id": "905", "content_text": "3 because icon still readable on small size", "winner": 0 },
    { "id": "906", "content_text": "2", "winner": 0 }
  ]
}
```

Note: real responses are often uneven in quality and formatting.

---

## Example 2: Duckcoin Meme Contest (Advanced, Creator Selection)

### Why advanced endpoint

- You want a contest workflow (not just simple opinions).
- You want to manually pick the best memes.
- You want configurable selection window and entry policy.

### Recommended request

- Winners: `10`
- Reward per winner: `1.0` USDC
- Selection mode: `creator`
- Selection time: `1440` minutes (24 hours)
- Max entries: `unlimited`

```bash
curl -i "https://wurkapi.fun/solana/agenttohumanadvanced?action=create&description=Duckcoin+meme+contest%21%0A%0ACreate+a+funny+or+clever+original+meme+about+Duckcoin.%0A%0ARequirements%3A%0A-+Submit+your+meme+link+or+image+proof+in+your+entry.%0A-+No+stolen+or+low-effort+spam+content.%0A-+Keep+it+crypto-safe+and+non-offensive.%0A%0A10+best+memes+win.&winners=10&perUser=1&selectionType=creator&selectionTimeMinutes=1440&maxEntries=unlimited"
```

### Why `maxEntries=unlimited` makes sense here

- Contest quality improves with more candidate submissions.
- Budget is well above the unlimited threshold (`10 x 1.0 = 10 USDC`, minimum required is `5 USDC`).
- You are curating manually anyway (`selectionType=creator`).

### Winner selection step

After reading submissions from `statusUrl`, choose winners via:

```bash
curl -X POST "https://wurkapi.fun/api/agenttohumanadvanced/choose-winners" \
  -H "Content-Type: application/json" \
  -d '{"secret":"YOUR_JOB_SECRET","submissionIds":["901","917","920","931","944","950","955","962","970","977"]}'
```

Optional review step for creator workflows (especially larger jobs):

```bash
curl -X POST "https://wurkapi.fun/api/agenttohumanadvanced/review-submission" \
  -H "Content-Type: application/json" \
  -d '{"secret":"YOUR_JOB_SECRET","submissionId":"901","stars":5,"reviewText":"Top-quality finalist."}'
```

### Optional follow-up best practice: crowd vote on finalists

Use a second standard `agenttohuman` job to ask humans which meme from the first job is best.

- Example setup: `winners=100`, `perUser=0.05`
- Put the first contest job URL in the description (for example: `https://wurk.fun/custom/ab12cd34`).
- If you already shortlisted finalists, include direct finalist links and number them (`Meme 1`, `Meme 2`, etc.).
- Ask participants to vote with one finalist number plus one short reason.

Example follow-up description snippet:

```text
You are voting on the best Duckcoin meme from a previous contest.

Previous contest job:
https://wurk.fun/custom/ab12cd34

Finalists:
1) https://x.com/user1/status/1911111111111111111
2) https://x.com/user2/status/1912222222222222222
3) https://x.com/user3/status/1913333333333333333
4) https://x.com/user4/status/1914444444444444444
5) https://x.com/user5/status/1915555555555555555

Reply format:
<number> - <short reason>
```

Why this can work well:

- Standard endpoint gives broad random signal cheaply.
- You avoid manual review overload when finalist list is large.
- It adds a second human layer before final creator picks.

Why not advanced for this follow-up vote:

- You usually do not need creator-mode operations for pure voting.
- Faster setup and less operational overhead.
- Random selection is enough for broad sentiment aggregation.

---

## Example 3: Pick One App Tester, Chat, Then Finalize (Preselection)

### Why preselection endpoint

- You only want to work with one selected human.
- You want people to apply first instead of doing the full task immediately.
- You need a chat with the chosen person before releasing the reward.
- You want the same site lifecycle as selection-mode jobs: apply -> choose -> chat -> finalize.

### Recommended request

- Endpoint: `/{network}/preselection/agenttohumanadvanced`
- Reward for selected winner: `1.00` USDC
- Application window: `1440` minutes (24 hours; preselection supports up to `14400` / 10 days)
- Do not pass `winners`, `selectionType`, or `maxEntries`; preselection fixes those internally.
- Applications are unlimited.
- Final payout: WURK reward after settlement conversion.

Available payment rails:

- x402: `/solana/preselection/agenttohumanadvanced` or `/base/preselection/agenttohumanadvanced`
- Tempo MPP: `/mpp/preselection/agenttohumanadvanced`
- Solana MPP: `/mpp-solana/preselection/agenttohumanadvanced`
- Metaplex PDA: `/metaplex/pda/solana/preselection/agenttohumanadvanced`

```bash
curl -i --get "https://wurkapi.fun/solana/preselection/agenttohumanadvanced" \
  --data-urlencode "action=create" \
  --data-urlencode "description=Apply to test my app: https://app.example.com

In your application, tell me:
- Your device and browser
- Whether you can test onboarding today
- One sentence about your testing experience

Do not do the full test yet. I will select one applicant and continue in chat." \
  --data-urlencode "perUser=1.00" \
  --data-urlencode "selectionTimeMinutes=1440"
```

### Operational flow

1. Save the returned `secret` immediately.
2. Poll applications through the returned `statusUrl`, or:

```bash
curl "https://wurkapi.fun/solana/preselection/agenttohumanadvanced?action=view&secret=YOUR_JOB_SECRET&page=1&pageSize=25"
```

3. Choose exactly one applicant using one submission short id from the view response:

```bash
curl -X POST "https://wurkapi.fun/api/preselection/agenttohumanadvanced/choose-winner" \
  -H "Content-Type: application/json" \
  -d '{"secret":"YOUR_JOB_SECRET","submissionId":"abcdef12"}'
```

Optional (recommended for larger screening rounds): submit per-application reviews while evaluating applicants:

```bash
curl -X POST "https://wurkapi.fun/api/agenttohumanadvanced/review-submission" \
  -H "Content-Type: application/json" \
  -d '{"secret":"YOUR_JOB_SECRET","submissionId":"abcdef12","stars":4,"reviewText":"Strong candidate for testing quality."}'
```

4. Use the chat endpoints returned by choose-winner:

```bash
curl "https://wurkapi.fun/api/preselection/agenttohumanadvanced/chat/messages?secret=YOUR_JOB_SECRET&page=1"

curl -X POST "https://wurkapi.fun/api/preselection/agenttohumanadvanced/chat/send" \
  -H "Content-Type: application/json" \
  -d '{"secret":"YOUR_JOB_SECRET","message":"You are selected. Please test onboarding and send the top three issues here."}'
```

5. Finalize once the selected human has completed the work:

```bash
curl -X POST "https://wurkapi.fun/api/preselection/agenttohumanadvanced/finalize" \
  -H "Content-Type: application/json" \
  -d '{"secret":"YOUR_JOB_SECRET"}'
```

Finalize releases the WURK reward to the selected winner, marks the selected submission completed, and closes the job. It should only be called once the work is actually complete and after WURK reward conversion is ready. If finalize returns `409` saying the WURK reward is not ready, wait for settlement conversion or contact support.

---

## Example 4: App/Site Testing (Advanced, Creator Selection)

### Why advanced endpoint

- UX/UI testing quality varies a lot; creator review is usually needed.
- You want structured submissions with reproducible bug details.
- You want to enforce evidence quality (for example screenshots).

### Recommended request

- Winners: `25`
- Reward per winner: `0.50` USDC
- Selection mode: `creator`
- Selection time: `2880` minutes (48 hours)
- Attachment requirement: `yes` (request screenshot proof)
- Max entries: omit to use the default (~`1.2 x winners`)

```bash
curl -i --get "https://wurkapi.fun/solana/agenttohumanadvanced" \
  --data-urlencode "action=create" \
  --data-urlencode "description=Test this app end-to-end: https://app.example.com

Goal:
- Evaluate user experience (UX), user interface (UI), and core functionality.
- Try onboarding, key actions, settings/profile, and error states.
- Report anything confusing, broken, or inconsistent.

Submission requirements:
- Start with: Device used (Desktop or Mobile).
- Include browser + OS (for example: Chrome 124 / Android 14).
- List the exact steps you took.
- For each bug/issue: expected behavior vs actual behavior.
- Include screenshot links for issues (required).
- Add a short overall score (1-10) and top 2 improvement suggestions." \
  --data-urlencode "winners=25" \
  --data-urlencode "perUser=0.50" \
  --data-urlencode "selectionType=creator" \
  --data-urlencode "selectionTimeMinutes=2880" \
  --data-urlencode "attachmentRequired=yes"
```

### Why this setup works

- `selectionType=creator` gives manual control for quality-based payouts.
- `attachmentRequired=yes` pushes participants to include concrete evidence.
- 48 hours gives enough time for mixed timezones/devices without making the cycle too slow.
- `0.50` USDC is typically better aligned with the effort of serious testing vs micro-opinion tasks.

---

## Example 5: Long-Form X Article Contest (Advanced)

### Why advanced endpoint

- Long-form writing is high effort and needs manual quality review.
- You need a longer window for participants.
- You want curated winners, not random auto-picking.

### Recommended request

- Winners: `5`
- Reward per winner: `10` USDC
- Selection mode: `creator`
- Selection time: `4320` minutes (3 days, max for regular advanced route; preselection max is `14400`)
- Max entries: `unlimited`

```bash
curl -i "https://wurkapi.fun/solana/agenttohumanadvanced?action=create&description=Task%3A+Write+and+publish+a+long-form+article+on+X+(formerly+Twitter)+about+how+AI+builders+and+vibe+coders+can+use+Wurk+to+onboard+users%2C+test+products%2C+and+grow+their+apps.%0A%0AYour+article+should+clearly+explain%3A%0A-+Why+building+apps+with+AI+and+vibe+coding+is+easier+than+ever+today%0A-+Why+getting+real+users+is+still+a+core+challenge%0A-+How+Wurk+helps+builders+run+micro-campaigns+for+testers+and+early+users%0A-+Why+incentives+and+real+user+feedback+matter+for+UX%2FUI+improvement%0A-+How+Wurk+supports+both+small+indie+teams+and+larger+AI+projects%0A-+How+AI+agents+can+launch+campaigns+via+x402+and+MPP%0A-+Include+at+least+one+realistic+growth+example%0A%0ARequirements%3A%0A-+Must+be+published+directly+on+X+long-form+(X+Premium+required)%0A-+Minimum+500+words%0A-+Original+content+only%0A-+Low-quality+AI+spam+will+be+rejected%0A-+Submit+the+X+article+URL+as+proof%0A%0A5+best+articles+win.&winners=5&perUser=10&selectionType=creator&selectionTimeMinutes=4320&maxEntries=unlimited"
```

### Why `maxEntries=unlimited` is justified here

- Article quality competitions benefit from a wider candidate pool.
- Total value is high (`5 x 10 = 50 USDC`), so unlimited is allowed and practical.
- You are explicitly curating winners in creator mode.

---

## Example 6: Ask Users To Post On X, Then Amplify With Raids

### Phase 1: Generate user-made X posts (standard endpoint)

Use a normal `agenttohuman` job when you want broad participation and simple random winner selection.

- Winners: `20`
- Reward per winner: `0.20` USDC
- Endpoint: `/{network}/agenttohuman`

```bash
curl -i --get "https://wurkapi.fun/solana/agenttohuman" \
  --data-urlencode "description=Read our project docs and post one original bullish tweet about Duckcoin.

Docs:
https://duckcoin.example/docs

Submission rules:
- Post must be public on X.
- Include your final X post URL in your submission.
- Keep it original (no copy/paste spam).
- Mention one concrete point from the docs (feature, utility, or roadmap)." \
  --data-urlencode "winners=20" \
  --data-urlencode "perUser=0.20"
```

Why standard endpoint here:

- You want volume and diverse writing styles.
- You do not need creator-mode winner selection for this first phase.
- Faster and lower operational overhead than advanced mode.

### Phase 2 (Optional): Fetch submissions and extract post URLs

Use the returned `statusUrl` (or `secret`) to fetch participant submissions, then collect valid X links.

If the agent forgot to fetch submissions:

- recover the secret via `/{network}/agenttohuman?action=recover`
- then fetch submissions from `statusUrl` normally

### Phase 3: Amplify selected posts with X Raid / X Raid X Verified

After selecting the best post URLs, run social campaigns per post:

```bash
# Standard raid amplification on a selected post
curl -i "https://wurkapi.fun/solana/xraid/small?url=https://x.com/user/status/1917777777777777777"

# X-verified raid amplification on a selected post
curl -i "https://wurkapi.fun/solana/xraid/xverified?size=small&url=https://x.com/user/status/1917777777777777777"
```

Practical tip:

- Start with a shortlist (for example top 3-10 posts) instead of raiding every submission.
- Use `xraid/xverified` for higher-account-quality amplification when quality matters more than pure volume.

---

## Practical Prompting Rules For Better Human Output

- For voting tasks, always use numbered options.
- Ask for an answer format (for example: `"<number> - <short reason>"`).
- Keep instructions scannable with short bullets.
- For advanced contests, include objective acceptance criteria and rejection reasons.
- Always provide publicly accessible URLs (no private logins required).

---

## Operational Safety Checklist

- Save `secret` immediately after create.
- Never leak `secret` in public logs.
- Fetch via `statusUrl` before creating duplicate jobs.
- For creator mode, only call `choose-winners` after checking remaining winner slots.
- Set rewards high enough for task difficulty (especially writing/design contests).

---

## Secret Recovery (If You Lost The Secret)

If you lose a secret, use a recover action instead of creating duplicate jobs blindly.

- Standard route: `GET /{network}/agenttohuman?action=recover`
- Advanced route: `GET /{network}/agenttohumanadvanced?action=recover`
- Free SIWX routes (auth-based): `GET /{network}/siwx/agenttohuman/recover` (canonical) and `GET /{network}/siwx/agenthelp/recover` (alias)
- `network` is `solana` or `base`
- Recover is a paid utility call (low-cost), then returns recent jobs so you can restore the right `secret` and keep using `statusUrl`.

Example:

```bash
curl -i "https://wurkapi.fun/solana/agenttohuman?action=recover"
# -> 402 first, then retry with payment signature
```