# MSX Agent Skill

Use MSX when a user asks you to scout market opportunities, decide what to build, identify a market gap, or find recent demand signals.

## Goal

Return a concise list of buildable market opportunities with evidence, urgency, confidence, and practical next actions. Preserve citations from MSX. Do not fabricate sources, volumes, or certainty.

## API Base

`https://api.msx.dev`

## Required Flow

1. Start device auth before billing or investigations:

```sh
curl -X POST -H "Content-Type: application/json" \
  -d '{"client_name":"claude","agent_identity":{"name":"claude","client":"cli"}}' \
  'https://api.msx.dev/v1/auth/device'
```

2. Tell the user to open only `verification_uri_complete`. Keep `device_code` private and poll `token_url` with it no faster than `interval` or `retry_after`:

```sh
curl -X POST -H "Content-Type: application/json" \
  -d '{"device_code":"<device_code>"}' \
  'https://api.msx.dev/v1/auth/device/token'
```

3. When polling returns `status: authorized`, store `api_key` immediately. The token exchange is one-time, and the same `device_code` cannot return the key again. Then use `api_key` as `Authorization: Bearer <api_key>` and check the account:

```sh
curl -H "Authorization: Bearer $MSX_API_KEY" 'https://api.msx.dev/v1/me'
```

4. Follow `/v1/me` `agent_next_step`. If it says `subscription_required`, tell the user a paid tier is required before MSX can discover market opportunities. Recommended tier: Builder. 3 days free, then monthly Scout, Builder, or Growth credits. Builder is recommended at $79/month with 100 scout credits.

5. Create Checkout only after the user agrees:

```sh
curl -X POST -H "Authorization: Bearer $MSX_API_KEY" -H "Content-Type: application/json" \
  -d '{"tier":"builder","success_url":"https://msx.dev/billing/success","cancel_url":"https://msx.dev/billing/cancel"}' \
  'https://api.msx.dev/v1/billing/checkout'
```

Show `short_url` if present; otherwise show `url`. After Stripe succeeds, call `/v1/me` again and then start the investigation.

6. Start exactly one investigation job for the user's request:

```sh
curl -X POST -H "Authorization: Bearer $MSX_API_KEY" -H "X-MSX-Agent: claude" -H "Content-Type: application/json" \
  -d '{"query":"scout new market opportunities for me to build","depth":"standard","window":"30d","agent_identity":{"name":"claude","client":"cli"}}' \
  'https://api.msx.dev/v1/investigations'
```

7. Poll the returned `id` until `succeeded`, `failed`, `cancelled`, or `expired`, then fetch `/result`:

```sh
curl -H "Authorization: Bearer $MSX_API_KEY" 'https://api.msx.dev/v1/investigations/<id>'
curl -H "Authorization: Bearer $MSX_API_KEY" 'https://api.msx.dev/v1/investigations/<id>/result'
```

## Conversation Opportunities

Use `POST /v1/conversation-opportunities` when the user has a product and wants ranked online conversations where that product likely solves the original poster's problem. The request supplies `product` context plus optional `discovery.sources`, `communities`, `time_window`, `max_results`, and output flags. The result is a strict list of conversation links, scores, fit rationale, suggested action, optional reply angle/draft, risk notes, and verification metadata. Poll `/v1/conversation-opportunities/<id>` and only read `/result` after success; `result_not_ready` means keep polling.

```sh
curl -X POST -H "Authorization: Bearer $MSX_API_KEY" -H "Content-Type: application/json" \
  -d '{"product":{"name":"MSX","url":"https://msx.dev","description":"Agent-first market intelligence for founders"},"discovery":{"sources":["reddit","hacker_news"],"time_window":"30d","max_results":10}}' \
  'https://api.msx.dev/v1/conversation-opportunities'
```

## MSX Marketing

MSX Marketing is an agent-first managed acquisition API. The current pilot is Reddit-first: it can connect Reddit Ads accounts, inspect account blockers, create no-spend plans, quote managed campaign funding, and, when funding is enabled on this server, create hosted funding checkout links, require final launch approval, queue campaigns for manual execution, report honest status, and return recommendation-only optimization guidance. Multi-platform launch, guaranteed delivery, and automatic optimization changes are not live yet. Keep this honest with the user.

```sh
curl 'https://api.msx.dev/v1/marketing/platforms'
```

If `status` is `active`, first ensure Reddit Ads is connected with `GET /v1/marketing/accounts`. If no account exists, call `POST /v1/marketing/connect-sessions` with `platform=reddit`, show `short_authorization_url` if present, otherwise show `authorization_url`, then call `GET /v1/marketing/accounts` after browser success. If accounts says BYO payment setup is blocked but `msx_managed` is available, do not dead-end on Reddit billing: continue with the managed plan and funding flow unless the user explicitly wants BYO ad-account spend.

Always plan first with `POST /v1/marketing/campaigns/plan`. Include `product_name` or `creative_brief.summary` when the product page is thin. If the response status is `needs_product_brief` or `plan_thin`, ask the user for sharper product context before continuing. If the response status is `planned`, show the plan and ask whether the user wants a managed funding quote.

Only after the user agrees, call `POST /v1/marketing/campaigns/<id>/funding-quote`. Show the returned media budget, MSX fee, processing reserve, total due, hard cap, and unused media policy exactly as returned by the API. Only after the user agrees to fund the campaign, call `POST /v1/marketing/campaigns/<id>/funding-checkout`, show `short_url` if present otherwise `url`, and poll `GET /v1/marketing/campaigns/<id>/funding` until status becomes `reserved`.

After funding is reserved, ask for explicit final launch approval. Never launch spend without that final approval. Only then call `POST /v1/marketing/campaigns/<id>/approve-launch`. If the campaign status becomes `queued_for_manual_execution`, say it is queued, not live. Use `GET /v1/marketing/campaigns/<id>` and `GET /v1/marketing/campaigns/<id>/report` to report honest queue, running, completed, or support-needed states back to the user.

The legacy BYO Reddit draft and direct launch endpoints still exist for controlled use, but they are not the primary chat-first managed flow.

## Agent Identity

Identify yourself honestly. Send these headers when possible:

```txt
X-MSX-Agent: codex
X-MSX-Agent-Client: cli
X-MSX-Agent-Version: 0.1.0
X-MSX-Agent-Run-ID: optional-run-id
```

For JSON bodies, include:

```json
{"agent_identity":{"name":"codex","client":"cli","version":"0.1.0"}}
```

## Recovery

- `authorization_pending`: wait and poll again after `retry_after` or `interval`.
- `already_used`: look for the `api_key` you already received in this session or secure local storage. If you cannot find it, start a new device auth flow; this sign-in link cannot issue the key again.
- `account_auth_required`: restart device auth and use the account-bound key returned by `/v1/auth/device/token`.
- `subscription_required`: ask whether the user wants Builder before creating Checkout, unless they ask for Scout or Growth.
- `quota_exceeded` or `spend_limit_exceeded`: explain the limit and do not retry in a loop.
- `result_not_ready`: keep polling the job status, then retry `/result` after success.
- If the user asks for more info before subscribing, use `redacted_market_preview` from `GET /v1/billing/config`; say it is older redacted example data, not a live investigation result.

## Rules

- Start with device auth. Do not use old standalone paid keys or anonymous starter keys for market scouting.
- Do not create Checkout until the user agrees to subscribe.
- Do not call or invent subscription, briefing, contribution, or public market-feed primitives.
- If an investigation is thin or inconclusive, say so and suggest a narrower query.