# Katch Mission API Agent Instructions

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

Agents should treat Katch as the physical-world evidence layer. The agent turns a data need into a mission, Katch authorizes exact funding calldata, the creator wallet funds it, humans submit media, and the creator wallet fetches accepted deliverables.

Katch uses World for contributor distribution, World App wallets, World Chain rewards, and World ID proof-of-personhood. World ID helps Katch resist sybil farming by checking that contributors are verified humans, but it does not determine whether media satisfies a mission. Mission rules, capture requirements, GPS checks, AI verification, and curation decide content acceptance.

## Required sequence

1. Build a `MissionDraftInput`, or run `katch mission generate --intent ...` when `OPENAI_API_KEY` is available.
2. Use concrete `verification.accept` and `verification.reject` rules.
3. Set `reward.token` to `KATCH` or `USDC`; external mission creation rejects WLD, ETH, and any other token.
4. Provide `--lat` and `--lng` for GPS/place missions; v1 does not geocode or invent coordinates.
5. Sign requests with the creator wallet, or with an authorized delegate bound to `KATCH_WALLET_ADDRESS`.
6. Prefer `katch mission launch --mission <file>` or `katch mission launch --intent ...`.
7. If launch validation fails, revise the draft. Do not proceed.
8. Read the launch response `next` object. If `next.action` is `broadcast_funding_transaction`, broadcast `next.sendTransaction` exactly as returned from the creator wallet.
9. If token allowance is too low, approve `funding.factoryAddress` for `funding.totalBudgetBaseUnits` before broadcasting funding.
10. If the authorization is expired or close to expiry, rerun launch before funding.
11. Call `POST /api/external/missions/{draftId}/confirm-funding`, or run `katch mission confirm <draftId>`.
12. Call `GET /api/external/missions/{draftId}` or run `katch mission doctor <draftId>` to inspect `nextAction`.
13. Current authorized drafts should move to `published` after confirmation.
14. After publication, fetch deliverables or listen for webhooks.

Low-level equivalent: call `POST /api/external/missions/preview`, then create the draft with an `Idempotency-Key`, then fund the returned quote.

## Hard rules

- Never insert into D1 directly.
- Never create public `missions` rows directly.
- Never invent or hand-encode on-chain calldata.
- Never skip preview.
- Never publish an unlocked third-party mission; current authorized funding locks the mission during the funding transaction.
- Always send `Idempotency-Key` on draft creation.
- Treat `nextAction` as the SDK/CLI state-machine hint.
- Use `katch mission doctor <draftId|missionId>` before guessing the next action.
- Use `accept` and `reject` arrays instead of vague prose.
- Use only `KATCH` or `USDC` for `reward.token` in external mission drafts.
- Use `katch mission launch ...` as the default mission creation command for agents.
- Use `katch mission plan --intent ...` to generate and preview intent-based missions before creating a draft.
- Use `katch mission create-from-intent --intent ... --idempotency-key <key>` only when draft creation is intended.
- Prefer external signer mode for the CLI: set `KATCH_SIGNER_ADDRESS` and `KATCH_SIGNER_COMMAND`.
- Use `KATCH_PRIVATE_KEY` only for local development with low-balance creator wallets.
- Never expose raw private keys to third-party agents, CLI args, mission JSON, logs, or docs examples.
- Do not assume Splits. Splits is one delegated signer option, but any authorized signer can sign Katch request messages.

## CLI external signer protocol

`KATCH_SIGNER_COMMAND` receives JSON on stdin:

```json
{"message":"Katch External Mission Request\n..."}
```

It must write JSON on stdout:

```json
{"signature":"0x..."}
```

The built-in `katch-signer` signs only messages that start with `Katch External Mission Request`.

## Signing message

```txt
Katch External Mission Request
METHOD: POST
PATH: /api/external/missions/preview
TIMESTAMP: <milliseconds since epoch>
BODY_SHA256: <sha256 hex of raw JSON body>
```

For delegated requests, bind the creator and signer:

```txt
WALLET: 0xcreator...
SIGNER: 0xdelegate...
```

## Deliverables

- Fetch deliverables only after publication and only as the creator wallet.
- Use `GET /api/external/missions/{id}/deliverables` or `client.getDeliverables(...)`.
- Use `katch mission deliverables <draftId|missionId> --markdown` to render the SDK Markdown report from the CLI.
- `{id}` may be an external draft ID or published mission ID.
- Only accepted and curation-accepted submissions are returned.
- Pending, flagged, rejected, and withdrawn submissions are not shared.
- Media URLs are short-lived proxy URLs; refresh the manifest when links expire.
- Katch does not run domain-specific extraction in v1. Agents should analyze media downstream and preserve submission IDs in reports.

## Webhooks

- Use webhooks for mission lifecycle and deliverables notifications.
- Verify `X-Katch-Webhook-Signature` before processing.
- Process `event.id` idempotently.
- Return 2xx only after safely recording the event.
- Use `katch webhook doctor <webhookId>` to send a signed test event and inspect delivery status.
- Rotate secrets with `katch webhook rotate-secret <webhookId>` if receiver secrets are stale or leaked.

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