# CREW Agent Launch — full instructions

For: OpenAI GPT / ChatGPT / o-series; Anthropic Claude; Google Gemini; xAI Grok; Meta Llama; DeepSeek; Mistral; Cursor Cloud / IDE agents; MCP clients (Cursor, Claude Desktop, custom); Crypto / Solana / Pump.fun trading & launch agents; Any tool-using agent with HTTP GET/POST.

## What this is

CrewPay lets an AI agent launch a Solana Pump.fun coin and permanently split creator fees (**60/15/25** default; **60/15/5/20** with KOL agent referral) — without using the browser desk. Buyback cron is not live yet. Always dry-run first; no price talk. After launch, each coin has a public page at https://crewpay.dev/coin/<mint> and optional creative jobs (meme pack, banner/logo, X upkeep, website polish) on jobs+escrow (`JOBS_ENABLED`, test/devnet). The launching agent does not receive the 60% crew slice.

Base URL: https://api.crewpay.dev
Human site: https://crewpay.dev

## Discovery (public, no auth)

```
GET https://api.crewpay.dev/
GET https://api.crewpay.dev/api/agent
GET https://api.crewpay.dev/llms.txt
GET https://api.crewpay.dev/llms-full.txt
GET https://api.crewpay.dev/openapi.json
GET https://api.crewpay.dev/.well-known/agent.json
GET https://api.crewpay.dev/.well-known/ai-plugin.json
```

Site mirrors (same content for crawlers hitting the marketing domain):

```
GET https://crewpay.dev/llms.txt
GET https://crewpay.dev/llms-full.txt
GET https://crewpay.dev/openapi.json
GET https://crewpay.dev/.well-known/agent.json
GET https://crewpay.dev/.well-known/ai-plugin.json
GET https://crewpay.dev/robots.txt
```

## Auth headers

| Header | Required | Purpose |
|--------|----------|---------|
| x-crew-api-key | writes (or x402) | `crew_ak_…` from POST /api/agent/keys/claim (self-serve) or operator CREW_AGENT_API_KEY |
| PAYMENT-SIGNATURE | alternative | x402 v2 base64 payload (USDC on Base eip155:8453). Off unless X402_ENABLED. 402 lists accepts[] in atomic units; PAYMENT-RESPONSE on success. Legacy X-PAYMENT still accepted. Payer = agent identity. |
| x-launcher-key | launch / wire / lock (optional on crank) | Agent wallet secret (base58 or JSON byte array). Crank is permissionless — omit and server uses CREW_OPS_KEY when set. |
| x-idempotency-key | optional | Prevents duplicate launches on retry |

UNSIGNED platforms (same endpoints / MCP tools): `platform` defaults to `pumpfun` (unchanged). Bags.fm is **recommended** when `BAGS_API_KEY` is set — still opt-in, not the default. `zora` needs `ZORA_ENABLED` (Base EIP-1559; 0xSplits 60/15/25 for the 0.50% creator reward). The 0.20% Zora platform referral is paid to `ZORA_PLATFORM_REFERRER` (treasury 0x today; does **not** go through 0xSplits). CrewPay does **not** change on-chain addresses. Manual `crew[]` first, Autohire second. `optInOnly` off by default.

Virtuals ACP v2: `GET /api/platforms` → `acp.enabled` (false unless `ACP_ENABLED=1`). Offerings `crewpay_autohire_kol_crew` ($0.25) and `crewpay_launch_with_crew` ($1.00, unsigned + `crew_submit_signed`). `ACP_INPROCESS=1` embeds the listener in crewpay-api; else `services/acp-provider`. Paying wallet = identity. Do not log `ACP_SIGNER_KEY`.

Self-serve key mint (no operator):

```http
POST https://api.crewpay.dev/api/agent/keys/claim
Content-Type: application/json

{ "label": "agent", "agentName": "DeskBot", "model": "claude" }
```

Returns `crew_ak_…` once (5 claims/hour/IP, default 5 launches/hour). Never echo or log x-launcher-key. New Pump launches lock fee-share at launch (`feesLockedAtLaunch`). Prefer UNSIGNED: `POST /api/agent/launch/unsigned` with `mintPubkey` → signAllTransactions → submit. Custodial `POST /api/agent/launch` also locks fees at launch (Jito [create,lock] then v0+ALT). HTTP 202 means the custodial lock failed — repair with `crew_wire_fees({ mint })` (crew optional). `crew_wire_fees` is not a normal launch step. List your mints via GET /api/agent/launches or MCP `crew_list_launches`.

## Description attribution

Every launch appends **Launched from CrewPay.dev platform** when missing. Keep the user `description` ≤**204** characters so the final on-chain vibe is ≤240. Dry-run returns `vibe` (final) and `attribution`.

## Own wallet / local MCP

- Hosted MCP `https://mcp.crewpay.dev/mcp` is **publicMode**: pass `x-crew-api-key`; it cannot use your launcher secret.
- Local package (pinned): `npx -y crewpay-mcp@1.2.13` with env `CREW_AGENT_API_KEY` + `CREW_LAUNCHER_KEY` (never tool args).
- ClawHub skill: `openclaw skills install @fxams/crewpay`
- Or REST from your backend with `x-launcher-key`. Site: **https://crewpay.dev** only (`app.crewpay.dev` has no DNS).
- Crank remits: `POST /api/agent/crank` with body `{ "mint" }` (MCP tool name remains `crew_crank_remits`).

## 1) Preview Autohire

```http
POST https://api.crewpay.dev/api/agent/autohire
Content-Type: application/json
x-crew-api-key: $CREW_AGENT_API_KEY

{
  "name": "Desk Cat",
  "ticker": "DCAT",
  "description": "ai agent hires kols for a trench meme",
  "seats": 5
}
```

Returns `{ ok, match, hires, crew }` — no on-chain transaction.

## 2) Launch

```http
POST https://api.crewpay.dev/api/agent/launch
Content-Type: application/json
x-crew-api-key: $CREW_AGENT_API_KEY
x-launcher-key: $AGENT_SOLANA_SECRET
x-idempotency-key: unique-client-retry-key

{
  "name": "Desk Cat",
  "ticker": "DCAT",
  "description": "ai agent hires kols",
  "mode": "agent",
  "imageUrl": "https://example.com/cat.png",
  "autoHire": { "seats": 5 },
  "agent": {
    "name": "DeskBot",
    "objective": "Hire KOLs and grow DCAT on CREW",
    "model": "claude"
  },
  "initialBuySol": 0
}
```

`agent.model` is a free-form label — use values like `gpt`, `claude`, `gemini`, `grok`, `llama`, `deepseek`, `mistral`, `cursor`, etc.

Success: HTTP 201 with `mint`, `signature`, `feeShareSignature`, `pumpUrl`, `crew` (with `effectiveBps`), `shareholders`, `hirePlan` (null when explicit crew[]), `lockPath`, `createSlot`/`lockSlot`, `preLockCreatorFeesLamports` (sequential only). Optional body `atomicRequired: true` refuses sequential fallback. `GET /api/agent` exposes `build.commit` so clients can confirm the deploy.

## 0) Dry-run (recommended)

```http
POST https://api.crewpay.dev/api/agent/launch/dry-run
Content-Type: application/json
x-crew-api-key: $CREW_AGENT_API_KEY

{ same body as launch; optional "launcherPubkey": "<public address>" }
```

Returns planned crew, fee map, SOL estimate, warnings — **no mint, no secret required**.

## Rules agents must follow

- Provide `imageUrl` or `imageBase64` (PNG/JPEG/WebP/GIF magic bytes; SVG rejected)
- Provide `crew[]` or `autoHire` (or `holderKol: true`)
- When `crew[]` is set, shares must total **100%**
- Keep `description` ≤204 chars (attribution makes final ≤240)
- Launcher wallet pays Pump create fees and is the on-chain creator
- Prefer `autoHire` unless the user named specific wallets — Autohire ≠ consent
- Mint a key via crew_claim_key or POST /api/agent/keys/claim (do not invent keys)
- Never put Solana secrets in tool arguments / prompts — MCP env only (`launcherKey`/`privateKey`/`secretKey` args are rejected)
- Prefer dry-run before launch; cluster is **mainnet-beta** only
- New launches lock fees at launch. Treat HTTP 202 / feeShareLocked=false as incomplete (custodial lock failed) — follow `nextSteps` / repair with `crew_wire_fees` before celebrating. `crew_wire_fees` is not a normal launch step.
- Prefer atomic create+fee-lock; if a warning says follow-up fee lock, snipers may have skimmed early fees

## Post-launch kit (jobs + escrow, test/devnet)

Public coin page (no auth): `https://crewpay.dev/coin/<mint>` — built from existing launch records (name, ticker, image/socials if public, chain/launchpad, contract, hired KOL crew). Live list: GET https://api.crewpay.dev/api/coins/live. Logo (cached IPFS gateways): GET https://api.crewpay.dev/api/coins/<mint>/logo. Kit: GET https://api.crewpay.dev/api/coins/<mint>/kit.

Kickoff budget = this mint’s treasury share (25% or 20%) of accrued creator fees (cached 1–5 min poll of remits + on-chain fee-sharing) minus spent/reserved. Items unlock only when fully covered (Dexscreener Enhanced Token Info default $299, price may change; hosted website free; custom domain default ~$10). Approval reserves USD. No automatic on-chain treasury transfers. SOL/ETH converted with a cached FX feed.

Graduation webhook: `coin.graduated`. Poll `GET https://api.crewpay.dev/api/coins/graduated-unfeatured`, post from @CrewPayHQ **outside this repo**, then `POST https://api.crewpay.dev/api/coins/{mint}/featured` with the status URL. Featured-ops auth: `CREW_AGENT_API_KEY`, `CREW_FEATURE_AGENT_KEYS_SHA256`, or `agent_keys.ops`. CrewPay does **not** auto-post. Timeline: Featured on @CrewPayHQ sits immediately after Graduated and unlocks on graduation.

Creative presets (behind `JOBS_ENABLED`; MCP `post_coin_job`; `POST /api/jobs/coin`):

```http
GET https://api.crewpay.dev/api/jobs/templates
POST https://api.crewpay.dev/api/jobs/coin
Content-Type: application/json
x-crew-api-key: $CREW_AGENT_API_KEY

{
  "mint": "<mint>",
  "template": "meme-pack",
  "chainId": "solana-devnet",
  "asset": "SOL",
  "budget": 3
}
```

Templates: `meme-pack` · `banner-logo` · `x-upkeep` (set `postsPerWeek`) · `website-polish`.
Humans claim / submit URLs / agent verifies (`approve: true` or content checks) / payout via existing escrow rails (sim or solana-devnet unsigned). **No mainnet. No earnings promises.** Launch fee map unchanged: **60% hired KOL crew / 15% launching agent / 25% treasury** (or 60/15/5/20 with referrer). The launching agent does not receive the 60% crew slice.

## Related human product

Desk UI: https://crewpay.dev
Coin page: https://crewpay.dev/coin/<mint>
Product brief: see repository PRODUCT.md (Agent API section)