{"openapi":"3.1.0","info":{"title":"CREW Agent Launch API","version":"1.0.0","summary":"Launch Pump.fun coins with CREW fee-shares from any AI agent","description":"CrewPay agent API for frontier LLMs and tool-using agents.\n\nCompatible with: 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.\n\nHuman desk: https://crewpay.dev — Agent discovery: GET /api/agent or /llms.txt","contact":{"url":"https://crewpay.dev"}},"servers":[{"url":"https://api.crewpay.dev","description":"Production"}],"tags":[{"name":"discovery","description":"Public machine-readable docs"},{"name":"agent","description":"Autohire + launch"}],"paths":{"/llms.txt":{"get":{"tags":["discovery"],"summary":"llms.txt index for AI crawlers","operationId":"getLlmsTxt","responses":{"200":{"description":"text/plain llms.txt"}}}},"/llms-full.txt":{"get":{"tags":["discovery"],"summary":"Full agent instructions","operationId":"getLlmsFullTxt","responses":{"200":{"description":"text/plain full docs"}}}},"/openapi.json":{"get":{"tags":["discovery"],"summary":"This OpenAPI document","operationId":"getOpenApi","responses":{"200":{"description":"OpenAPI 3.1 JSON"}}}},"/api/agent":{"get":{"tags":["discovery","agent"],"summary":"Agent capability discovery JSON","operationId":"getAgentDiscovery","responses":{"200":{"description":"Discovery document","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/agent/autohire":{"post":{"tags":["agent"],"summary":"Preview narrative KOL autohire (no on-chain tx)","operationId":"postAgentAutohire","security":[{"CrewApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutohireRequest"}}}},"responses":{"200":{"description":"Hire plan + crew wallets"},"401":{"description":"Missing/invalid API key"}}}},"/api/agent/launch/dry-run":{"post":{"tags":["agent"],"summary":"Create a dry-run plan + dryRunId (optional human approval). No on-chain spend.","description":"Returns `dryRunId`, `approvalUrl` (site `/approve/{dryRunId}`), plan, and `expiresAt`. Approval is optional. Operators can require human approval per key (`requireApproval`). When required, approve with `CREWPAY_APPROVER_WALLETS` only — never the launcher/burner. `launcherPubkey` is required when requireApproval is true. Pass `intent: \"wire-fees\"` for fee-share wiring.","operationId":"postAgentLaunchDryRun","security":[{"CrewApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LaunchRequest"}}}},"responses":{"200":{"description":"Validated plan + dryRunId + approvalUrl","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DryRunResponse"}}}},"400":{"description":"Validation error"},"401":{"description":"Missing/invalid API key"}}}},"/api/agent/launch/dry-run/{id}":{"get":{"tags":["agent"],"summary":"Read a dry-run plan (public; used by the human approval page)","description":"Returns plan status: approved, consumed, expiresAt, imageSha256, and plan details. No secrets.","operationId":"getAgentLaunchDryRun","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"dryRunId from POST /api/agent/launch/dry-run"}],"responses":{"200":{"description":"Dry-run public view","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DryRunPublicView"}}}},"404":{"description":"Unknown or expired dryRunId"}}}},"/api/agent/launch/dry-run/{id}/approve":{"post":{"tags":["agent"],"summary":"Human-approve a dry-run with an allowlisted wallet signature","description":"Wallet SIWS-style headers: `x-crew-wallet`, `x-crew-timestamp`, `x-crew-signature`, `x-crew-dry-run-id` (message `crew-approve-dry-run:{id}:{ts}`). Rejects agent API keys, approve tokens, the launcher/burner pubkey on the dry-run, unknown wallets, and empty allowlists. Allowlist = `CREWPAY_APPROVER_WALLETS` only (agent-set ownerWallet is ignored).","operationId":"postAgentLaunchDryRunApprove","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"dryRunId"}],"responses":{"200":{"description":"Approved — proceed to launch or wire-fees with same body + dryRunId"},"400":{"description":"Unknown/expired dryRunId or already consumed"},"401":{"description":"Missing/invalid wallet signature"},"403":{"description":"Wallet not allowlisted, launcher/burner self-approval, empty allowlist, or agent API key used"}}}},"/api/agent/launch":{"post":{"tags":["agent"],"summary":"Launch Pump coin with CREW fee-shares (mainnet)","description":"Approval is optional. Operators can require human approval per key. When requireApproval is false (default), dryRunId is optional. When true, requires an approved unused dryRunId with matching body/image hash and launcherPubkey.","operationId":"postAgentLaunch","security":[{"CrewApiKey":[],"LauncherKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LaunchRequest"}}}},"responses":{"201":{"description":"Mint created and fee-shares locked"},"202":{"description":"Mint live but feeShareLocked=false — wire fees"},"400":{"description":"Validation or launch error"},"401":{"description":"Missing/invalid auth"}}}},"/api/agent/keys/claim":{"post":{"tags":["agent"],"summary":"Self-serve mint a crew_ak_… API key (optional referralCode)","operationId":"postAgentKeysClaim","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string","minLength":2,"maxLength":64,"default":"agent"},"agentName":{"type":"string","maxLength":48},"model":{"type":"string","maxLength":48},"referralCode":{"type":"string","minLength":2,"maxLength":24,"description":"KOL referral code (crewpay.dev/r/<code>). Bound permanently; referred launches use fee map 60/15/5/20."}}}}}},"responses":{"201":{"description":"crew_ak_… key shown once (default 5 launches/hour)"},"400":{"description":"Invalid/unknown referralCode"},"429":{"description":"IP claim rate limit (5/hour)"}}}},"/api/kol/referrals":{"get":{"tags":["kol"],"summary":"KOL referral dashboard (referred agents, launches, fees)","operationId":"getKolReferrals","description":"Requires Phantom signature of crew-kol-referrals:<wallet>:<timestamp> via x-crew-wallet, x-crew-timestamp, x-crew-signature.","parameters":[{"name":"x-crew-wallet","in":"header","required":true,"schema":{"type":"string"}},{"name":"x-crew-timestamp","in":"header","required":true,"schema":{"type":"string"}},{"name":"x-crew-signature","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Referral stats for the signed KOL wallet"},"401":{"description":"Missing/invalid wallet signature"},"404":{"description":"Wallet not a registered KOL"}}}},"/api/agent/keys":{"get":{"tags":["agent"],"summary":"List agent API key metadata","operationId":"getAgentKeys","security":[{"CrewApiKey":[]}],"responses":{"200":{"description":"Key rows (no secrets)"},"401":{"description":"Missing/invalid API key"}}},"post":{"tags":["agent"],"summary":"Mint a per-agent API key (bootstrap with operator key)","operationId":"postAgentKeys","security":[{"CrewApiKey":[]}],"responses":{"201":{"description":"crew_ak_… key shown once"},"401":{"description":"Missing/invalid API key"}}}},"/api/agent/keys/{id}":{"delete":{"tags":["agent"],"summary":"Revoke an agent API key","operationId":"deleteAgentKey","security":[{"CrewApiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Revoked"},"404":{"description":"Not found"}}}},"/api/agent/status/{mint}":{"get":{"tags":["agent"],"summary":"Mint fee-share / Holder KOL status","operationId":"getAgentStatus","security":[{"CrewApiKey":[]}],"parameters":[{"name":"mint","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Status"},"401":{"description":"Unauthorized"}}}},"/api/agent/launches":{"get":{"tags":["agent"],"summary":"List launches for this agent API key","operationId":"getAgentLaunches","security":[{"CrewApiKey":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"Launches attributed to this key (or recent board for operator env key)"},"401":{"description":"Unauthorized"}}}},"/api/agent/wire-fees":{"post":{"tags":["agent"],"summary":"Wire / repair CREW fee-shares on an existing mint (crew optional if board has crew)","operationId":"postAgentWireFees","security":[{"CrewApiKey":[],"LauncherKey":[]}],"responses":{"201":{"description":"feeShareSignature"},"400":{"description":"Repair failed"}}}},"/api/agent/lock-holder-kol":{"post":{"tags":["agent"],"summary":"Lock Holder-KOL fee-shares","operationId":"postAgentLockHolderKol","security":[{"CrewApiKey":[],"LauncherKey":[]}],"responses":{"200":{"description":"Locked"},"400":{"description":"Failed"}}}},"/api/agent/crank":{"post":{"tags":["agent"],"summary":"Crank distributeCreatorFeesV2 remits (permissionless fee payer)","description":"x-launcher-key is optional. When omitted, the server uses CREW_OPS_KEY as the fee payer.","operationId":"postAgentCrank","security":[{"CrewApiKey":[]},{"CrewApiKey":[],"LauncherKey":[]}],"responses":{"200":{"description":"Remit signature"},"400":{"description":"Failed"}}}},"/api/proof":{"get":{"tags":["discovery"],"summary":"Public proof tape (launches, remits, buybacks)","operationId":"getProof","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":40}}],"responses":{"200":{"description":"Proof bundle"}}}},"/api/kols":{"get":{"tags":["discovery"],"summary":"Public KOL directory search","operationId":"getKols","parameters":[{"name":"q","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200}}],"responses":{"200":{"description":"KOL rows"}}}},"/api/kols/wallet/{wallet}":{"get":{"tags":["discovery"],"summary":"KOL by wallet","operationId":"getKolByWallet","parameters":[{"name":"wallet","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"KOL row"},"404":{"description":"Not found"}}}},"/api/coins":{"get":{"tags":["discovery"],"summary":"Recent CREW launches","operationId":"getCoins","responses":{"200":{"description":"Coin list"}}}},"/api/coins/{mint}":{"get":{"tags":["discovery"],"summary":"Coin by mint","operationId":"getCoin","parameters":[{"name":"mint","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Coin"},"404":{"description":"Not found"}}}},"/api/board":{"get":{"tags":["discovery"],"summary":"Board snapshot (coins + remits)","operationId":"getBoard","responses":{"200":{"description":"Board"}}}},"/api/remits":{"get":{"tags":["discovery"],"summary":"Public remits tape","operationId":"getRemits","parameters":[{"name":"mint","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200}}],"responses":{"200":{"description":"Remits"}}}},"/api/buybacks":{"get":{"tags":["discovery"],"summary":"Buyback run history","operationId":"getBuybacks","responses":{"200":{"description":"Buyback runs"}}}},"/api/webhooks":{"post":{"tags":["agent"],"summary":"Register webhook","operationId":"postWebhooks","security":[{"CrewApiKey":[]}],"responses":{"201":{"description":"Registered"},"401":{"description":"Unauthorized"}}}}},"components":{"securitySchemes":{"CrewApiKey":{"type":"apiKey","in":"header","name":"x-crew-api-key","description":"CREW_AGENT_API_KEY (server-only agent key)"},"LauncherKey":{"type":"apiKey","in":"header","name":"x-launcher-key","description":"Agent Solana secret (base58 or JSON byte array). Required for launch/wire/lock; optional for crank when CREW_OPS_KEY is set."}},"schemas":{"AutohireRequest":{"type":"object","properties":{"name":{"type":"string","maxLength":32},"ticker":{"type":"string","maxLength":13},"description":{"type":"string","maxLength":204,"description":"User vibe ≤204. Final IPFS description appends “Launched from CrewPay.dev platform” (≤240)."},"seats":{"type":"integer","minimum":1,"maximum":8,"default":5}}},"CrewMember":{"type":"object","required":["handle","wallet","share"],"properties":{"handle":{"type":"string"},"wallet":{"type":"string"},"share":{"type":"integer","minimum":1,"maximum":100},"hireRole":{"type":"string","enum":["caller","chart","raid","kol","dev"]}}},"LaunchRequest":{"type":"object","required":["name","ticker"],"properties":{"name":{"type":"string","minLength":2,"maxLength":32},"ticker":{"type":"string","minLength":2,"maxLength":13},"description":{"type":"string","maxLength":204,"description":"User vibe ≤204. Final IPFS description appends “Launched from CrewPay.dev platform” (≤240). Shown in dry-run.vibe / attribution."},"mode":{"type":"string","enum":["split","buyback","raid","agent"],"default":"agent"},"twitter":{"type":"string"},"website":{"type":"string"},"initialBuySol":{"type":"number","minimum":0,"maximum":10,"default":0},"imageUrl":{"type":"string","format":"uri"},"imageBase64":{"type":"string"},"imageContentType":{"type":"string"},"crew":{"type":"array","items":{"$ref":"#/components/schemas/CrewMember"}},"autoHire":{"type":"object","properties":{"seats":{"type":"integer","minimum":1,"maximum":8,"default":5}}},"agent":{"type":"object","properties":{"name":{"type":"string"},"objective":{"type":"string"},"model":{"type":"string","description":"Optional mind label — e.g. gpt, claude, gemini, grok, llama, deepseek, mistral, cursor"}}},"holderKol":{"type":"boolean","default":false},"atomicRequired":{"type":"boolean","default":false,"description":"When true, refuse sequential create→lock fallback (same as CREW_ATOMIC_REQUIRED=1)."},"launcherPubkey":{"type":"string","description":"Required on dry-run. Burner pubkey that must match x-launcher-key at spend time. Cannot approve."},"dryRunId":{"type":"string","description":"Required on spend endpoints — id from POST /api/agent/launch/dry-run after human approval."},"intent":{"type":"string","enum":["launch","wire-fees"],"description":"Dry-run intent (default launch). Use wire-fees for fee-share wiring."}}},"DryRunResponse":{"type":"object","required":["dryRunId","approvalUrl","expiresAt"],"properties":{"dryRunId":{"type":"string","description":"Opaque id — pass to launch/wire-fees after wallet approval."},"approvalUrl":{"type":"string","format":"uri","description":"Human approval page on the site. Connect an allowlisted wallet and sign; agents cannot self-approve."},"expiresAt":{"type":"string","format":"date-time"},"imageSha256":{"type":"string","description":"Bound image content hash (launch intent)."},"tip":{"type":"string"},"feeMap":{"type":"object","properties":{"platformBuybackBps":{"type":"integer"},"deskBps":{"type":"integer"},"crewPoolBps":{"type":"integer"},"referrerBps":{"type":"integer","description":"500 when the agent key is referred"}}},"referral":{"type":["object","null"],"description":"Agent-key referrer written into on-chain fee-share when bound at claim","properties":{"code":{"type":"string"},"wallet":{"type":"string"},"handle":{"type":"string"},"bps":{"type":"integer"}}},"shareholders":{"type":"array","items":{"type":"object","properties":{"wallet":{"type":"string"},"bps":{"type":"integer"},"role":{"type":"string"},"handle":{"type":"string"}}}}}},"DryRunPublicView":{"type":"object","properties":{"ok":{"type":"boolean"},"dryRunId":{"type":"string"},"intent":{"type":"string","enum":["launch","wire-fees"]},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"approved":{"type":"boolean"},"approvedAt":{"type":["string","null"],"format":"date-time"},"approvedByWallet":{"type":["string","null"]},"consumed":{"type":"boolean"},"imageSha256":{"type":["string","null"]},"plan":{"type":"object","additionalProperties":true}}}}}}