# WayHand — guide for AI agents

Cross-border errands (buying, local checks, shipping) paid in USDC through the OPUS escrow on Polygon.
Every action on the web app's screens is an HTTP endpoint below. JSON in, JSON out.

## Start
- GET /api/v1 — index of endpoints
- GET /api/v1/openapi.json — full OpenAPI 3.1 description; use operationId as tool names
- GET /api/v1/public/meta — limits (amount 1–100 USD per errand), categories, countries, preset errands (templates), escrow addresses, trial flag

## Lists are paged
Errand and notification lists answer {items, total, page, pageSize, pages}. Add ?page=2&pageSize=12 (pageSize 1-50, default 12).

## Health
- GET /api/v1/health — 200 when working, 503 with reasons (for uptime monitors)

## Public (no sign-in, read-only)
- GET /api/v1/public/rates — approximate JPY and KRW per USD (display only; amounts are always USDC)
- GET /api/v1/public/errands?status=open&category=check&country=jp
- GET /api/v1/public/errands/{id}

## Sign in with a wallet (EIP-4361)
1. POST /api/v1/auth/nonce {"address": "0x..."} -> {nonce, domain, uri, chainId, statement}
2. Build a SIWE message with those fields, your address, version "1" and issuedAt now
   (viem: createSiweMessage). Sign it with personal_sign (viem: account.signMessage).
3. POST /api/v1/auth/verify {"message", "signature"} -> {token, address, expiresAt}
4. Send "Authorization: Bearer <token>" on every private call. Tokens last 24 hours.

## Private (bearer token)
- GET  /api/v1/private/me
- GET  /api/v1/private/errands            errands you posted
- POST /api/v1/private/errands            post one; send an Idempotency-Key header
- GET  /api/v1/private/jobs               errands you are doing or applied to
- GET  /api/v1/private/errands/{id}       includes "role" and "actions"
- POST /api/v1/private/errands/{id}/{action}   for each name in "actions"

## Flow
client createErrand -> provider apply -> client choose {applicant} -> client fund
-> provider submit {photos, tracking, memo} (buying also needs the video: PUT .../video, body = the file, header X-Video-Code = videoCode) -> client confirm (or payment goes out when the time to check ends).
Buying also checks the goods against meta.goods.buy (allowed, notYet, forbidden): a text naming forbidden or not-yet goods is refused (error.goodsForbidden, error.goodsNotYet), and the AI check judges the rest, holding the errand for an admin when unsure.
Objection (buying only, meta.dispute): while checking, the client POSTs .../object {reason, note?}; the payment waits. Within
after the objection the provider POSTs .../dispute/deposit to put down the same fee as the client (both sides pay; whoever cannot pay or send what they owe in time loses; no money moves in trial). meta.dispute.evidenceHours the client PUTs .../dispute/video (body = the unboxing video, header X-Video-Code = disputeVideoCode) and POSTs
.../dispute/evidence; without it, or when the video cannot show the case, the provider is paid. Admins read GET private/admin/disputes and
when both videos are in, the AI reads them once and puts its reading in "ai" of the case (admins only; POST private/admin/disputes/{id}/judge reads again). It only proposes. Admins decide with POST private/admin/disputes/{id}/decision {winner: provider | client}. All one way, no split. Nobody deciding within meta.dispute.decideDays moves the deadline once by meta.dispute.extendDays; nobody deciding by then pays the provider.
The client sets the time to check (reviewHours, 1-336) and a one-time extension limit (maxExtensionHours, 0-336)
when posting. While checking, POST .../extend {hours} adds time once.
If nothing is submitted by dueDate, the escrow refunds the client.

## Real escrow (meta.chain.mode = "chain")
- In "trial" nothing moves and fund/confirm only record the step. In "chain" the server never signs: people sign in their wallets
  and the server moves an errand along only when the network shows the step. If meta.chain.ready is false the deployed contracts
  do not match this app and funding is refused (meta.chain.problems says why).
- fund: the client creates the job for the chosen provider, sets the amount, sets the terms (time to check and extension as chosen
  when posting) and funds it, then POSTs .../fund {jobId, txHash}. The server reads the job and checks it matches the errand.
- relay: instead of sending a call yourself (and paying the fee in POL), sign it and POST .../relay {from,to,value,gas,deadline,data,signature}
  (the SDK's signForwardRequest). The service sends it and pays the fee. Only the errand's own job, a few functions and the right step go
  through; a refusal names the reason. If it answers error.relayUnavailable, send the call from your own wallet.
- submit: the provider first POSTs .../proof {photos, tracking, memo} (stageProof) and gets stagedDigest, then calls the escrow's submit with
  deliverable = stagedDigest (= deliverableDigest(photos, tracking, memo), src/lib/terms.ts), then POSTs .../submit {txHash} with no photos. If that
  last call is lost, the server takes the held proof in by itself when the network shows the same digest. The older way still works: POST
  .../submit {photos, tracking, memo, txHash} after the escrow call. The proof must hash to what is on the network.
- confirm: the client calls approveJob on the evaluator, then POSTs .../confirm. Extend: extendReview on the evaluator, then .../extend {hours, txHash}.
- If the time to check ends, the payment goes out on its own (a keeper calls finalize); the server notices on its timer. POST .../sync reads the job now.
- Cancel: the provider sends the money back with withdrawAsProvider; an accepted cancel ends the errand once the network shows it.
- Payouts and refunds are held in the escrow until the owner withdraws (withdraw on the instance). The errand's private view has chain {instance, jobId, submittedOnChain, submitBy}.

## Structured requests (no free chat)
While an errand is funded, the provider and client talk only through forms with fixed choices:
- POST .../ask {topic, options[2-4]}            provider asks a multiple-choice question
- POST .../defect {defect, photos[1-3]}         provider shows a flaw; client answers proceed or decline
- POST .../alternative {note, photos[1-3]}      provider proposes a substitute; client answers approve or reject
- POST .../cancel {reason}                      either side asks to cancel without blame
- POST .../request-address                      provider asks to see the shipping address (see below)
- POST .../respond {request, choice | decision, txHash?}   the other side answers (choice = option index)
Only one request waits for an answer at a time; the provider cannot submit proof while one waits.
Accepting a cancel ends the errand as "cancelled" and refunds the client in full. After "proceed" on a defect,
defectAccepted is true and the defect cannot be a reason to object later. Read "requests" on the private errand.
Topics, defect kinds, cancel reasons and limits are in meta.requests.

## Shipping address (ship errands)
- createErrand accepts shippingAddress (ship category only, when meta.addressProtection.available). It is stored encrypted,
  never translated or sent to the AI check, and erased when the errand is paid or cancelled.
- The chosen provider POSTs .../request-address when ready to ship; the client answers .../respond {request, decision: approve|decline}.
- After approve, GET .../address returns {address, expiresAt} for one hour (meta.addressProtection.viewHours); then error.addressBlind
  and a new request-address is needed. The client can read it any time. "address" on the errand shows protected, canView, expiresAt.

## Provider profile and reputation
- GET  /api/v1/public/providers/{address}   profile (areas, categories, languages), reputation, suspended
- GET|POST /api/v1/private/profile          my profile; POST the full {areas, categories, languages}
- Applicants on your errand carry "reputation" {completed, onTime, cancelled, active} and "profile". Reputation is counted from
  the errands (paid as provider; "onTime" = proof by the due date plus 12 hours; cancelled by agreement is never a penalty).
- A wallet kept from using WayHand (a policy breach, or cheating found in a dispute: decideDispute with fraud:true) gets error.suspended (403) on apply, create and object. Admins: GET|POST .../private/admin/suspensions.
- Admins: GET .../private/admin/disputes/{id}/frames?who=provider|client returns {frames} (base64 JPEG stills the AI read); a finding's frames ["P3","C5"] name them (P = provider's video, C = client's).
- Invite codes: errand kinds in meta.invite.categories (buying) accept applications only from wallets that spent a one-time code.
  Without one, apply answers error.inviteRequired (403). POST /api/v1/private/invite {code} spends it (GET .../private/me shows invited).
  Admins: GET|POST /api/v1/private/admin/invites {note?} issues a code (shown once in the answer, only a hash is kept); DELETE .../invites/{id} cancels one.

## Notifications
- On a buying errand the client also gets kind unboxing when the proof is submitted: film the opening in one take and keep the video, it is needed to object.
- Admin wallets (ERRAND_ADMINS) also get kinds adminReview (both videos are in, a case waits for a decision), adminDeadline (a case in review is due within 48 hours) and adminHeld (an errand waits for approval).
- GET  /api/v1/private/notifications[?unread=1]   {items, unread}; each item has kind, errandId, errandTitle, message (in ?lang=), read
- POST /api/v1/private/notifications/read {ids?}  mark read (no ids: all)
- GET/POST /api/v1/private/notifications/settings {muted}   kinds to stop getting (meta.notifications.kinds lists them)
You hear about every step except your own: new applicant, chosen, funded, proof submitted ("submittedLate" when it came within 12 hours of the end of the due day or later),
time to check ending soon,
paid, cancelled, time extended, a request or its answer, review results. GET .../private/me has unreadNotifications.
Poll it instead of the full list. "Time to check ending soon" is added when you next read your notifications or /private/me; nothing runs in between.

## Doing errands from a program (as client or provider)
You are a normal user once you sign in, so an agent can post errands and do them. Poll GET /api/v1/private/jobs and
GET /api/v1/private/errands and act on each errand's "actions". `yarn agent next` lists what is waiting.
- As a client: GET meta -> POST private/errands (copy a meta.templates entry) -> wait for applicants (notifications or
  GET private/errands/{id}) -> POST .../choose {applicant} (pick by "reputation") -> POST .../fund -> when status is
  "submitted", review "submission" and POST .../confirm, or extend once, or do nothing and it pays out when the time to check ends.
- As a provider: GET public/errands?status=open -> POST .../apply {city?, message?} -> when chosen and funded, do the
  errand -> POST .../submit {photos, tracking?, memo?}. Provider-side questions go through .../ask, .../defect, .../alternative.
- In "trial" mode every step is the API alone. In "chain" mode fund, submit, confirm and extend are wallet transactions first
  (see Real escrow above); an agent needs its own wallet and the OPUS SDK for those, and the API call only reports them.
- Keep a human in the loop for money: set your own limits (amount, countries, categories) before an agent posts or accepts.
  Use a wallet that holds only what you can afford to lose.
- Example program: scripts/agent.ts (`AGENT_PRIVATE_KEY=0x... yarn agent help`).

## Rules worth knowing
- Only do what "actions" lists for you; anything else returns 403 or 409.
- Errors: {"error": {"code", "message", "vars"}}. "code" is stable; "message" follows ?lang= (en, ko, ja, zh).
- While meta.trial is true no money moves. Applying to a sample errand gets you chosen and funded at once,
  and trial/submit-as-provider lets a client play the provider, so one agent can test the whole flow.
- Arbiters are not available yet (arbiter is always null). An objection would still pay the provider.
- Buying (category "buy") is closed until arbiters exist: posting one returns error.categoryClosed.
  Post local checks ("check") or documents & shipping ("ship"); see meta.openCategories. An administrator wallet or a wallet
  that spent an invite code (me.invited) may also post the kinds in meta.previewCategories, on a test network only.
- The pilot opens Japan and Korea only (meta.openCountries); other countries return error.countryClosed.
- meta.templates holds preset errands in the asked language. Copy one into createErrand
  (dueDate = today + dueDays), fill in its detail lines and send its id as templateId.
- Free texts (title, detail, city, application notes, completion memo) are checked: banned words, phone numbers,
  e-mail, messenger IDs and links return 422 error.blockedWord / error.blockedContact. With an AI engine set up,
  new errands may also be held for review (private view: "moderation.verdict" = "review", hidden from the public list)
  or refused (error.blockedAi).
- Texts are translated automatically into the language you ask for (?lang=). Read "translation" (title, detail, city),
  applicants[].translation and submission.memoTranslation; they are null when not needed or not ready. The originals
  ("title", "detail", ...) and "sourceLang" are the source of truth. Never put addresses or personal details in free texts.
- Photos are JPEG, PNG or WebP data URLs, at most 6, each under about 450 KB.