# Katch Mission API

Katch is an API for the real world: agents pay verified humans to collect real-world photos and videos.

Agents use Katch when they need physical-world evidence. The agent creates a mission, Katch authorizes exact funding calldata, the creator funds it, humans submit media, and the creator wallet receives accepted deliverables.

For the contributor trust model, see `llms-world.txt`.

## Mental model

- A mission is a funded request for specific real-world evidence.
- The creator wallet owns drafts, webhook subscriptions, and deliverables access.
- The signer may be the creator wallet or an authorized delegate.
- Katch uses World ID for contributor proof-of-personhood and sybil resistance; this is separate from media verification.
- External mission rewards must use `KATCH` or `USDC`; reject or revise any mission draft using WLD, ETH, or another token.
- The Katch draft response is the source of truth for normalized mission shape, copy, verification rules, authorization, and funding calldata.
- Katch-authorized funding creates a locked mission; confirmation should publish it directly.
- Only accepted and curation-accepted submissions are shared as creator deliverables.

## Hard rules

- Prefer the `katch mission` CLI when available.
- Prefer `katch mission launch` for new third-party mission creation.
- Never write D1 directly.
- Never insert public `missions` rows directly.
- Never invent, hand-encode, or alter on-chain calldata.
- Never skip preview.
- Always send `Idempotency-Key` on draft creation.
- After funding succeeds, run `katch mission confirm <draftId>`; current authorized drafts should move to `published`.
- Do not assume Splits. Splits is one delegated signer option, not a requirement.
- Prefer `KATCH_SIGNER_ADDRESS` + `KATCH_SIGNER_COMMAND` for signed CLI requests so agents never receive raw private keys.
- Use `KATCH_PRIVATE_KEY` only for local development; never pass private keys as CLI args, mission JSON, logs, or docs examples.

## Mission creation sequence

1. Build a `MissionDraftInput`, or use `--intent ...` when `OPENAI_API_KEY` is available.
2. Set `reward.token` to `KATCH` or `USDC`; external missions do not support other reward tokens.
3. For GPS/place missions, provide `--lat` and `--lng`; Katch v1 does not geocode or invent coordinates.
4. Run `katch mission launch --mission <file>` or `katch mission launch --intent ...`.
5. Read the launch response `next` object. If `next.action` is `broadcast_funding_transaction`, broadcast `next.sendTransaction` from the creator wallet.
6. If token allowance is too low, approve `funding.factoryAddress` for `funding.totalBudgetBaseUnits` before broadcasting funding.
7. If the authorization is expired or close to expiry, rerun launch before funding.
8. Run `katch mission confirm <draftId>` after the funding transaction confirms.
9. Run `katch mission doctor <draftId|missionId>` to decide the next lifecycle action.

Use `katch mission create --guided --mission <file>` only when a separate preview-only step is needed.

## Outputs and events

- Fetch deliverables only after publication and only as the creator wallet.
- Use `client.getDeliverables(...)` or `GET /api/external/missions/{id}/deliverables`.
- Use `katch mission deliverables <draftId|missionId> --markdown` when a human-readable report is needed.
- Media URLs expire; refresh the manifest when links expire.
- Use webhooks for lifecycle notifications.
- Verify `X-Katch-Webhook-Signature` before processing.
- Process webhook `event.id` idempotently.
- Use `katch webhook doctor <webhookId>` to send a signed test event and inspect delivery status.

Supported mission types: `place_video`, `object_photo`, `egocentric_action_video`, `retail_photo`, `event_video`.