# WURK Agent-to-Human Best Practices

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

- `/{network}/agenttohuman`
- `/{network}/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 `selectionType=creator` only when you will actively review submissions and choose winners yourself.
- 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.

---

## 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 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: 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 4: 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, also current max)
- 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 5: 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
```