# Handsel

> The first gift from every great brand. Handsel is a free-samples marketplace for humans and their AI agents.
> Brands list only free things — physical samples, digital trials, and services. People, or agents acting
> for them, claim them. If they love it, one click subscribes.

Everything listed on Handsel is free to claim. Physical samples are shipped to the member's saved address.
Digital and service samples return a redemption code immediately (format HSL-XXXX-XXXX).

## For AI agents

- Discovery manifest: https://handsel.shantomathew.workers.dev/.well-known/agent.json
- MCP server (Streamable HTTP, JSON-RPC 2.0, JSON responses): POST https://handsel.shantomathew.workers.dev/mcp
  Tools: search_samples {query?, category?, kind?, limit?}, get_sample {id}, claim_sample {id},
         list_my_claims {}, submit_feedback {claim_id, rating 1-5, would_buy, comment?}
- REST base: https://handsel.shantomathew.workers.dev/api
- Human-readable docs: https://handsel.shantomathew.workers.dev/agents

## Authentication

Search and sample lookup are public. Claiming, listing claims and feedback require an agent key that a
member creates at https://handsel.shantomathew.workers.dev/me and gives to you. Send it as:

    Authorization: Bearer hsk_...

Each key is scoped to one member and has: a monthly claim cap (1-20 per 30 days), an optional category
allow-list, an expiry date, and a share setting (postal, prefs) that controls which profile fields you may read
via GET /api/me. Keys can be revoked by the member at any time.

## Rules

- One claim per member per sample.
- At most 6 claims per member per rolling 30 days (across web and agents).
- Physical samples require a shipping address on the member's profile.
- Agent claims must also respect the key's monthly cap and categories.
- Feedback is never gated: honest negative ratings are as valuable as positive ones.
- Only claim things your human would actually want. Respect their stated allergies, pets, and things to avoid.

## REST endpoints

- GET  /api/samples?category=&kind=&q=&limit=   → {samples:[Sample]}
- GET  /api/samples/{id}                        → {sample}
- POST /api/samples/{id}/claim   (auth)         → {claim:{id,status,code?}}
- GET  /api/me                   (auth)         → {user, profile (filtered by key share), brand, agent_key}
- GET  /api/me/claims            (auth)         → {claims:[...]}
- POST /api/claims/{id}/feedback (auth)         {rating, would_buy, comment} → {feedback}
- POST /api/claims/{id}/subscribe (auth)        → {url}  (only when your human explicitly asks to subscribe)
- GET  /api/stats                               → {brands, samples, claims, members, agents}

Errors are JSON: {"error": "message"} with a 4xx status.

## Vocabulary

Categories: beauty, food, drink, pet, baby, wellness, home, software, media, services
Kinds: physical, digital, service