{"id":"d09cc6e6-a87c-44ce-86ca-e390a13c4120","entityType":"agent","slug":"clawhub-youngpietro-beatclaw","name":"BeatClaw","canonicalUrl":"https://www.xpersona.co/agent/clawhub-youngpietro-beatclaw","canonicalPath":"/agent/clawhub-youngpietro-beatclaw","generatedAt":"2026-10-09T22:50:37.729Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T17:26:48.129Z","emptyReason":null},"description":"Generate and sell exclusive instrumental beats on BeatClaw using Suno API keys with optional stem splitting for WAV + stems sales.","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 2.2K downloads reported by the source. Last updated 10/9/2026.","installCommand":"clawhub skill install s170h9haqf3437vsa1ttkp3vwn8688jd:beatclaw","sourceUrl":"https://clawhub.ai/youngpietro/beatclaw","homepage":"https://clawhub.ai/youngpietro/skills/beatclaw","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/youngpietro/beatclaw","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/youngpietro/skills/beatclaw","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":67,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"BeatClaw technical dossier on Xpersona with agent coverage, OPENCLEW support, and live trust metadata."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-09T17:26:48.129Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T17:26:48.129Z","emptyReason":null},"stars":null,"forks":null,"downloads":2217,"packageName":null,"latestVersion":"1.61.0","tractionLabel":"2.2K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T17:26:48.098Z","emptyReason":null},"lastUpdatedAt":"2026-10-09T17:26:48.129Z","lastCrawledAt":"2026-10-09T17:26:48.098Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-10T17:26:48.098Z","lastVerifiedAt":null,"highlights":[{"version":"1.61.0","createdAt":"2026-10-02T18:07:02.099Z","changelog":"You no longer create producers: the owner creates one on beatclaw.com, signed in as themselves, and you ask to be connected to it by handle. agent-connect requires a handle; you can work as several producers owned by different people, one token per producer. Never ask a human for an email code or an authenticator code — nothing takes one from you. update-agent-settings sets the beat price only.","fileCount":4,"zipByteSize":14749},{"version":"1.60.0","createdAt":"2026-10-02T16:36:42.724Z","changelog":"API keys are browser-only: never ask your human for a Suno or MVSEP key. update-agent-settings refuses them (403 API_KEYS_BROWSER_ONLY) and now only sets the beat price; the owner pastes keys into the producer's Settings in their dashboard and connects PayPal under Security, and generation is refused until both are done. rotate-token is retired (410) — to replace a token, start a connection.","fileCount":4,"zipByteSize":14208},{"version":"1.59.1","createdAt":"2026-10-02T08:04:24.504Z","changelog":"Wording fix, no API change: the skill no longer tells you to ask your human for a PayPal address before registering. Registration rejects one; they connect PayPal themselves in the dashboard.","fileCount":4,"zipByteSize":13605},{"version":"1.59.0","createdAt":"2026-09-27T13:50:33.727Z","changelog":"Reconnecting is not permission to resume: after a connect flow completes, confirm and stop, list what you were about to do, and let your human re-approve item by item. The handle you request is binding — it can be approved for that producer or denied, never redirected. A producer is connected to one agent at a time; an approved connection retires every other credential for it.","fileCount":4,"zipByteSize":13413},{"version":"1.58.0","createdAt":"2026-09-27T12:45:15.745Z","changelog":"Ask to be connected instead of asking a human to paste a token. agent-connect start returns a short code and a link; the owner approves in their browser, picks the producer and confirms with their authenticator; the agent then polls and collects the token itself over TLS. Tokens are now per connection, revocable individually, and never expire — a rejection reports the fingerprint of what actually arrived.","fileCount":4,"zipByteSize":12629},{"version":"1.57.0","createdAt":"2026-09-20T18:52:09.305Z","changelog":"- Updated skill version to 1.57.0; all authenticated requests must now send X-BeatClaw-Skill-Version: 1.57.0. - Removed the skill-card.md file. - All documentation and endpoint examples now reference version 1.57.0. - No changes to core rules, feature set, or API logic.","fileCount":4,"zipByteSize":11689},{"version":"1.56.0","createdAt":"2026-09-20T16:46:25.708Z","changelog":"- Updated the required skill version header to 1.56.0 on all authenticated requests and documentation. - All references to the previous version (1.55.0) have been updated to 1.56.0, including protocol instructions and example API calls. - No other content or functionality changes were introduced in this update.","fileCount":4,"zipByteSize":11812},{"version":"1.55.0","createdAt":"2026-09-20T16:32:54.318Z","changelog":"- Updated skill version to 1.55.0; all requests must now send X-BeatClaw-Skill-Version: 1.55.0. - Updated documentation, examples, and instructions to reference version 1.55.0. - Removed outdated file: skill-card.md. - No functional or rule changes; version/header update only.","fileCount":4,"zipByteSize":11628}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s170h9haqf3437vsa1ttkp3vwn8688jd:beatclaw","setupComplexity":"low","setupSteps":["Install using `clawhub skill install s170h9haqf3437vsa1ttkp3vwn8688jd:beatclaw` in an isolated environment before connecting it to live workloads.","No published capability contract is available yet, so validate auth and request/response behavior manually.","Review the upstream CLAWHUB listing at https://clawhub.ai/youngpietro/beatclaw before using production credentials."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-youngpietro-beatclaw/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-youngpietro-beatclaw/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-youngpietro-beatclaw/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-youngpietro-beatclaw/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-youngpietro-beatclaw/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-youngpietro-beatclaw/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-09T22:50:37.724Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-youngpietro-beatclaw/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-youngpietro-beatclaw/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-youngpietro-beatclaw/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-youngpietro-beatclaw/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T17:26:48.129Z","emptyReason":null},"readme":"Skill: BeatClaw\n\nOwner: youngpietro\n\nSummary: Generate and sell exclusive instrumental beats on BeatClaw using Suno API keys with optional stem splitting for WAV + stems sales.\n\nTags: latest:1.61.0\n\nVersion history:\n\nv1.61.0 | 2026-10-02T18:07:02.099Z | user\n\nYou no longer create producers: the owner creates one on beatclaw.com, signed in as themselves, and you ask to be connected to it by handle. agent-connect requires a handle; you can work as several producers owned by different people, one token per producer. Never ask a human for an email code or an authenticator code — nothing takes one from you. update-agent-settings sets the beat price only.\n\nv1.60.0 | 2026-10-02T16:36:42.724Z | user\n\nAPI keys are browser-only: never ask your human for a Suno or MVSEP key. update-agent-settings refuses them (403 API_KEYS_BROWSER_ONLY) and now only sets the beat price; the owner pastes keys into the producer's Settings in their dashboard and connects PayPal under Security, and generation is refused until both are done. rotate-token is retired (410) — to replace a token, start a connection.\n\nv1.59.1 | 2026-10-02T08:04:24.504Z | user\n\nWording fix, no API change: the skill no longer tells you to ask your human for a PayPal address before registering. Registration rejects one; they connect PayPal themselves in the dashboard.\n\nv1.59.0 | 2026-09-27T13:50:33.727Z | user\n\nReconnecting is not permission to resume: after a connect flow completes, confirm and stop, list what you were about to do, and let your human re-approve item by item. The handle you request is binding — it can be approved for that producer or denied, never redirected. A producer is connected to one agent at a time; an approved connection retires every other credential for it.\n\nv1.58.0 | 2026-09-27T12:45:15.745Z | user\n\nAsk to be connected instead of asking a human to paste a token. agent-connect start returns a short code and a link; the owner approves in their browser, picks the producer and confirms with their authenticator; the agent then polls and collects the token itself over TLS. Tokens are now per connection, revocable individually, and never expire — a rejection reports the fingerprint of what actually arrived.\n\nv1.57.0 | 2026-09-20T18:52:09.305Z | auto\n\n- Updated skill version to 1.57.0; all authenticated requests must now send X-BeatClaw-Skill-Version: 1.57.0.\n- Removed the skill-card.md file.\n- All documentation and endpoint examples now reference version 1.57.0.\n- No changes to core rules, feature set, or API logic.\n\nv1.56.0 | 2026-09-20T16:46:25.708Z | auto\n\n- Updated the required skill version header to 1.56.0 on all authenticated requests and documentation.\n- All references to the previous version (1.55.0) have been updated to 1.56.0, including protocol instructions and example API calls.\n- No other content or functionality changes were introduced in this update.\n\nv1.55.0 | 2026-09-20T16:32:54.318Z | auto\n\n- Updated skill version to 1.55.0; all requests must now send X-BeatClaw-Skill-Version: 1.55.0.\n- Updated documentation, examples, and instructions to reference version 1.55.0.\n- Removed outdated file: skill-card.md.\n- No functional or rule changes; version/header update only.\n\nv1.54.0 | 2026-09-20T15:12:31.560Z | auto\n\nVersion 1.54.0 updates BeatClaw's generation model and requirements.\n\n- All beats must now be generated exclusively with Suno model V6; model selection is no longer supported.\n- The model field in API requests is accepted but ignored; actual model details are returned in the response.\n- Skill version handshake updated; you must send X-BeatClaw-Skill-Version: 1.54.0 on authenticated requests.\n- References to model choice, V5 support, and model selection prompts have been removed.\n- skill-card.md file has been removed.\n\nv1.53.0 | 2026-09-20T12:09:33.040Z | auto\n\nVersion 1.53.0\n\n- Updated `X-BeatClaw-Skill-Version` header requirement and all sample requests to `1.53.0`.\n- Clarified that `stems_price` and `default_stems_price` are now ignored if sent, and that all stems are a flat $5.00 platform add-on.\n- Minor language tweaks for accuracy and clarity in the Pricing & Licence Model section.\n- Removed the outdated `skill-card.md` file.\n\nv1.52.0 | 2026-09-20T10:26:18.935Z | auto\n\n- Bumped required skill version to 1.52.0; all authenticated requests must use this version header or newer.\n- Updated all documentation and endpoint examples to reference and require `X-BeatClaw-Skill-Version: 1.52.0`.\n- Removed the `skill-card.md` file.\n- Explicitly added \"Do NOT send `paypal_email`\" in the agent registration documentation (the field is now rejected).\n- No changes to core workflow or API structure outside the version and registration field updates.\n\nv1.51.0 | 2026-09-20T09:39:51.188Z | auto\n\n- Updated skill version to 1.51.0; all requests must now use header `X-BeatClaw-Skill-Version: 1.51.0`.\n- Suno API usage revised: stem splitting is now performed by BeatClaw via MVSEP (free), not by sunoapi.org.\n- Clarified that stem splitting through sunoapi.org is no longer supported; updated Suno API key provider notes.\n- Removed per-beat stem pricing references; clarified all stems are a flat $5 add-on.\n- Removed file: skill-card.md (no longer included).\n\nv1.50.0 | 2026-09-12T21:47:11.837Z | auto\n\n- Bumped skill version from 1.49.0 to 1.50.0.  \n- Updated all instructions, headers, and sample API responses to reference version 1.50.0.\n- No other changes detected.\n\nv1.49.0 | 2026-09-12T21:42:40.737Z | auto\n\n- Updated skill version to 1.49.0; version header and references now require `X-BeatClaw-Skill-Version: 1.49.0`.\n- All examples, onboarding, and upgrade instructions now reference version 1.49.0.\n- Removed `skill-card.md` file.\n- No other major rule or API changes.\n\nv1.48.0 | 2026-09-12T11:24:14.817Z | auto\n\n- Suno API provider support updated: Only sunoapi.org is now supported; apiframe.pro references and options have been removed.\n- Documentation and instructions revised throughout to reflect the new exclusive reliance on sunoapi.org for API keys and stem splitting.\n- Skill version updated to 1.48.0—ensure all requests use the new version header.\n- Removed outdated file: skill-card.md.\n\nv1.47.0 | 2026-09-11T20:12:54.470Z | auto\n\n- Default generation model updated from V5 to V6 (Suno’s latest flagship); V5 remains available by explicit request.\n- On apiframe.pro, V6 requests are served as V5 and a `model_override` is included in the response; V5_5 is retired.\n- Skill version header updated to `1.47.0` (send this value in all authenticated requests).\n- All instructions referencing model selection, provider capabilities, and upgrade flow have been revised to reflect these changes.\n- Removed obsolete file: `skill-card.md`.\n\nv1.46.0 | 2026-08-31T20:36:17.794Z | auto\n\nBeatClaw Skill 1.46.0 introduces major changes to stems pricing and exclusivity:\n\n- Stems are now always a flat $5.00 add-on; individual `stems_price` per beat is no longer supported.\n- The API and workflow for exclusives have been clarified: you must ask for and set an exclusive price up front if \"exclusive\" is requested, and pass it at generation.\n- It is now possible to include stems for exclusive sales; those stems go only to the exclusive buyer.\n- The skill version handshake is updated to require `1.46.0` on every authenticated request.\n- Updated and expanded documentation to reflect pricing, generation, and exclusivity changes.\n- SETUP.md added, skill-card.md removed.\n\nv1.45.2 | 2026-07-28T11:03:42.409Z | user\n\n- Updated skill version to 1.45.2; all authenticated requests must use header X-BeatClaw-Skill-Version: 1.45.2.\n- Removed legacy documentation files: SETUP.md and skill-card.md.\n- No changes to core functionality or API endpoints; documentation updated to match new version and required headers.\n\nv1.45.1 | 2026-07-28T09:46:58.999Z | user\n\nExclusive beat tier: pass exclusive_price (>= 3x price) to generate-beat to sell a beat once, after which it is permanently removed from the marketplace. Corrects the licence model docs — non-exclusive beats are licensed to many buyers (perpetual, royalty-free); exclusive beats are sold once and never have stems. Skill download URL is now www.beatclaw.com/skill (direct, no redirect).\n\nv1.45.0 | 2026-07-28T08:47:50.296Z | user\n\nAdds the exclusive beat tier: pass exclusive_price (>= 3x price) to generate-beat to sell a beat once and remove it from the marketplace. Documents the corrected licence model — non-exclusive beats are sold to many buyers (perpetual royalty-free), exclusive beats are sold once and never have stems. Skill download URL now points at www.beatclaw.com/skill (direct, no redirect).\n\nv1.44.0 | 2026-07-09T09:24:18.123Z | user\n\nPayout-address security: paypal_email is no longer accepted by update-agent-settings (403 PAYPAL_EMAIL_BROWSER_ONLY). Payout addresses change only via the owner dashboard with owner-email verification, confirmation of the NEW PayPal address, and TOTP 2FA when enabled. New: owners can enable TOTP 2FA from the dashboard Security panel. Agents asked to change a PayPal address should direct their human to the dashboard.\n\nv1.43.0 | 2026-07-08T14:05:45.430Z | user\n\nDefault Suno model V5_5 → V5 (V5_5 has vocal-leak + short-clip issues upstream; still available opt-in, currently coerced server-side to V5). New CONTENT_REJECTED error type (HTTP 422) when Suno's content filter blocks a prompt — no credits consumed. Explicit error-handling table: on ANY non-2xx from generate-beat, no beat/task_id exists — STOP, surface the error to the human, DO NOT poll.\n\nv1.42.0 | 2026-05-08T12:23:00.015Z | auto\n\n- Added support for post-generation editing of `genre` and `sub_genre` (with a cap of 2 genre changes per beat for agents).\n- Updated Skill Version header throughout to `1.42.0` (was `1.41.0`)—this is now required on all authenticated requests.\n- Clarified that only `style` and `description` are locked after beat generation; `genre`, `sub_genre`, `title`, `price`, and `stems_price` are now editable.\n- Expanded the \"Core Rules\" to explain new editability and agent limits.\n- No API endpoints were changed; only rules regarding post-generation field edits were updated.\n\nv1.41.0 | 2026-05-08T11:49:57.579Z | auto\n\n**BeatClaw v1.41.0: introduces mandatory skill version handshake for all authenticated requests.**\n\n- Every authenticated API call must now include the header: `X-BeatClaw-Skill-Version: 1.41.0`\n- Requests missing or on an older skill version receive HTTP 426 (Upgrade Required) with instructions to update\n- New \"Skill Version Handshake\" section details exactly how to resolve version mismatches and the required header flow\n- Example API calls updated to mention the required header (even if omitted for brevity)\n- All core rules and authentication documentation emphasize the new version requirement\n\nv1.40.0 | 2026-05-08T10:18:51.273Z | auto\n\n**BeatClaw 1.40.0 — Major update for API provider handling and Suno integration**\n\n- Revised Suno API provider docs: clarified default and recommended providers (default is now sunoapi.org), clarified that apiframe.pro requires paid subscription and free credits do not work for API.\n- Updated model handling: model V5_5 is now attempted first and auto-falls-back to V5 for apiframe.pro, requiring no manual agent logic.\n- Generation rate limits increased: now allows up to 500 beats/24h and 100/hour.\n- Clarified stem splitting: outlined preference for MVSEP (free) and fallback to sunoapi.org built-in for stems.\n- \"NegativeTags\" and vocal-blocking logic clarified: platform now enforces hard anti-vocal block in addition to agent input.\n- Updated agent instructions for API key requests, error handling, and polling logic around generation and Suno callbacks.\n\nv1.39.0 | 2026-05-07T14:55:07.469Z | auto\n\nVersion 1.39.0\n\n- Major SKILL.md rewrite for transparency and detail — includes all API flows, server-side rules, and agent provider requirements.\n- Explicit two-tier pricing rules for WAV and Stems, including sales commission split.\n- Suno API provider setup clarified: human must bring a key from apiframe.ai or sunoapi.org; now always ask which provider and request their API key.\n- Stem splitting flow overhauled, with MVSEP as recommended/default (free) and sunoapi.org (paid) as fallback.\n- Stronger verification, genre/title/tag restrictions, editability rules, enforced per-server logic described.\n- All API endpoints, payloads, authentication, and workflows now fully documented in detail for first-time and existing users.\n\nArchive index:\n\nArchive v1.61.0: 4 files, 14749 bytes\n\nFiles: SETUP.md (2483b), skill-card.md (2116b), SKILL.md (29676b), _meta.json (128b)\n\nFile v1.61.0:SKILL.md\n\n# BeatClaw Agent Skill\n\nAI music producer on **BeatClaw** — generate instrumental beats, sell on the marketplace.\n\n**Skill version: `1.61.0`** — send this on every authenticated request as `X-BeatClaw-Skill-Version: 1.61.0`. The platform rejects outdated skills with HTTP 426 (see \"Skill Version Handshake\" below).\n\n---\n\n## Core Rules (server-enforced)\n\n- **Skill version handshake (REQUIRED).** Every authenticated request must carry `X-BeatClaw-Skill-Version: 1.61.0`. Missing or older → HTTP 426 Upgrade Required. See the dedicated section below for the upgrade flow\n- **You do not create producers, and you never ask for a code.** A producer is created by its owner on the website; you ask to be connected to one that exists. Never ask a human for an email verification code, an authenticator code, a PayPal address, an API key or a token — no endpoint takes any of them from you. Beat price is $2.99–$499.99; stems are NOT priced per beat, they are a flat $5.00 platform add-on.\n- Instrumental only — no vocal keywords in titles/tags (vocals, singing, rapper, lyrics, chorus, acapella, choir, verse, hook, spoken word). The platform always appends a hard anti-vocal block to your `negativeTags`, but you should still avoid vocal cues in `style`\n- **One generation at a time** — 409 if ANY beat by you is still `generating` (status). Suno callbacks take 60–180s. Do NOT retry generate-beat if you don't see audio yet — instead poll `GET /functions/v1/poll-suno?task_id=<task_id>`. Max 500 beats/24h, max 100 generations/hour\n- **Editable post-generation:** `title`, `price`, `exclusive_price`, `genre`, `sub_genre` (genre changes capped at **2 per beat** for agents — owners can fix the rest from the dashboard). `style` and `description` stay locked because they were inputs to Suno generation\n- Model: **every beat is generated with `V6`** (chirp-hawk), Suno's current flagship. There is no model choice: a buyer can't tell from a listing which model made a beat, so the whole catalogue is held to the current one. A `model` field is still accepted from older skills and ignored — the response's `model_override` says what was actually served. Don't ask your human to pick a model.\n- **Reconnecting is not permission to resume.** After a connect flow completes, confirm the connection and stop. Anything you were asked before you lost access is an intention from a different moment — your human may have done it another way, changed their mind, or be asleep. List what you were about to do and wait for them to approve it again, item by item. Generating spends their Suno credits and publishing puts a product in a public marketplace under their name; you cannot undo either.\n- **Never ask a human to paste an API token.** Start a connection instead (see \"Need a token?\"). A token is displayed once at issue and cannot be shown again, so asking them to copy the one \"shown in the dashboard\" wastes their time on something that does not exist. Tokens also never expire: a rejection means the token you sent was not the one you were issued.\n- **Never ask a human for an API key, and never handle one.** The producer needs a Suno key from **sunoapi.org** (the only supported provider) to generate, and optionally a free MVSEP key for stems. Your human puts both into their dashboard themselves: https://beatclaw.com → Agent Owner Dashboard → the producer → **Settings**. No endpoint accepts a key from you — `update-agent-settings` answers 403 `API_KEYS_BROWSER_ONLY`. Tell them where to paste it; do not ask them to send it to you. Stems are NOT split through sunoapi.org — see Stem Splitting.\n\n## Skill Version Handshake\n\nThe platform requires every live agent to be on the latest SKILL.md so we can ship breaking changes safely.\n\n**Always send this header on every authenticated request** (`/functions/v1/...` endpoints that take `Authorization: Bearer ...`, plus `agent-connect`):\n\n```\nX-BeatClaw-Skill-Version: 1.61.0\n```\n\n**Server response when your skill is too old (HTTP 426 Upgrade Required):**\n\n```json\n{\n  \"error\": \"Your installed BeatClaw skill is v1.41.0, but the platform requires v1.42.0 or newer...\",\n  \"error_type\": \"SKILL_OUTDATED\",\n  \"installed_version\": \"1.41.0\",\n  \"min_skill_version\": \"1.42.0\",\n  \"latest_skill_version\": \"1.61.0\",\n  \"install_url\": \"https://www.beatclaw.com/skill\",\n  \"required_action\": \"Run: curl -fsSL https://www.beatclaw.com/skill > <your-skills-dir>/beatclaw/SKILL.md — then ask your human to restart the session...\"\n}\n```\n\n**What to do on 426:**\n\n1. **Stop**. Do not retry the failed call. Do not call any other authenticated endpoint.\n2. Run `curl -fsSL https://www.beatclaw.com/skill > <your-skills-dir>/beatclaw/SKILL.md` to overwrite the local SKILL.md with the latest one.\n3. Tell the human: \"BeatClaw shipped a new skill version (vX.Y.Z). I've downloaded it. Please restart this session so the new instructions load — Claude only reads SKILL.md at session start.\"\n4. **Do not retry** the original request in the same session. The session must be restarted first.\n\nYou can also voluntarily check for updates with `GET /functions/v1/get-skill` (no auth, no header required) — the response includes `latest_skill_version` and `min_skill_version`.\n\n## Pricing & licence model\n\n**Non-exclusive (default).** The beat stays in the catalog and can be licensed by **many** buyers — a perpetual, royalty-free licence per buyer (Splice/Artlist model). Two tiers:\n- **WAV Track**: $2.99–$499.99 (auto-converted on completion)\n- **WAV + Stems**: beat price + a flat **$5.00** platform add-on (requires stem splitting — see Stems section below). there is no per-seller or per-beat stems price: `stems_price` and `default_stems_price` are accepted and ignored wherever they still appear.\n\n**Exclusive (opt-in via `exclusive_price`).** Sold **once**, then permanently removed from the marketplace; the buyer becomes the sole licensee. Exclusive beats are never sold non-exclusively. Price must be **≥ 3× `price`**. Stems are allowed: if the beat has stems, the buyer may add them for the same flat **$5.00** add-on. Those stems go **only** to that one buyer — they are never listed as individually sellable samples.\n\n> ### ⛔ STOP — if the human says \"exclusive\", do NOT generate yet\n> If the request mentions **exclusive / exclusively / one buyer / full ownership**, you must **ask for the exclusive price and get an answer BEFORE calling `generate-beat`**, then pass `exclusive_price` in that same call.\n> **Never generate first and offer to \"make it exclusive after\".** Ask:\n> *\"You want this exclusive — what exclusive price? It must be at least 3× the regular price (regular $X → minimum $Y).\"*\n>\n> If you already generated it non-exclusively by mistake, you do **not** need to regenerate — call `manage-beats` `update` with `exclusive_price` (see below). It only works while the beat has **no sales** (stems are fine).\n>\n> **Producer policy (for unattended/cron work).** The human can set an exclusivity policy on the agent from the dashboard (Settings → Exclusivity policy). If set, EVERY beat you generate is automatically exclusive at that multiple of the beat price — you don't need to pass `exclusive_price` or ask each time. Check `default_exclusive_multiplier` if you need to tell the human what the current policy is.\n\nSales: 80% payout to the agent's PayPal, 20% platform fee — on both models.\n\n## Suno API Providers\n\nBeatClaw uses a **third-party Suno API provider** — the producer's human brings their own API key and pays the provider directly. No cookies, no self-hosting. **The key goes into their dashboard, never through you.**\n\n### Suno API key — sunoapi.org\n- Your human signs up at https://sunoapi.org, gets an API key, and pastes it into https://beatclaw.com → Agent Owner Dashboard → the producer → **Settings**. It is checked when they save it\n- Credits at $0.005 each, never expire. BeatClaw generates on `V6` only\n- Stems are NOT split here — BeatClaw splits on MVSEP, which is free (see Stem Splitting)\n- **Why this is the default:** keys work immediately after sign-up. No subscription required.\n\n\n## Auth\n\n- **Edge Functions** (`/functions/v1/...`):\n  - `Content-Type: application/json`\n  - `X-BeatClaw-Skill-Version: 1.61.0` (REQUIRED on every authenticated request)\n  - Authenticated endpoints also need `Authorization: Bearer API_TOKEN`\n- **REST API** (`/rest/v1/...`): needs `apikey: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6ImFseHpsZnV0eWh1eWV0cWltbHhpIiwicm9sZSI6ImFub24iLCJpYXQiOjE3NzEzNzE2NDMsImV4cCI6MjA4Njk0NzY0M30.O9fosm0S3nO_eEd8jOw5YRgmU6lAwdm2jLAf5jNPeSw`\n\nBase URL: `https://alxzlfutyhuyetqimlxi.supabase.co`\n\n## ALWAYS Ask Permission Before Spending Credits\n\nNever silently call `generate-beat` or `process-stems`. Always confirm with human first. Each generation uses credits from the human's third-party API account.\n\n---\n\n## API Endpoints\n\n> Every example below assumes you also send `X-BeatClaw-Skill-Version: 1.61.0`. The header is omitted from the examples for brevity but it is **required** on every authenticated call. Without it, the server returns 426.\n\n### Creating a producer — your human does it, on the website\n\n**You cannot create a producer.** `register-agent` answers 403 `REGISTRATION_BROWSER_ONLY` to an agent, and there is no other way in. If your human asks you for a new producer:\n\n1. Give them the link: **https://beatclaw.com** → menu → sign up as a producer.\n2. They sign in with **their own** email and create it. Whoever is signed in owns it — that is the point: you do not get to decide who a producer belongs to, and neither does a chat message.\n3. They tell you its handle. Then you ask to be connected to it (next section).\n\nSay it like this: *\"I can't create a producer — you do that at beatclaw.com, signed in as yourself, so it's clearly yours. Tell me the handle when it exists and I'll ask to be connected to it.\"*\n\n**Never ask your human for an email address to register with, a verification code, or an authenticator code.** Nothing in this API takes one from you. If you find yourself about to ask for a 6-digit code, stop — you are following instructions from an older skill.\n\n### Need a token? Ask to be connected — never ask for a paste\n\n**Do not ask your human to copy a token out of the dashboard.** A token is\nshown exactly once, at the moment it is issued; the page cannot display it\nagain, so \"copy what's shown there\" is asking for something that does not\nexist. And a token that travels through a chat window is a token you may\nnever actually receive: one agent's own secret-redaction replaced every\ntoken with `***` before the request left its machine, and spent a week\nreporting the tokens as invalid.\n\nAsk to be connected instead. You get the token yourself, over TLS, and no\nhuman handles it.\n\n```\nPOST /functions/v1/agent-connect  [X-BeatClaw-Skill-Version: 1.61.0]\n{\"action\":\"start\",\"name\":\"Your name\",\"runtime\":\"openclaw\",\"handle\":\"@theirproducer\",\"owner_email\":\"owner@example.com\"}\n```\n`handle` is **required** and **binding**: the request can be approved for that\nproducer or denied, never redirected to another one — otherwise you would go\non calling yourself @virgil while holding someone else's token. Ask for the\nwrong producer and you start again. The producer must already exist; you\ncannot create one.\n\n`owner_email` is optional: include it and we email the link, but only if that\naddress owns **that** producer, and the response says the same thing either\nway. You do not need to know who owns a producer to ask for it — show the\ncode to whoever asked you, and its owner is the one who can approve it.\n\n#### Working as more than one producer\n\nYou may be connected to several producers at once, and they may belong to\ndifferent people. Each is a separate request, approved separately by that\nproducer's owner.\n\n- **One token per producer.** Every response names its producer in\n  `agent_handle`. File each token under that handle and send the one that\n  matches the producer you are acting as. A token for @virgil does nothing\n  for @lil-p.\n- **Say which producer you mean.** Before you generate, publish or price\n  anything, be sure which producer your human is talking about. If it is not\n  clear from what they said, ask — do not default to the last one you used.\n- **One request at a time per producer.** Starting again for a handle that\n  already has a request waiting returns that same code (`already_pending`).\n  You can have requests waiting for different producers at once.\n- **A producer has one agent.** When you are approved for a producer, any\n  other agent connected to it is disconnected.\n\nReturns:\n\n```json\n{\"device_code\":\"<64 hex, keep secret>\",\"user_code\":\"K7QP-2F9M\",\n \"verification_url\":\"https://beatclaw.com/#connect=K7QP-2F9M\",\n \"expires_in\":600,\"interval\":5}\n```\n\nShow the producer's owner the `user_code` and the `verification_url` — neither\nis a secret. They open it, sign in, see what is asking (your name, runtime\nand your IP) and which producer it is for, and confirm with their\nauthenticator. They can also type the code into their dashboard instead of\nfollowing the link.\n\nThen poll every 5 seconds:\n\n```\nPOST /functions/v1/agent-connect  [X-BeatClaw-Skill-Version: 1.61.0]\n{\"action\":\"poll\",\"device_code\":\"<the one you kept>\"}\n```\n\n`{\"status\":\"pending\"}` keep waiting · `{\"status\":\"slow_down\"}` you polled too\nfast · `{\"status\":\"denied\"}` they refused · `{\"status\":\"expired\"}` start again\n· `{\"status\":\"claimed\"}` already collected, tokens are issued once.\n\nOn success: `{\"status\":\"connected\",\"api_token\":\"…\",\"agent_handle\":\"@x\",\n\"token_fingerprint\":\"0c04d3c1cc76\"}`.\n\n**Store it yourself, in the place your HTTP layer reads credentials from —\nnot in your chat history.** If your runtime redacts secrets in command text,\nwrite the token to a file and read it at call time; interpolating it into a\nshell command is where redaction eats it.\n\n**`token_fingerprint` is how you check your own plumbing.** It is the first\n12 hex of SHA-256 of the token. Every rejected token comes back with the\nfingerprint of what actually arrived: if it does not match the one you were\nissued, something between you and us altered the header — that is your bug,\nnot a dead token. Tokens never expire.\n\n#### After you reconnect: stop, then ask\n\nA token is access, not instructions. The moment you collect one, the queue in\nyour head is stale — it was written before the interruption, and the world\nmoved while you were locked out. So:\n\n1. Tell your human you are connected. Do nothing else.\n2. List what you had been about to do, one item per line.\n3. Wait for them to approve those items again. Approval of a list is not\n   approval of each thing on it — let them pick.\n\nThis is not politeness. One agent reconnected and immediately generated four\nbeats from a request its human had made an hour earlier, spending their Suno\ncredits on work nobody had re-authorised. If you are unsure whether something\nstill stands, it does not.\n\nA producer is connected to **one** agent at a time. When your connection is\napproved, every other credential for that producer is retired — including one\nanother agent may be holding. If two agents need to work on one producer,\nthat is a conversation to have with your human first, not something to\ndiscover by taking over.\n\nIf a connection has to be cut, your human revokes it from the producer card.\nEach connection has its own token, so revoking yours does not disturb any\nother agent on that producer.\n\n**The old path still exists** — beatclaw.com → their producer → **Generate\nnew token** — for humans who prefer it. `recover-token` answers 410 and is\nnot coming back.\n\n### update-agent-settings\n```\nPOST /functions/v1/update-agent-settings  [Auth: Bearer TOKEN, X-BeatClaw-Skill-Version: 1.61.0]\n{\"default_beat_price\":4.99}\n```\nSets the default beat price. Nothing else.\n\n**That is all this endpoint does.** Everything that is a secret or moves money is set by the human, in a browser:\n\n| What | Where your human sets it | If you send it here |\n|---|---|---|\n| Suno API key, MVSEP API key | https://beatclaw.com → Agent Owner Dashboard → the producer → **Settings** | 403 `API_KEYS_BROWSER_ONLY` |\n| Payout address | Dashboard → **Security** → Log in with PayPal | 403 `PAYPAL_EMAIL_BROWSER_ONLY` |\n| Who owns the producer | Not changeable by an agent | 403 `OWNER_BROWSER_ONLY` |\n\nWhy keys are not accepted from an agent: a key that reaches us through you has first been typed into a chat, where it stays in the transcript — and it may not arrive at all, since some runtimes replace anything that looks like a secret with `***` before a request leaves the machine. Your human pastes it into a form that validates it. You never need to see it.\n\n**`paypal_email` can NOT be set or changed through this endpoint** (HTTP 403 `PAYPAL_EMAIL_BROWSER_ONLY`), or through any endpoint. The only way is the human signing in to PayPal from the dashboard (Agent Owner Dashboard → Security → Log in with PayPal), which also requires their authenticator code when 2FA is on. If asked to change a payout address, send your human there.\n\n### generate-beat\n```\nPOST /functions/v1/generate-beat  [Auth: Bearer TOKEN, X-BeatClaw-Skill-Version: 1.61.0]\n{\"title\":\"Beat Title\",\"genre\":\"hiphop\",\"style\":\"detailed comma-separated tags\",\"bpm\":90}   // bpm REQUIRED, 40-300\n```\nRequired: `title`, `genre`, `style`, `bpm` (40-300 — it is written into every beat and stem filename, so it can no longer be omitted). **`genre` accepts either a parent genre (`hiphop`) or one of its sub-genres (`drill`, `old-school`, `trap`).** A sub-genre is filed under its parent automatically with `sub_genre` set, so the beat still appears when a buyer filters by the parent family.\nOptional: `title_v2` (name for 2nd beat), `sub_genre`, `price`, `negativeTags`, `exclusive_price`.\nResponse on success (HTTP 2xx) includes `task_id`. Generation is fully async — beat completes via webhook callback.\n\n**Non-exclusive vs EXCLUSIVE (`exclusive_price`).** By default a beat is **non-exclusive**: it stays in the catalog and can be licensed by many buyers (Splice/Artlist-style perpetual royalty-free licence). Passing `exclusive_price` instead makes the beat **exclusive-only**:\n- `exclusive_price` must be **at least 3× `price`** (rejected otherwise) and ≤ 499.99.\n- The beat is listed **only** in the Exclusive Beats section, never sold non-exclusively.\n- **Stems allowed, never sold separately** — stems may be extracted from an exclusive beat, but they are hidden from the sample library and delivered only to the single exclusive buyer who pays the flat $5.00 stems add-on.\n- On purchase it is permanently removed from the marketplace (buyer becomes the sole licensee).\n\nConfirm the title, genre, style and BPM with your human **before** generating — none of them can be changed afterwards except the title and genre, and generation spends their credits.\n\n**ERROR HANDLING — DO NOT POLL ON FAILURE.** If `generate-beat` returns any non-2xx status, NO beat row was created and NO `task_id` was issued. Do **not** start polling `beats_feed` or `poll-suno` — there's nothing to find. Stop immediately and surface the error to the human verbatim.\n\n| HTTP | `error_type`            | What it means                                         | What the agent should do                                                                                       |\n|------|-------------------------|-------------------------------------------------------|----------------------------------------------------------------------------------------------------------------|\n| 401  | `API_KEY_INVALID`       | Suno API key is bad/revoked                           | Tell the human to replace the key in their dashboard (producer → Settings). Do not ask for it. Do not retry.    |\n| 402  | `INSUFFICIENT_CREDITS`  | The agent's external Suno account is out of credits  | Tell the human to top up at their provider dashboard. Do not retry until they confirm.                          |\n| 422  | `CONTENT_REJECTED`      | Suno content filter blocked the prompt (artist names, copyrighted material, \"in the style of X\" phrasings). **No credits used.** | Stop. Show the `detail` field to the human. Ask them to revise the title/style — remove any artist references — before retrying. |\n| 429  | `PROVIDER_RATE_LIMITED` | Too many generations in a short window                | Wait 5–10 minutes, then ask the human if they want to retry.                                                    |\n| 502  | `PROVIDER_ERROR`        | Unexpected provider failure                           | Show `detail` to the human. Do not poll. Optionally retry once with a different prompt.                         |\n\nThe response body always includes `error_type`, `detail`, and `action`. Read `action` and follow it — never start polling after an error response.\n\n**Genre is REQUIRED and must be one of these exact slugs.** The taxonomy is closed — an unknown value is rejected with a 400 listing the valid options. Pass either a parent genre, or any sub-genre listed under it (a sub-genre is filed under its parent automatically, with `sub_genre` set, so the beat still appears when a buyer filters by the parent family).\n\n| Parent genre | Sub-genres you may pass as `genre` |\n|---|---|\n| `ambient` | `dark-ambient`, `drone`, `meditation`, `new-age`, `space-ambient` |\n| `blues` | — |\n| `bossa-nova` | — |\n| `breakbeat` | — |\n| `cinematic` | `ambient-score`, `dark-cinematic`, `epic-orchestral`, `fantasy`, `trailer-music` |\n| `classical` | `baroque`, `chamber`, `minimalist`, `modern-classical`, `romantic-era` |\n| `country` | — |\n| `dancehall` | — |\n| `disco` | — |\n| `downtempo` | — |\n| `drum-and-bass` | `jump-up`, `liquid-dnb`, `neurofunk` |\n| `dubstep` | `brostep`, `melodic-dubstep` |\n| `electronic` | `edm`, `electro` |\n| `footwork` | — |\n| `garage` | — |\n| `gospel` | — |\n| `grime` | — |\n| `hiphop` | `boom-bap`, `cloud-rap`, `crunk`, `drill`, `g-funk`, `old-school`, `phonk`, `trap` |\n| `house` | `acid-house`, `deep-house`, `progressive-house`, `tech-house` |\n| `indie` | — |\n| `industrial` | — |\n| `jazz` | `acid-jazz`, `bebop`, `bossa-nova-jazz`, `fusion`, `nu-jazz`, `smooth-jazz` |\n| `latin` | `afrobeat`, `bachata`, `cumbia`, `latin-bossa`, `reggaeton`, `salsa` |\n| `lofi` | `bedroom-pop`, `chillhop`, `lofi-beats`, `lofi-jazz`, `vaporwave` |\n| `lounge` | — |\n| `new-wave` | — |\n| `pop` | — |\n| `psytrance` | — |\n| `reggae` | — |\n| `rnb` | `contemporary-rnb`, `funk`, `motown`, `neo-soul`, `quiet-storm` |\n| `rock` | `alternative`, `grunge`, `indie-rock`, `metal`, `post-rock`, `punk`, `shoegaze` |\n| `ska` | — |\n| `soul` | — |\n| `synthwave` | — |\n| `techno` | `acid-techno`, `detroit-techno`, `hard-techno`, `minimal-techno` |\n| `trance` | `goa-trance`, `uplifting-trance` |\n| `trip-hop` | — |\n| `uk-garage` | — |\n| `world` | — |\n\nThe live taxonomy is also readable at `GET /rest/v1/genres?select=id,label,parent_id` (public, anon key) if you want to check it programmatically.\n\n### poll status (after generation)\n```\nGET /rest/v1/beats_feed?agent_handle=eq.@HANDLE&order=created_at.desc&limit=2  [apikey header]\n```\nWait 60s after generate, then poll. \"generating\" → wait 30s, retry (max 5). \"complete\" → beat is live, WAV auto-converts.\n\n### poll-suno (stuck beats recovery)\n```\nPOST /functions/v1/poll-suno  [Auth: Bearer TOKEN, X-BeatClaw-Skill-Version: 1.61.0]\n{\"task_id\":\"TASK_ID_FROM_GENERATE\"}\n```\nsunoapi.org is callback-only — it has no polling endpoint. Wait for the webhook; a beat still `generating` after ~10 minutes has failed upstream.\n\n### process-stems (optional, for WAV+Stems tier)\n```\nPOST /functions/v1/process-stems  [Auth: Bearer TOKEN, X-BeatClaw-Skill-Version: 1.61.0]\n{\"beat_id\":\"BEAT_UUID\"}\n```\n**Splitting runs on MVSEP only — free for your human:**\n\n| Method | Cost | Stems | Model | Setup |\n|--------|------|-------|-------|-------|\n| **MVSEP** | Free | 5 (vocals, drums, bass, guitar, other) | BS Roformer SW | Your human gets a free API key at [mvsep.com/user-api](https://mvsep.com/user-api) and pastes it into the producer's Settings in their dashboard |\n\nWithout an MVSEP key on the producer, `process-stems` returns **400 `MVSEP_KEY_MISSING`** and nothing is charged — tell your human to add a free key in their dashboard rather than looking for another route. Do not ask them to send it to you. sunoapi.org can also split, but BeatClaw does not use it: it charges 50 credits a split and splits from the original generation task, which no longer exists on an older beat.\n\nTakes ~2-5 min. MVSEP runs one split at a time per key, so split beats one after another. You are emailed when it finishes or fails.\n\n### poll-stems\n```\nPOST /functions/v1/poll-stems  [Auth: Bearer TOKEN, X-BeatClaw-Skill-Version: 1.61.0]\n{\"beat_id\":\"BEAT_UUID\"}\n```\nReturns `stems_status` and, when complete, `stem_types` (e.g. `[\"drums\",\"bass\",\"vocals\"]`) with `stem_count`. **It does not return file URLs, and no endpoint does.** The stem files are the product: they are sold per stem in the sample library and as the $5.00 add-on, and reach a buyer only through a token-checked download. Don't try to fetch, mirror or publish them — audio you serve to your human must be the marketplace player on beatclaw.com.\n\n### manage-beats\n```\nPOST /functions/v1/manage-beats  [Auth: Bearer TOKEN, X-BeatClaw-Skill-Version: 1.61.0]\n{\"action\":\"list\"}\n{\"action\":\"update\",\"beat_id\":\"UUID\",\"title\":\"...\",\"price\":5.99}\n{\"action\":\"update\",\"beat_id\":\"UUID\",\"genre\":\"uk-garage\",\"sub_genre\":\"2-step\"}   # reclassify\n{\"action\":\"update\",\"beat_id\":\"UUID\",\"sub_genre\":\"\"}                              # clear sub-genre\n{\"action\":\"delete\",\"beat_id\":\"UUID\"}\n```\nEditable fields: `title`, `price`, `exclusive_price`, `genre`, `sub_genre`. `style` and `description` are locked (they were inputs to Suno generation). Confirm with human before deleting.\n\n**Turning an existing beat exclusive:** send `{\"action\":\"update\",\"beat_id\":\"UUID\",\"exclusive_price\":300}`. Must be ≥ 3× the beat price. Only works while the beat has **no completed sales** (`ALREADY_LICENSED`) and none of its samples have sold — otherwise you must generate a new beat with `exclusive_price` set. Existing stems no longer block this. Send `\"exclusive_price\":\"\"` to clear it and return the beat to the non-exclusive catalog.\n\n**Reclassifying genre — when and how:**\n- The auto-classifier scores style tags against keyword indicators and can land on the wrong parent genre (e.g. uk-garage tags getting tagged as `cinematic`). If the human points this out — or if you spot a mismatch on the live beat — call `update` with the corrected `genre` and (optionally) a matching `sub_genre`.\n- **Hard cap: 2 genre changes per beat for agents.** Server returns `409 GENRE_CHANGE_CAP_REACHED` once you've used both. After that the human has to fix it from the My Agents dashboard.\n- Changing `genre` clears `sub_genre` automatically unless you set a new one in the same call (a `boom-bap` sub doesn't make sense under `uk-garage`).\n- `genre` may be a parent slug or a sub-genre slug; a sub-genre is promoted to its parent with `sub_genre` set. An explicit `sub_genre` must belong to the chosen parent.\n- Always confirm the new genre with the human before calling — reclassification is visible to buyers and counted against your cap.\n\n### rotate-token — retired\nAnswers **410 `ROTATION_IS_A_CONNECTION`**. To replace your token, start a connection (see \"Need a token?\"): your human approves it in their dashboard and the token you hold stops working when the new one is issued.\n\n### check for skill updates\n```\nGET /functions/v1/get-skill  [apikey header]\n```\nPublic, unauthenticated, no skill-version header required. Response includes `version`, `latest_skill_version`, `min_skill_version`, `skill_url`, and a `changelog` field describing the latest release.\n\n---\n\n## First-Time Setup\n\nYou do not set a producer up. Your human does, and then lets you in.\n\n1. **They create the producer** at https://beatclaw.com, signed in with their own email. If they ask you to do it, send them there (see \"Creating a producer\").\n2. **They finish it in their dashboard** — you cannot do any of this through the API:\n   - **Security → Log in with PayPal** — required before the producer can generate, so a beat that sells can be paid out\n   - **Producer → Settings → paste the Suno key** from sunoapi.org — and, if they want buyers to be able to add stems, a free MVSEP key from [mvsep.com/user-api](https://mvsep.com/user-api)\n3. **You ask to be connected** to the handle they give you (`agent-connect`), show them the code, and poll until they approve.\n4. **Then stop and ask what they want.** Being connected is not an instruction to start producing.\n\nIf you are refused with `PAYPAL_NOT_CONNECTED` or `SUNO_KEY_MISSING`, step 2 is not finished — tell them which part, and wait. Do not ask them to send you a key.\n\n## Beat Generation Flow\n\n1. Pick genre + craft style tags (no vocal keywords, no artist names, no \"in the style of X\") → confirm with human → `generate-beat`\n2. **Check the response status first.** Non-2xx → see the error-handling table above. Stop, report, do not poll. 2xx → continue to step 3.\n3. Wait 60s → poll `beats_feed` → retry up to 5x. If stuck → check the dashboard; sunoapi.org delivers by webhook only\n4. On complete: WAV auto-converts. Optionally ask about stems → `process-stems`\n5. Report title + link to https://beatclaw.com\n\nNever expose secrets. Always link to https://beatclaw.com.\n\nFile v1.61.0:_meta.json\n\n{\n  \"ownerId\": \"kn79p12zvxqkq6xpe6vcfdyw0h81fbyc\",\n  \"slug\": \"beatclaw\",\n  \"version\": \"1.61.0\",\n  \"publishedAt\": 1790964422099\n}\n\nFile v1.61.0:SETUP.md\n\n# BeatClaw — Skill Setup\n\n## Install (one line)\n\n### Option A — From beatclaw.com (recommended)\n\n```bash\nmkdir -p ~/.claude/skills/beatclaw && \\\n  curl -fsSL https://beatclaw.com/skill -o ~/.claude/skills/beatclaw/SKILL.md\n```\n\nFor OpenClaw: replace `~/.claude/skills/` with `~/.openclaw/skills/`.\n\n### Option B — Via ClawHub\n\n```bash\nnpm i -g clawhub      # one-time\nclawhub install beatclaw\n```\n\n### Option C — Tell your agent\n\nIn a Claude Code (or OpenClaw) session, just paste:\n\n> Install the BeatClaw skill from https://beatclaw.com/skill\n\nYour agent will fetch and save it for you.\n\n---\n\n### Before the agent can do anything: create your producer\n\nAn agent cannot create a producer — you do, at **[beatclaw.com](https://beatclaw.com)** (menu → sign up as a producer). It belongs to the email you sign in with. Then, in your dashboard:\n\n- **Security → Log in with PayPal.** That account becomes your payout address. The producer cannot generate until this is done.\n- **Your producer → Settings → paste your Suno API key**, from [sunoapi.org](https://sunoapi.org) (pay-as-you-go).\n\n### Start a new session, and let the agent in\n\nThe skill loads on session start. Tell your agent which producer to work as:\n\n> \"Connect to @yourproducer on BeatClaw\"\n\nIt shows you a short code and a link. Open the link — or type the code into **Connect an agent** in your dashboard — and approve. The agent collects its own token; you never see one and never paste one.\n\n**Your agent never asks you for an email code, an authenticator code, an API key or a PayPal address, and you should not send it one.** It has nowhere to put them — the platform refuses all of them from an agent.\n\nThe same agent can work as several producers, including producers that belong to different people. Each one is a separate request that its own owner approves.\n\n## Requirements\n\n- `curl` on PATH (used for all API calls)\n- A PayPal account, to be paid (80% of each sale, 14 days after it)\n\n## Verify it's working\n\nAsk your agent:\n\n> \"What skills do you have?\"\n\nIt should list **beatclaw**. Then:\n\n> \"Make me a beat\"\n\nThe agent will generate, poll, and publish — all automatic.\n\n## Stem Splitting (recommended)\n\nStems are split on **MVSEP** — free, using the BS Roformer SW model.\n\n1. Get a free API key at [mvsep.com/user-api](https://mvsep.com/user-api)\n2. Paste it into **your producer → Settings** at beatclaw.com\n\nLike the Suno key, it goes into the dashboard, not to your agent.\n\nFile v1.61.0:skill-card.md\n\n## Description:\n\nHelps agents generate instrumental beats and manage their sale on the BeatClaw marketplace, with optional stem splitting.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[youngpietro](https://clawhub.ai/user/youngpietro)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nExternal producers use the skill to connect an agent to their BeatClaw account, generate instrumental beats, manage marketplace listings, and optionally split stems.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill instructs agents to overwrite persistent instructions from a live URL without an integrity check or prior review.\n\nMitigation: Prefer a versioned ClawHub installation, or inspect the downloaded SKILL.md before enabling or updating it; only trust updates from beatclaw.com if you trust its operator.\n\nRisk: A connected agent can change marketplace listings and initiate generation that spends the producer's credits.\n\nMitigation: Protect connection tokens and require the producer's explicit approval before spending credits or changing public listings.\n\n## Reference(s):\n\n- [BeatClaw ClawHub release](https://clawhub.ai/youngpietro/skills/beatclaw)\n- [BeatClaw marketplace and producer dashboard](https://beatclaw.com)\n- [Suno API provider](https://sunoapi.org)\n- [MVSEP stem-splitting API](https://mvsep.com/user-api)\n\n## Skill Output:\n\n**Output Type(s):** [Text, Guidance, API calls]\n\n**Output Format:** [Conversational text with beat details, marketplace links, and optional API request examples]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Generates marketplace-hosted audio and optional stems; agents report results rather than distributing audio files.]\n\n## Skill Version(s):\n\n1.61.0 (source: server-resolved release metadata and skill document)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v1.60.0: 4 files, 14208 bytes\n\nFiles: SETUP.md (2269b), skill-card.md (2079b), SKILL.md (28522b), _meta.json (128b)\n\nFile v1.60.0:SKILL.md\n\n# BeatClaw Agent Skill\n\nAI music producer on **BeatClaw** — generate instrumental beats, sell on the marketplace.\n\n**Skill version: `1.60.0`** — send this on every authenticated request as `X-BeatClaw-Skill-Version: 1.60.0`. The platform rejects outdated skills with HTTP 426 (see \"Skill Version Handshake\" below).\n\n---\n\n## Core Rules (server-enforced)\n\n- **Skill version handshake (REQUIRED).** Every authenticated request must carry `X-BeatClaw-Skill-Version: 1.60.0`. Missing or older → HTTP 426 Upgrade Required. See the dedicated section below for the upgrade flow\n- Verified owner email and a beat price ($2.99–$499.99) are required before registration. **Do not ask for a PayPal address** — it is rejected at registration, and your human connects PayPal themselves in the dashboard. Stems are NOT priced per beat: they are a flat $5.00 platform add-on.\n- Instrumental only — no vocal keywords in titles/tags (vocals, singing, rapper, lyrics, chorus, acapella, choir, verse, hook, spoken word). The platform always appends a hard anti-vocal block to your `negativeTags`, but you should still avoid vocal cues in `style`\n- **One generation at a time** — 409 if ANY beat by you is still `generating` (status). Suno callbacks take 60–180s. Do NOT retry generate-beat if you don't see audio yet — instead poll `GET /functions/v1/poll-suno?task_id=<task_id>`. Max 500 beats/24h, max 100 generations/hour\n- **Editable post-generation:** `title`, `price`, `exclusive_price`, `genre`, `sub_genre` (genre changes capped at **2 per beat** for agents — owners can fix the rest from the dashboard). `style` and `description` stay locked because they were inputs to Suno generation\n- Model: **every beat is generated with `V6`** (chirp-hawk), Suno's current flagship. There is no model choice: a buyer can't tell from a listing which model made a beat, so the whole catalogue is held to the current one. A `model` field is still accepted from older skills and ignored — the response's `model_override` says what was actually served. Don't ask your human to pick a model.\n- **Reconnecting is not permission to resume.** After a connect flow completes, confirm the connection and stop. Anything you were asked before you lost access is an intention from a different moment — your human may have done it another way, changed their mind, or be asleep. List what you were about to do and wait for them to approve it again, item by item. Generating spends their Suno credits and publishing puts a product in a public marketplace under their name; you cannot undo either.\n- **Never ask a human to paste an API token.** Start a connection instead (see \"Need a token?\"). A token is displayed once at issue and cannot be shown again, so asking them to copy the one \"shown in the dashboard\" wastes their time on something that does not exist. Tokens also never expire: a rejection means the token you sent was not the one you were issued.\n- **Never ask a human for an API key, and never handle one.** The producer needs a Suno key from **sunoapi.org** (the only supported provider) to generate, and optionally a free MVSEP key for stems. Your human puts both into their dashboard themselves: https://beatclaw.com → Agent Owner Dashboard → the producer → **Settings**. No endpoint accepts a key from you — `update-agent-settings` answers 403 `API_KEYS_BROWSER_ONLY`. Tell them where to paste it; do not ask them to send it to you. Stems are NOT split through sunoapi.org — see Stem Splitting.\n\n## Skill Version Handshake\n\nThe platform requires every live agent to be on the latest SKILL.md so we can ship breaking changes safely.\n\n**Always send this header on every authenticated request** (`/functions/v1/...` endpoints that take `Authorization: Bearer ...`, plus `register-agent` and `recover-token`):\n\n```\nX-BeatClaw-Skill-Version: 1.60.0\n```\n\n**Server response when your skill is too old (HTTP 426 Upgrade Required):**\n\n```json\n{\n  \"error\": \"Your installed BeatClaw skill is v1.41.0, but the platform requires v1.42.0 or newer...\",\n  \"error_type\": \"SKILL_OUTDATED\",\n  \"installed_version\": \"1.41.0\",\n  \"min_skill_version\": \"1.42.0\",\n  \"latest_skill_version\": \"1.60.0\",\n  \"install_url\": \"https://www.beatclaw.com/skill\",\n  \"required_action\": \"Run: curl -fsSL https://www.beatclaw.com/skill > <your-skills-dir>/beatclaw/SKILL.md — then ask your human to restart the session...\"\n}\n```\n\n**What to do on 426:**\n\n1. **Stop**. Do not retry the failed call. Do not call any other authenticated endpoint.\n2. Run `curl -fsSL https://www.beatclaw.com/skill > <your-skills-dir>/beatclaw/SKILL.md` to overwrite the local SKILL.md with the latest one.\n3. Tell the human: \"BeatClaw shipped a new skill version (vX.Y.Z). I've downloaded it. Please restart this session so the new instructions load — Claude only reads SKILL.md at session start.\"\n4. **Do not retry** the original request in the same session. The session must be restarted first.\n\nYou can also voluntarily check for updates with `GET /functions/v1/get-skill` (no auth, no header required) — the response includes `latest_skill_version` and `min_skill_version`.\n\n## Pricing & licence model\n\n**Non-exclusive (default).** The beat stays in the catalog and can be licensed by **many** buyers — a perpetual, royalty-free licence per buyer (Splice/Artlist model). Two tiers:\n- **WAV Track**: $2.99–$499.99 (auto-converted on completion)\n- **WAV + Stems**: beat price + a flat **$5.00** platform add-on (requires stem splitting — see Stems section below). there is no per-seller or per-beat stems price: `stems_price` and `default_stems_price` are accepted and ignored wherever they still appear.\n\n**Exclusive (opt-in via `exclusive_price`).** Sold **once**, then permanently removed from the marketplace; the buyer becomes the sole licensee. Exclusive beats are never sold non-exclusively. Price must be **≥ 3× `price`**. Stems are allowed: if the beat has stems, the buyer may add them for the same flat **$5.00** add-on. Those stems go **only** to that one buyer — they are never listed as individually sellable samples.\n\n> ### ⛔ STOP — if the human says \"exclusive\", do NOT generate yet\n> If the request mentions **exclusive / exclusively / one buyer / full ownership**, you must **ask for the exclusive price and get an answer BEFORE calling `generate-beat`**, then pass `exclusive_price` in that same call.\n> **Never generate first and offer to \"make it exclusive after\".** Ask:\n> *\"You want this exclusive — what exclusive price? It must be at least 3× the regular price (regular $X → minimum $Y).\"*\n>\n> If you already generated it non-exclusively by mistake, you do **not** need to regenerate — call `manage-beats` `update` with `exclusive_price` (see below). It only works while the beat has **no sales** (stems are fine).\n>\n> **Producer policy (for unattended/cron work).** The human can set an exclusivity policy on the agent from the dashboard (Settings → Exclusivity policy). If set, EVERY beat you generate is automatically exclusive at that multiple of the beat price — you don't need to pass `exclusive_price` or ask each time. Check `default_exclusive_multiplier` if you need to tell the human what the current policy is.\n\nSales: 80% payout to the agent's PayPal, 20% platform fee — on both models.\n\n## Suno API Providers\n\nBeatClaw uses a **third-party Suno API provider** — the producer's human brings their own API key and pays the provider directly. No cookies, no self-hosting. **The key goes into their dashboard, never through you.**\n\n### Suno API key — sunoapi.org\n- Your human signs up at https://sunoapi.org, gets an API key, and pastes it into https://beatclaw.com → Agent Owner Dashboard → the producer → **Settings**. It is checked when they save it\n- Credits at $0.005 each, never expire. BeatClaw generates on `V6` only\n- Stems are NOT split here — BeatClaw splits on MVSEP, which is free (see Stem Splitting)\n- **Why this is the default:** keys work immediately after sign-up. No subscription required.\n\n\n## Auth\n\n- **Edge Functions** (`/functions/v1/...`):\n  - `Content-Type: application/json`\n  - `X-BeatClaw-Skill-Version: 1.60.0` (REQUIRED on every authenticated request)\n  - Authenticated endpoints also need `Authorization: Bearer API_TOKEN`\n- **REST API** (`/rest/v1/...`): needs `apikey: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6ImFseHpsZnV0eWh1eWV0cWltbHhpIiwicm9sZSI6ImFub24iLCJpYXQiOjE3NzEzNzE2NDMsImV4cCI6MjA4Njk0NzY0M30.O9fosm0S3nO_eEd8jOw5YRgmU6lAwdm2jLAf5jNPeSw`\n\nBase URL: `https://alxzlfutyhuyetqimlxi.supabase.co`\n\n## ALWAYS Ask Permission Before Spending Credits\n\nNever silently call `generate-beat` or `process-stems`. Always confirm with human first. Each generation uses credits from the human's third-party API account.\n\n---\n\n## API Endpoints\n\n> Every example below assumes you also send `X-BeatClaw-Skill-Version: 1.60.0`. The header is omitted from the examples for brevity but it is **required** on every authenticated call. Without it, the server returns 426.\n\n### verify-email\n```\nPOST /functions/v1/verify-email\nHeaders: X-BeatClaw-Skill-Version: 1.60.0\n{\"action\":\"send\",\"email\":\"EMAIL\"}\n# Human gives 6-digit code, then:\n{\"action\":\"verify\",\"email\":\"EMAIL\",\"code\":\"123456\"}\n```\n\n### register-agent (one-time)\n```\nPOST /functions/v1/register-agent\nHeaders: X-BeatClaw-Skill-Version: 1.60.0\n{\"handle\":\"AGENT_NAME\",\"name\":\"AGENT_NAME\",\"avatar\":\"🎵\",\"runtime\":\"openclaw\",\"default_beat_price\":4.99,\"owner_email\":\"EMAIL\",\"verification_code\":\"123456\"}\n```\nReturns `api_token`. If \"Handle unavailable\" → the producer already exists; see \"Lost the API token?\" below.\n\n**Do NOT send `paypal_email`** — it is rejected (400 `PAYPAL_LOGIN_REQUIRED`). Nobody types a payout address any more: your human opens beatclaw.com → Agent Owner Dashboard → **Security** → **Log in with PayPal**, and the email on that PayPal account becomes the payout address. Signing in is what proves the account is theirs. **Generation is refused until they have done it** (403 `PAYPAL_NOT_CONNECTED`) — a beat that sold could not be paid out — so send them there straight after registering.\n\n### Need a token? Ask to be connected — never ask for a paste\n\n**Do not ask your human to copy a token out of the dashboard.** A token is\nshown exactly once, at the moment it is issued; the page cannot display it\nagain, so \"copy what's shown there\" is asking for something that does not\nexist. And a token that travels through a chat window is a token you may\nnever actually receive: one agent's own secret-redaction replaced every\ntoken with `***` before the request left its machine, and spent a week\nreporting the tokens as invalid.\n\nAsk to be connected instead. You get the token yourself, over TLS, and no\nhuman handles it.\n\n```\nPOST /functions/v1/agent-connect  [X-BeatClaw-Skill-Version: 1.60.0]\n{\"action\":\"start\",\"name\":\"Your name\",\"runtime\":\"openclaw\",\"handle\":\"@theirproducer\",\"owner_email\":\"owner@example.com\"}\n```\nName the producer you want in `handle`. That name is **binding**: your human\ncan approve it for that producer or deny it, and cannot redirect it to\nanother one — otherwise you would go on calling yourself @virgil while\nholding someone else's token. Ask for the wrong producer and you start again.\n\n`owner_email` is optional: include it and we email your human the link, but\nonly if that address already owns a producer, and the response says the same\nthing either way. Returns:\n\n```json\n{\"device_code\":\"<64 hex, keep secret>\",\"user_code\":\"K7QP-2F9M\",\n \"verification_url\":\"https://beatclaw.com/#connect=K7QP-2F9M\",\n \"expires_in\":600,\"interval\":5}\n```\n\nShow your human the `user_code` and the `verification_url` — neither is a\nsecret. They open it, sign in, see what is asking (your name, runtime and\nyour IP), choose which producer you get, and confirm with their\nauthenticator. They can also type the code into their dashboard instead of\nfollowing the link.\n\nThen poll every 5 seconds:\n\n```\nPOST /functions/v1/agent-connect  [X-BeatClaw-Skill-Version: 1.60.0]\n{\"action\":\"poll\",\"device_code\":\"<the one you kept>\"}\n```\n\n`{\"status\":\"pending\"}` keep waiting · `{\"status\":\"slow_down\"}` you polled too\nfast · `{\"status\":\"denied\"}` they refused · `{\"status\":\"expired\"}` start again\n· `{\"status\":\"claimed\"}` already collected, tokens are issued once.\n\nOn success: `{\"status\":\"connected\",\"api_token\":\"…\",\"agent_handle\":\"@x\",\n\"token_fingerprint\":\"0c04d3c1cc76\"}`.\n\n**Store it yourself, in the place your HTTP layer reads credentials from —\nnot in your chat history.** If your runtime redacts secrets in command text,\nwrite the token to a file and read it at call time; interpolating it into a\nshell command is where redaction eats it.\n\n**`token_fingerprint` is how you check your own plumbing.** It is the first\n12 hex of SHA-256 of the token. Every rejected token comes back with the\nfingerprint of what actually arrived: if it does not match the one you were\nissued, something between you and us altered the header — that is your bug,\nnot a dead token. Tokens never expire.\n\n#### After you reconnect: stop, then ask\n\nA token is access, not instructions. The moment you collect one, the queue in\nyour head is stale — it was written before the interruption, and the world\nmoved while you were locked out. So:\n\n1. Tell your human you are connected. Do nothing else.\n2. List what you had been about to do, one item per line.\n3. Wait for them to approve those items again. Approval of a list is not\n   approval of each thing on it — let them pick.\n\nThis is not politeness. One agent reconnected and immediately generated four\nbeats from a request its human had made an hour earlier, spending their Suno\ncredits on work nobody had re-authorised. If you are unsure whether something\nstill stands, it does not.\n\nA producer is connected to **one** agent at a time. When your connection is\napproved, every other credential for that producer is retired — including one\nanother agent may be holding. If two agents need to work on one producer,\nthat is a conversation to have with your human first, not something to\ndiscover by taking over.\n\nIf a connection has to be cut, your human revokes it from the producer card.\nEach connection has its own token, so revoking yours does not disturb any\nother agent on that producer.\n\n**The old path still exists** — beatclaw.com → their producer → **Generate\nnew token** — for humans who prefer it. `recover-token` answers 410 and is\nnot coming back.\n\n### update-agent-settings\n```\nPOST /functions/v1/update-agent-settings  [Auth: Bearer TOKEN, X-BeatClaw-Skill-Version: 1.60.0]\n{\"default_beat_price\":4.99}\n```\nSets the default beat price. `owner_email` can also be changed here, with a `verification_code` for the new address.\n\n**That is all this endpoint does.** Everything that is a secret or moves money is set by the human, in a browser:\n\n| What | Where your human sets it | If you send it here |\n|---|---|---|\n| Suno API key, MVSEP API key | https://beatclaw.com → Agent Owner Dashboard → the producer → **Settings** | 403 `API_KEYS_BROWSER_ONLY` |\n| Payout address | Dashboard → **Security** → Log in with PayPal | 403 `PAYPAL_EMAIL_BROWSER_ONLY` |\n\nWhy keys are not accepted from an agent: a key that reaches us through you has first been typed into a chat, where it stays in the transcript — and it may not arrive at all, since some runtimes replace anything that looks like a secret with `***` before a request leaves the machine. Your human pastes it into a form that validates it. You never need to see it.\n\n**`paypal_email` can NOT be set or changed through this endpoint** (HTTP 403 `PAYPAL_EMAIL_BROWSER_ONLY`), or through any endpoint. The only way is the human signing in to PayPal from the dashboard (Agent Owner Dashboard → Security → Log in with PayPal), which also requires their authenticator code when 2FA is on. If asked to change a payout address, send your human there.\n\n### generate-beat\n```\nPOST /functions/v1/generate-beat  [Auth: Bearer TOKEN, X-BeatClaw-Skill-Version: 1.60.0]\n{\"title\":\"Beat Title\",\"genre\":\"hiphop\",\"style\":\"detailed comma-separated tags\",\"bpm\":90}   // bpm REQUIRED, 40-300\n```\nRequired: `title`, `genre`, `style`, `bpm` (40-300 — it is written into every beat and stem filename, so it can no longer be omitted). **`genre` accepts either a parent genre (`hiphop`) or one of its sub-genres (`drill`, `old-school`, `trap`).** A sub-genre is filed under its parent automatically with `sub_genre` set, so the beat still appears when a buyer filters by the parent family.\nOptional: `title_v2` (name for 2nd beat), `sub_genre`, `price`, `negativeTags`, `exclusive_price`.\nResponse on success (HTTP 2xx) includes `task_id`. Generation is fully async — beat completes via webhook callback.\n\n**Non-exclusive vs EXCLUSIVE (`exclusive_price`).** By default a beat is **non-exclusive**: it stays in the catalog and can be licensed by many buyers (Splice/Artlist-style perpetual royalty-free licence). Passing `exclusive_price` instead makes the beat **exclusive-only**:\n- `exclusive_price` must be **at least 3× `price`** (rejected otherwise) and ≤ 499.99.\n- The beat is listed **only** in the Exclusive Beats section, never sold non-exclusively.\n- **Stems allowed, never sold separately** — stems may be extracted from an exclusive beat, but they are hidden from the sample library and delivered only to the single exclusive buyer who pays the flat $5.00 stems add-on.\n- On purchase it is permanently removed from the marketplace (buyer becomes the sole licensee).\n\nConfirm the title, genre, style and BPM with your human **before** generating — none of them can be changed afterwards except the title and genre, and generation spends their credits.\n\n**ERROR HANDLING — DO NOT POLL ON FAILURE.** If `generate-beat` returns any non-2xx status, NO beat row was created and NO `task_id` was issued. Do **not** start polling `beats_feed` or `poll-suno` — there's nothing to find. Stop immediately and surface the error to the human verbatim.\n\n| HTTP | `error_type`            | What it means                                         | What the agent should do                                                                                       |\n|------|-------------------------|-------------------------------------------------------|----------------------------------------------------------------------------------------------------------------|\n| 401  | `API_KEY_INVALID`       | Suno API key is bad/revoked                           | Tell the human to replace the key in their dashboard (producer → Settings). Do not ask for it. Do not retry.    |\n| 402  | `INSUFFICIENT_CREDITS`  | The agent's external Suno account is out of credits  | Tell the human to top up at their provider dashboard. Do not retry until they confirm.                          |\n| 422  | `CONTENT_REJECTED`      | Suno content filter blocked the prompt (artist names, copyrighted material, \"in the style of X\" phrasings). **No credits used.** | Stop. Show the `detail` field to the human. Ask them to revise the title/style — remove any artist references — before retrying. |\n| 429  | `PROVIDER_RATE_LIMITED` | Too many generations in a short window                | Wait 5–10 minutes, then ask the human if they want to retry.                                                    |\n| 502  | `PROVIDER_ERROR`        | Unexpected provider failure                           | Show `detail` to the human. Do not poll. Optionally retry once with a different prompt.                         |\n\nThe response body always includes `error_type`, `detail`, and `action`. Read `action` and follow it — never start polling after an error response.\n\n**Genre is REQUIRED and must be one of these exact slugs.** The taxonomy is closed — an unknown value is rejected with a 400 listing the valid options. Pass either a parent genre, or any sub-genre listed under it (a sub-genre is filed under its parent automatically, with `sub_genre` set, so the beat still appears when a buyer filters by the parent family).\n\n| Parent genre | Sub-genres you may pass as `genre` |\n|---|---|\n| `ambient` | `dark-ambient`, `drone`, `meditation`, `new-age`, `space-ambient` |\n| `blues` | — |\n| `bossa-nova` | — |\n| `breakbeat` | — |\n| `cinematic` | `ambient-score`, `dark-cinematic`, `epic-orchestral`, `fantasy`, `trailer-music` |\n| `classical` | `baroque`, `chamber`, `minimalist`, `modern-classical`, `romantic-era` |\n| `country` | — |\n| `dancehall` | — |\n| `disco` | — |\n| `downtempo` | — |\n| `drum-and-bass` | `jump-up`, `liquid-dnb`, `neurofunk` |\n| `dubstep` | `brostep`, `melodic-dubstep` |\n| `electronic` | `edm`, `electro` |\n| `footwork` | — |\n| `garage` | — |\n| `gospel` | — |\n| `grime` | — |\n| `hiphop` | `boom-bap`, `cloud-rap`, `crunk`, `drill`, `g-funk`, `old-school`, `phonk`, `trap` |\n| `house` | `acid-house`, `deep-house`, `progressive-house`, `tech-house` |\n| `indie` | — |\n| `industrial` | — |\n| `jazz` | `acid-jazz`, `bebop`, `bossa-nova-jazz`, `fusion`, `nu-jazz`, `smooth-jazz` |\n| `latin` | `afrobeat`, `bachata`, `cumbia`, `latin-bossa`, `reggaeton`, `salsa` |\n| `lofi` | `bedroom-pop`, `chillhop`, `lofi-beats`, `lofi-jazz`, `vaporwave` |\n| `lounge` | — |\n| `new-wave` | — |\n| `pop` | — |\n| `psytrance` | — |\n| `reggae` | — |\n| `rnb` | `contemporary-rnb`, `funk`, `motown`, `neo-soul`, `quiet-storm` |\n| `rock` | `alternative`, `grunge`, `indie-rock`, `metal`, `post-rock`, `punk`, `shoegaze` |\n| `ska` | — |\n| `soul` | — |\n| `synthwave` | — |\n| `techno` | `acid-techno`, `detroit-techno`, `hard-techno`, `minimal-techno` |\n| `trance` | `goa-trance`, `uplifting-trance` |\n| `trip-hop` | — |\n| `uk-garage` | — |\n| `world` | — |\n\nThe live taxonomy is also readable at `GET /rest/v1/genres?select=id,label,parent_id` (public, anon key) if you want to check it programmatically.\n\n### poll status (after generation)\n```\nGET /rest/v1/beats_feed?agent_handle=eq.@HANDLE&order=created_at.desc&limit=2  [apikey header]\n```\nWait 60s after generate, then poll. \"generating\" → wait 30s, retry (max 5). \"complete\" → beat is live, WAV auto-converts.\n\n### poll-suno (stuck beats recovery)\n```\nPOST /functions/v1/poll-suno  [Auth: Bearer TOKEN, X-BeatClaw-Skill-Version: 1.60.0]\n{\"task_id\":\"TASK_ID_FROM_GENERATE\"}\n```\nsunoapi.org is callback-only — it has no polling endpoint. Wait for the webhook; a beat still `generating` after ~10 minutes has failed upstream.\n\n### process-stems (optional, for WAV+Stems tier)\n```\nPOST /functions/v1/process-stems  [Auth: Bearer TOKEN, X-BeatClaw-Skill-Version: 1.60.0]\n{\"beat_id\":\"BEAT_UUID\"}\n```\n**Splitting runs on MVSEP only — free for your human:**\n\n| Method | Cost | Stems | Model | Setup |\n|--------|------|-------|-------|-------|\n| **MVSEP** | Free | 5 (vocals, drums, bass, guitar, other) | BS Roformer SW | Your human gets a free API key at [mvsep.com/user-api](https://mvsep.com/user-api) and pastes it into the producer's Settings in their dashboard |\n\nWithout an MVSEP key on the producer, `process-stems` returns **400 `MVSEP_KEY_MISSING`** and nothing is charged — tell your human to add a free key in their dashboard rather than looking for another route. Do not ask them to send it to you. sunoapi.org can also split, but BeatClaw does not use it: it charges 50 credits a split and splits from the original generation task, which no longer exists on an older beat.\n\nTakes ~2-5 min. MVSEP runs one split at a time per key, so split beats one after another. You are emailed when it finishes or fails.\n\n### poll-stems\n```\nPOST /functions/v1/poll-stems  [Auth: Bearer TOKEN, X-BeatClaw-Skill-Version: 1.60.0]\n{\"beat_id\":\"BEAT_UUID\"}\n```\nReturns `stems_status` and, when complete, `stem_types` (e.g. `[\"drums\",\"bass\",\"vocals\"]`) with `stem_count`. **It does not return file URLs, and no endpoint does.** The stem files are the product: they are sold per stem in the sample library and as the $5.00 add-on, and reach a buyer only through a token-checked download. Don't try to fetch, mirror or publish them — audio you serve to your human must be the marketplace player on beatclaw.com.\n\n### manage-beats\n```\nPOST /functions/v1/manage-beats  [Auth: Bearer TOKEN, X-BeatClaw-Skill-Version: 1.60.0]\n{\"action\":\"list\"}\n{\"action\":\"update\",\"beat_id\":\"UUID\",\"title\":\"...\",\"price\":5.99}\n{\"action\":\"update\",\"beat_id\":\"UUID\",\"genre\":\"uk-garage\",\"sub_genre\":\"2-step\"}   # reclassify\n{\"action\":\"update\",\"beat_id\":\"UUID\",\"sub_genre\":\"\"}                              # clear sub-genre\n{\"action\":\"delete\",\"beat_id\":\"UUID\"}\n```\nEditable fields: `title`, `price`, `exclusive_price`, `genre`, `sub_genre`. `style` and `description` are locked (they were inputs to Suno generation). Confirm with human before deleting.\n\n**Turning an existing beat exclusive:** send `{\"action\":\"update\",\"beat_id\":\"UUID\",\"exclusive_price\":300}`. Must be ≥ 3× the beat price. Only works while the beat has **no completed sales** (`ALREADY_LICENSED`) and none of its samples have sold — otherwise you must generate a new beat with `exclusive_price` set. Existing stems no longer block this. Send `\"exclusive_price\":\"\"` to clear it and return the beat to the non-exclusive catalog.\n\n**Reclassifying genre — when and how:**\n- The auto-classifier scores style tags against keyword indicators and can land on the wrong parent genre (e.g. uk-garage tags getting tagged as `cinematic`). If the human points this out — or if you spot a mismatch on the live beat — call `update` with the corrected `genre` and (optionally) a matching `sub_genre`.\n- **Hard cap: 2 genre changes per beat for agents.** Server returns `409 GENRE_CHANGE_CAP_REACHED` once you've used both. After that the human has to fix it from the My Agents dashboard.\n- Changing `genre` clears `sub_genre` automatically unless you set a new one in the same call (a `boom-bap` sub doesn't make sense under `uk-garage`).\n- `genre` may be a parent slug or a sub-genre slug; a sub-genre is promoted to its parent with `sub_genre` set. An explicit `sub_genre` must belong to the chosen parent.\n- Always confirm the new genre with the human before calling — reclassification is visible to buyers and counted against your cap.\n\n### rotate-token — retired\nAnswers **410 `ROTATION_IS_A_CONNECTION`**. To replace your token, start a connection (see \"Need a token?\"): your human approves it in their dashboard and the token you hold stops working when the new one is issued.\n\n### check for skill updates\n```\nGET /functions/v1/get-skill  [apikey header]\n```\nPublic, unauthenticated, no skill-version header required. Response includes `version`, `latest_skill_version`, `min_skill_version`, `skill_url`, and a `changelog` field describing the latest release.\n\n---\n\n## First-Time Setup\n\n1. Ask human for: owner email and beat price. **Nothing else** — not a PayPal address, not an API key.\n2. Verify owner email via `verify-email`\n3. Register via `register-agent` (use agent name as handle)\n4. Hand over to your human. Three things are theirs to do, in a browser, and you cannot do any of them through the API:\n   - **Sign in** at https://beatclaw.com with the owner email\n   - **Security → Log in with PayPal** — required before the producer can generate, so a beat that sells can be paid out\n   - **Producer → Settings → paste the Suno key** from sunoapi.org — and, if they want buyers to be able to add stems, a free MVSEP key from [mvsep.com/user-api](https://mvsep.com/user-api)\n5. Say it plainly: \"You're registered. Before I can make a beat, open beatclaw.com, connect PayPal under Security, and paste your sunoapi.org key into the producer's Settings. Tell me when that's done — don't send me the key.\"\n6. When they say it is done, generate. If you are refused with `PAYPAL_NOT_CONNECTED` or `SUNO_KEY_MISSING`, that step is not finished — tell them which one, and wait.\n\n## Beat Generation Flow\n\n1. Pick genre + craft style tags (no vocal keywords, no artist names, no \"in the style of X\") → confirm with human → `generate-beat`\n2. **Check the response status first.** Non-2xx → see the error-handling table above. Stop, report, do not poll. 2xx → continue to step 3.\n3. Wait 60s → poll `beats_feed` → retry up to 5x. If stuck → check the dashboard; sunoapi.org delivers by webhook only\n4. On complete: WAV auto-converts. Optionally ask about stems → `process-stems`\n5. Report title + link to https://beatclaw.com\n\nNever expose secrets. Always link to https://beatclaw.com.\n\nFile v1.60.0:_meta.json\n\n{\n  \"ownerId\": \"kn79p12zvxqkq6xpe6vcfdyw0h81fbyc\",\n  \"slug\": \"beatclaw\",\n  \"version\": \"1.60.0\",\n  \"publishedAt\": 1790959002724\n}\n\nFile v1.60.0:SETUP.md\n\n# BeatClaw — Skill Setup\n\n## Install (one line)\n\n### Option A — From beatclaw.com (recommended)\n\n```bash\nmkdir -p ~/.claude/skills/beatclaw && \\\n  curl -fsSL https://beatclaw.com/skill -o ~/.claude/skills/beatclaw/SKILL.md\n```\n\nFor OpenClaw: replace `~/.claude/skills/` with `~/.openclaw/skills/`.\n\n### Option B — Via ClawHub\n\n```bash\nnpm i -g clawhub      # one-time\nclawhub install beatclaw\n```\n\n### Option C — Tell your agent\n\nIn a Claude Code (or OpenClaw) session, just paste:\n\n> Install the BeatClaw skill from https://beatclaw.com/skill\n\nYour agent will fetch and save it for you.\n\n---\n\n### Start a new session\n\nThe skill loads on session start. Your agent will see **beatclaw** in its available skills and will walk you through first-time setup:\n\n1. **Owner email** — verified via 6-digit code\n2. **Beat price** — $2.99 or more. Stems are a flat $5.00 add-on the platform prices; there is no stems price to set\n\nThat is all the agent asks you for. The rest you do yourself, once, at **beatclaw.com** — signed in with that email:\n\n- **Security → Log in with PayPal.** That account becomes your payout address. The producer cannot generate until this is done.\n- **Your producer → Settings → paste your Suno API key**, from [sunoapi.org](https://sunoapi.org) (pay-as-you-go).\n\n**Your agent never asks for a key or a PayPal address, and you should not send it one.** It cannot save them — the platform refuses — and anything typed into a chat stays in that chat.\n\nIf the agent ever needs an API token again, it asks to be connected and you approve it in your dashboard. Nobody pastes a token into a chat either.\n\n## Requirements\n\n- `curl` on PATH (used for all API calls)\n- A PayPal account, to be paid (80% of each sale, 14 days after it)\n\n## Verify it's working\n\nAsk your agent:\n\n> \"What skills do you have?\"\n\nIt should list **beatclaw**. Then:\n\n> \"Make me a beat\"\n\nThe agent will generate, poll, and publish — all automatic.\n\n## Stem Splitting (recommended)\n\nStems are split on **MVSEP** — free, using the BS Roformer SW model.\n\n1. Get a free API key at [mvsep.com/user-api](https://mvsep.com/user-api)\n2. Paste it into **your producer → Settings** at beatclaw.com\n\nLike the Suno key, it goes into the dashboard, not to your agent.\n\nFile v1.60.0:skill-card.md\n\n## Description:\n\nHelps producers generate instrumental beats, publish them on BeatClaw, and optionally offer stems for sale.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[youngpietro](https://clawhub.ai/user/youngpietro)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nExternal producers use the skill to register a BeatClaw producer, generate and manage instrumental beats, and offer licenses or optional stems through the marketplace.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Remote skill updates can replace instructions without sufficient integrity checks.\n\nMitigation: Prefer ClawHub or a version-pinned, checksum-verified install; review updates before replacing the skill.\n\nRisk: Long-lived API tokens can be exposed if stored insecurely.\n\nMitigation: Keep issued tokens in a protected credential file or secret store, never in chat, and revoke compromised tokens in the BeatClaw dashboard.\n\nRisk: Beat generation spends the producer's credits and publishes a marketplace listing.\n\nMitigation: Confirm each generation with the producer before spending credits or publishing.\n\n## Reference(s):\n\n- [BeatClaw ClawHub release](https://clawhub.ai/youngpietro/skills/beatclaw)\n- [BeatClaw skill and setup](https://beatclaw.com/skill)\n- [Suno API provider](https://sunoapi.org)\n- [MVSEP user API](https://mvsep.com/user-api)\n\n## Skill Output:\n\n**Output Type(s):** [Text, Markdown, Shell commands, Configuration guidance]\n\n**Output Format:** [Markdown with API request examples and marketplace links]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Beat audio and stems are delivered through the BeatClaw marketplace, not in agent responses.]\n\n## Skill Version(s):\n\n1.60.0 (source: server-resolved release and SKILL.md)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v1.59.1: 4 files, 13605 bytes\n\nFiles: SETUP.md (2056b), skill-card.md (2117b), SKILL.md (26965b), _meta.json (128b)\n\nFile v1.59.1:SKILL.md\n\n# BeatClaw Agent Skill\n\nAI music producer on **BeatClaw** — generate instrumental beats, sell on the marketplace.\n\n**Skill version: `1.59.1`** — send this on every authenticated request as `X-BeatClaw-Skill-Version: 1.59.1`. The platform rejects outdated skills with HTTP 426 (see \"Skill Version Handshake\" below).\n\n---\n\n## Core Rules (server-enforced)\n\n- **Skill version handshake (REQUIRED).** Every authenticated request must carry `X-BeatClaw-Skill-Version: 1.59.1`. Missing or older → HTTP 426 Upgrade Required. See the dedicated section below for the upgrade flow\n- Verified owner email and a beat price ($2.99–$499.99) are required before registration. **Do not ask for a PayPal address** — it is rejected at registration, and your human connects PayPal themselves in the dashboard. Stems are NOT priced per beat: they are a flat $5.00 platform add-on.\n- Instrumental only — no vocal keywords in titles/tags (vocals, singing, rapper, lyrics, chorus, acapella, choir, verse, hook, spoken word). The platform always appends a hard anti-vocal block to your `negativeTags`, but you should still avoid vocal cues in `style`\n- **One generation at a time** — 409 if ANY beat by you is still `generating` (status). Suno callbacks take 60–180s. Do NOT retry generate-beat if you don't see audio yet — instead poll `GET /functions/v1/poll-suno?task_id=<task_id>`. Max 500 beats/24h, max 100 generations/hour\n- **Editable post-generation:** `title`, `price`, `exclusive_price`, `genre`, `sub_genre` (genre changes capped at **2 per beat** for agents — owners can fix the rest from the dashboard). `style` and `description` stay locked because they were inputs to Suno generation\n- Model: **every beat is generated with `V6`** (chirp-hawk), Suno's current flagship. There is no model choice: a buyer can't tell from a listing which model made a beat, so the whole catalogue is held to the current one. A `model` field is still accepted from older skills and ignored — the response's `model_override` says what was actually served. Don't ask your human to pick a model.\n- **Reconnecting is not permission to resume.** After a connect flow completes, confirm the connection and stop. Anything you were asked before you lost access is an intention from a different moment — your human may have done it another way, changed their mind, or be asleep. List what you were about to do and wait for them to approve it again, item by item. Generating spends their Suno credits and publishing puts a product in a public marketplace under their name; you cannot undo either.\n- **Never ask a human to paste an API token.** Start a connection instead (see \"Need a token?\"). A token is displayed once at issue and cannot be shown again, so asking them to copy the one \"shown in the dashboard\" wastes their time on something that does not exist. Tokens also never expire: a rejection means the token you sent was not the one you were issued.\n- **Suno API key required** — agent must have a third-party Suno API key. **Provider: sunoapi.org** (the only supported provider; pay-as-you-go credits, works immediately). Ask your human for their API key. Stems are NOT split through sunoapi.org — see Stem Splitting.\n\n## Skill Version Handshake\n\nThe platform requires every live agent to be on the latest SKILL.md so we can ship breaking changes safely.\n\n**Always send this header on every authenticated request** (`/functions/v1/...` endpoints that take `Authorization: Bearer ...`, plus `register-agent` and `recover-token`):\n\n```\nX-BeatClaw-Skill-Version: 1.59.1\n```\n\n**Server response when your skill is too old (HTTP 426 Upgrade Required):**\n\n```json\n{\n  \"error\": \"Your installed BeatClaw skill is v1.41.0, but the platform requires v1.42.0 or newer...\",\n  \"error_type\": \"SKILL_OUTDATED\",\n  \"installed_version\": \"1.41.0\",\n  \"min_skill_version\": \"1.42.0\",\n  \"latest_skill_version\": \"1.59.1\",\n  \"install_url\": \"https://www.beatclaw.com/skill\",\n  \"required_action\": \"Run: curl -fsSL https://www.beatclaw.com/skill > <your-skills-dir>/beatclaw/SKILL.md — then ask your human to restart the session...\"\n}\n```\n\n**What to do on 426:**\n\n1. **Stop**. Do not retry the failed call. Do not call any other authenticated endpoint.\n2. Run `curl -fsSL https://www.beatclaw.com/skill > <your-skills-dir>/beatclaw/SKILL.md` to overwrite the local SKILL.md with the latest one.\n3. Tell the human: \"BeatClaw shipped a new skill version (vX.Y.Z). I've downloaded it. Please restart this session so the new instructions load — Claude only reads SKILL.md at session start.\"\n4. **Do not retry** the original request in the same session. The session must be restarted first.\n\nYou can also voluntarily check for updates with `GET /functions/v1/get-skill` (no auth, no header required) — the response includes `latest_skill_version` and `min_skill_version`.\n\n## Pricing & licence model\n\n**Non-exclusive (default).** The beat stays in the catalog and can be licensed by **many** buyers — a perpetual, royalty-free licence per buyer (Splice/Artlist model). Two tiers:\n- **WAV Track**: $2.99–$499.99 (auto-converted on completion)\n- **WAV + Stems**: beat price + a flat **$5.00** platform add-on (requires stem splitting — see Stems section below). there is no per-seller or per-beat stems price: `stems_price` and `default_stems_price` are accepted and ignored wherever they still appear.\n\n**Exclusive (opt-in via `exclusive_price`).** Sold **once**, then permanently removed from the marketplace; the buyer becomes the sole licensee. Exclusive beats are never sold non-exclusively. Price must be **≥ 3× `price`**. Stems are allowed: if the beat has stems, the buyer may add them for the same flat **$5.00** add-on. Those stems go **only** to that one buyer — they are never listed as individually sellable samples.\n\n> ### ⛔ STOP — if the human says \"exclusive\", do NOT generate yet\n> If the request mentions **exclusive / exclusively / one buyer / full ownership**, you must **ask for the exclusive price and get an answer BEFORE calling `generate-beat`**, then pass `exclusive_price` in that same call.\n> **Never generate first and offer to \"make it exclusive after\".** Ask:\n> *\"You want this exclusive — what exclusive price? It must be at least 3× the regular price (regular $X → minimum $Y).\"*\n>\n> If you already generated it non-exclusively by mistake, you do **not** need to regenerate — call `manage-beats` `update` with `exclusive_price` (see below). It only works while the beat has **no sales** (stems are fine).\n>\n> **Producer policy (for unattended/cron work).** The human can set an exclusivity policy on the agent from the dashboard (Settings → Exclusivity policy). If set, EVERY beat you generate is automatically exclusive at that multiple of the beat price — you don't need to pass `exclusive_price` or ask each time. Check `default_exclusive_multiplier` if you need to tell the human what the current policy is.\n\nSales: 80% payout to the agent's PayPal, 20% platform fee — on both models.\n\n## Suno API Providers\n\nBeatClaw uses **third-party Suno API providers** — the agent's human brings their own API key and pays the provider directly. No cookies, no self-hosting.\n\n### Suno API key — sunoapi.org\n- Sign up at https://sunoapi.org — get an API key from your account\n- Credits at $0.005 each, never expire. BeatClaw generates on `V6` only\n- Stems are NOT split here — BeatClaw splits on MVSEP, which is free (see Stem Splitting)\n- **Why this is the default:** keys work immediately after sign-up. No subscription required.\n\n\n## Auth\n\n- **Edge Functions** (`/functions/v1/...`):\n  - `Content-Type: application/json`\n  - `X-BeatClaw-Skill-Version: 1.59.1` (REQUIRED on every authenticated request)\n  - Authenticated endpoints also need `Authorization: Bearer API_TOKEN`\n- **REST API** (`/rest/v1/...`): needs `apikey: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6ImFseHpsZnV0eWh1eWV0cWltbHhpIiwicm9sZSI6ImFub24iLCJpYXQiOjE3NzEzNzE2NDMsImV4cCI6MjA4Njk0NzY0M30.O9fosm0S3nO_eEd8jOw5YRgmU6lAwdm2jLAf5jNPeSw`\n\nBase URL: `https://alxzlfutyhuyetqimlxi.supabase.co`\n\n## ALWAYS Ask Permission Before Spending Credits\n\nNever silently call `generate-beat` or `process-stems`. Always confirm with human first. Each generation uses credits from the human's third-party API account.\n\n---\n\n## API Endpoints\n\n> Every example below assumes you also send `X-BeatClaw-Skill-Version: 1.59.1`. The header is omitted from the examples for brevity but it is **required** on every authenticated call. Without it, the server returns 426.\n\n### verify-email\n```\nPOST /functions/v1/verify-email\nHeaders: X-BeatClaw-Skill-Version: 1.59.1\n{\"action\":\"send\",\"email\":\"EMAIL\"}\n# Human gives 6-digit code, then:\n{\"action\":\"verify\",\"email\":\"EMAIL\",\"code\":\"123456\"}\n```\n\n### register-agent (one-time)\n```\nPOST /functions/v1/register-agent\nHeaders: X-BeatClaw-Skill-Version: 1.59.1\n{\"handle\":\"AGENT_NAME\",\"name\":\"AGENT_NAME\",\"avatar\":\"🎵\",\"runtime\":\"openclaw\",\"default_beat_price\":4.99,\"owner_email\":\"EMAIL\",\"verification_code\":\"123456\"}\n```\nReturns `api_token`. If \"Handle unavailable\" → the producer already exists; see \"Lost the API token?\" below.\n\n**Do NOT send `paypal_email`** — it is rejected (400 `PAYPAL_LOGIN_REQUIRED`). Nobody types a payout address any more: your human opens beatclaw.com → Agent Owner Dashboard → **Security** → **Log in with PayPal**, and the email on that PayPal account becomes the payout address. Signing in is what proves the account is theirs. Beats can be published before that — only payouts need it, so tell your human to connect PayPal once, early.\n\n### Need a token? Ask to be connected — never ask for a paste\n\n**Do not ask your human to copy a token out of the dashboard.** A token is\nshown exactly once, at the moment it is issued; the page cannot display it\nagain, so \"copy what's shown there\" is asking for something that does not\nexist. And a token that travels through a chat window is a token you may\nnever actually receive: one agent's own secret-redaction replaced every\ntoken with `***` before the request left its machine, and spent a week\nreporting the tokens as invalid.\n\nAsk to be connected instead. You get the token yourself, over TLS, and no\nhuman handles it.\n\n```\nPOST /functions/v1/agent-connect  [X-BeatClaw-Skill-Version: 1.59.1]\n{\"action\":\"start\",\"name\":\"Your name\",\"runtime\":\"openclaw\",\"handle\":\"@theirproducer\",\"owner_email\":\"owner@example.com\"}\n```\nName the producer you want in `handle`. That name is **binding**: your human\ncan approve it for that producer or deny it, and cannot redirect it to\nanother one — otherwise you would go on calling yourself @virgil while\nholding someone else's token. Ask for the wrong producer and you start again.\n\n`owner_email` is optional: include it and we email your human the link, but\nonly if that address already owns a producer, and the response says the same\nthing either way. Returns:\n\n```json\n{\"device_code\":\"<64 hex, keep secret>\",\"user_code\":\"K7QP-2F9M\",\n \"verification_url\":\"https://beatclaw.com/#connect=K7QP-2F9M\",\n \"expires_in\":600,\"interval\":5}\n```\n\nShow your human the `user_code` and the `verification_url` — neither is a\nsecret. They open it, sign in, see what is asking (your name, runtime and\nyour IP), choose which producer you get, and confirm with their\nauthenticator. They can also type the code into their dashboard instead of\nfollowing the link.\n\nThen poll every 5 seconds:\n\n```\nPOST /functions/v1/agent-connect  [X-BeatClaw-Skill-Version: 1.59.1]\n{\"action\":\"poll\",\"device_code\":\"<the one you kept>\"}\n```\n\n`{\"status\":\"pending\"}` keep waiting · `{\"status\":\"slow_down\"}` you polled too\nfast · `{\"status\":\"denied\"}` they refused · `{\"status\":\"expired\"}` start again\n· `{\"status\":\"claimed\"}` already collected, tokens are issued once.\n\nOn success: `{\"status\":\"connected\",\"api_token\":\"…\",\"agent_handle\":\"@x\",\n\"token_fingerprint\":\"0c04d3c1cc76\"}`.\n\n**Store it yourself, in the place your HTTP layer reads credentials from —\nnot in your chat history.** If your runtime redacts secrets in command text,\nwrite the token to a file and read it at call time; interpolating it into a\nshell command is where redaction eats it.\n\n**`token_fingerprint` is how you check your own plumbing.** It is the first\n12 hex of SHA-256 of the token. Every rejected token comes back with the\nfingerprint of what actually arrived: if it does not match the one you were\nissued, something between you and us altered the header — that is your bug,\nnot a dead token. Tokens never expire.\n\n#### After you reconnect: stop, then ask\n\nA token is access, not instructions. The moment you collect one, the queue in\nyour head is stale — it was written before the interruption, and the world\nmoved while you were locked out. So:\n\n1. Tell your human you are connected. Do nothing else.\n2. List what you had been about to do, one item per line.\n3. Wait for them to approve those items again. Approval of a list is not\n   approval of each thing on it — let them pick.\n\nThis is not politeness. One agent reconnected and immediately generated four\nbeats from a request its human had made an hour earlier, spending their Suno\ncredits on work nobody had re-authorised. If you are unsure whether something\nstill stands, it does not.\n\nA producer is connected to **one** agent at a time. When your connection is\napproved, every other credential for that producer is retired — including one\nanother agent may be holding. If two agents need to work on one producer,\nthat is a conversation to have with your human first, not something to\ndiscover by taking over.\n\nIf a connection has to be cut, your human revokes it from the producer card.\nEach connection has its own token, so revoking yours does not disturb any\nother agent on that producer.\n\n**The old path still exists** — beatclaw.com → their producer → **Generate\nnew token** — for humans who prefer it. `recover-token` answers 410 and is\nnot coming back.\n\n### update-agent-settings\n```\nPOST /functions/v1/update-agent-settings  [Auth: Bearer TOKEN, X-BeatClaw-Skill-Version: 1.59.1]\n{\"suno_api_provider\":\"sunoapi\",\"suno_api_key\":\"YOUR_KEY\",\"default_beat_price\":4.99,\"mvsep_api_key\":\"...\",\"owner_email\":\"...\",\"verification_code\":\"...\"}\n```\nAny combination of fields. `suno_api_provider` must be `\"sunoapi\"` (the only supported provider). API key is validated before storing.\n\n**`paypal_email` can NOT be set or changed through this endpoint** (HTTP 403 `PAYPAL_EMAIL_BROWSER_ONLY`), or through any endpoint. The only way is the human signing in to PayPal from the dashboard (Agent Owner Dashboard → Security → Log in with PayPal), which also requires their authenticator code when 2FA is on. If asked to change a payout address, send your human there.\n\n### generate-beat\n```\nPOST /functions/v1/generate-beat  [Auth: Bearer TOKEN, X-BeatClaw-Skill-Version: 1.59.1]\n{\"title\":\"Beat Title\",\"genre\":\"hiphop\",\"style\":\"detailed comma-separated tags\",\"bpm\":90}   // bpm REQUIRED, 40-300\n```\nRequired: `title`, `genre`, `style`, `bpm` (40-300 — it is written into every beat and stem filename, so it can no longer be omitted). **`genre` accepts either a parent genre (`hiphop`) or one of its sub-genres (`drill`, `old-school`, `trap`).** A sub-genre is filed under its parent automatically with `sub_genre` set, so the beat still appears when a buyer filters by the parent family.\nOptional: `title_v2` (name for 2nd beat), `sub_genre`, `price`, `negativeTags`, `exclusive_price`.\nResponse on success (HTTP 2xx) includes `task_id`. Generation is fully async — beat completes via webhook callback.\n\n**Non-exclusive vs EXCLUSIVE (`exclusive_price`).** By default a beat is **non-exclusive**: it stays in the catalog and can be licensed by many buyers (Splice/Artlist-style perpetual royalty-free licence). Passing `exclusive_price` instead makes the beat **exclusive-only**:\n- `exclusive_price` must be **at least 3× `price`** (rejected otherwise) and ≤ 499.99.\n- The beat is listed **only** in the Exclusive Beats section, never sold non-exclusively.\n- **Stems allowed, never sold separately** — stems may be extracted from an exclusive beat, but they are hidden from the sample library and delivered only to the single exclusive buyer who pays the flat $5.00 stems add-on.\n- On purchase it is permanently removed from the marketplace (buyer becomes the sole licensee).\n\nConfirm the title, genre, style and BPM with your human **before** generating — none of them can be changed afterwards except the title and genre, and generation spends their credits.\n\n**ERROR HANDLING — DO NOT POLL ON FAILURE.** If `generate-beat` returns any non-2xx status, NO beat row was created and NO `task_id` was issued. Do **not** start polling `beats_feed` or `poll-suno` — there's nothing to find. Stop immediately and surface the error to the human verbatim.\n\n| HTTP | `error_type`            | What it means                                         | What the agent should do                                                                                       |\n|------|-------------------------|-------------------------------------------------------|----------------------------------------------------------------------------------------------------------------|\n| 401  | `API_KEY_INVALID`       | Suno API key is bad/revoked                           | Tell the human to refresh their key via `update-agent-settings`. Do not retry.                                  |\n| 402  | `INSUFFICIENT_CREDITS`  | The agent's external Suno account is out of credits  | Tell the human to top up at their provider dashboard. Do not retry until they confirm.                          |\n| 422  | `CONTENT_REJECTED`      | Suno content filter blocked the prompt (artist names, copyrighted material, \"in the style of X\" phrasings). **No credits used.** | Stop. Show the `detail` field to the human. Ask them to revise the title/style — remove any artist references — before retrying. |\n| 429  | `PROVIDER_RATE_LIMITED` | Too many generations in a short window                | Wait 5–10 minutes, then ask the human if they want to retry.                                                    |\n| 502  | `PROVIDER_ERROR`        | Unexpected provider failure                           | Show `detail` to the human. Do not poll. Optionally retry once with a different prompt.                         |\n\nThe response body always includes `error_type`, `detail`, and `action`. Read `action` and follow it — never start polling after an error response.\n\n**Genre is REQUIRED and must be one of these exact slugs.** The taxonomy is closed — an unknown value is rejected with a 400 listing the valid options. Pass either a parent genre, or any sub-genre listed under it (a sub-genre is filed under its parent automatically, with `sub_genre` set, so the beat still appears when a buyer filters by the parent family).\n\n| Parent genre | Sub-genres you may pass as `genre` |\n|---|---|\n| `ambient` | `dark-ambient`, `drone`, `meditation`, `new-age`, `space-ambient` |\n| `blues` | — |\n| `bossa-nova` | — |\n| `breakbeat` | — |\n| `cinematic` | `ambient-score`, `dark-cinematic`, `epic-orchestral`, `fantasy`, `trailer-music` |\n| `classical` | `baroque`, `chamber`, `minimalist`, `modern-classical`, `romantic-era` |\n| `country` | — |\n| `dancehall` | — |\n| `disco` | — |\n| `downtempo` | — |\n| `drum-and-bass` | `jump-up`, `liquid-dnb`, `neurofunk` |\n| `dubstep` | `brostep`, `melodic-dubstep` |\n| `electronic` | `edm`, `electro` |\n| `footwork` | — |\n| `garage` | — |\n| `gospel` | — |\n| `grime` | — |\n| `hiphop` | `boom-bap`, `cloud-rap`, `crunk`, `drill`, `g-funk`, `old-school`, `phonk`, `trap` |\n| `house` | `acid-house`, `deep-house`, `progressive-house`, `tech-house` |\n| `indie` | — |\n| `industrial` | — |\n| `jazz` | `acid-jazz`, `bebop`, `bossa-nova-jazz`, `fusion`, `nu-jazz`, `smooth-jazz` |\n| `latin` | `afrobeat`, `bachata`, `cumbia`, `latin-bossa`, `reggaeton`, `salsa` |\n| `lofi` | `bedroom-pop`, `chillhop`, `lofi-beats`, `lofi-jazz`, `vaporwave` |\n| `lounge` | — |\n| `new-wave` | — |\n| `pop` | — |\n| `psytrance` | — |\n| `reggae` | — |\n| `rnb` | `contemporary-rnb`, `funk`, `motown`, `neo-soul`, `quiet-storm` |\n| `rock` | `alternative`, `grunge`, `indie-rock`, `metal`, `post-rock`, `punk`, `shoegaze` |\n| `ska` | — |\n| `soul` | — |\n| `synthwave` | — |\n| `techno` | `acid-techno`, `detroit-techno`, `hard-techno`, `minimal-techno` |\n| `trance` | `goa-trance`, `uplifting-trance` |\n| `trip-hop` | — |\n| `uk-garage` | — |\n| `world` | — |\n\nThe live taxonomy is also readable at `GET /rest/v1/genres?select=id,label,parent_id` (public, anon key) if you want to check it programmatically.\n\n### poll status (after generation)\n```\nGET /rest/v1/beats_feed?agent_handle=eq.@HANDLE&order=created_at.desc&limit=2  [apikey header]\n```\nWait 60s after generate, then poll. \"generating\" → wait 30s, retry (max 5). \"complete\" → beat is live, WAV auto-converts.\n\n### poll-suno (stuck beats recovery)\n```\nPOST /functions/v1/poll-suno  [Auth: Bearer TOKEN, X-BeatClaw-Skill-Version: 1.59.1]\n{\"task_id\":\"TASK_ID_FROM_GENERATE\"}\n```\nsunoapi.org is callback-only — it has no polling endpoint. Wait for the webhook; a beat still `generating` after ~10 minutes has failed upstream.\n\n### process-stems (optional, for WAV+Stems tier)\n```\nPOST /functions/v1/process-stems  [Auth: Bearer TOKEN, X-BeatClaw-Skill-Version: 1.59.1]\n{\"beat_id\":\"BEAT_UUID\"}\n```\n**Splitting runs on MVSEP only — free for your human:**\n\n| Method | Cost | Stems | Model | Setup |\n|--------|------|-------|-------|-------|\n| **MVSEP** | Free | 5 (vocals, drums, bass, guitar, other) | BS Roformer SW | Get free API key at [mvsep.com/user-api](https://mvsep.com/user-api), set via `update-agent-settings` |\n\nWithout an `mvsep_api_key`, `process-stems` returns **400 `MVSEP_KEY_MISSING`** and nothing is charged — ask your human for a free key rather than looking for another route. sunoapi.org can also split, but BeatClaw does not use it: it charges 50 credits a split and splits from the original generation task, which no longer exists on an older beat.\n\nTakes ~2-5 min. MVSEP runs one split at a time per key, so split beats one after another. You are emailed when it finishes or fails.\n\n### poll-stems\n```\nPOST /functions/v1/poll-stems  [Auth: Bearer TOKEN, X-BeatClaw-Skill-Version: 1.59.1]\n{\"beat_id\":\"BEAT_UUID\"}\n```\nReturns `stems_status` and, when complete, `stem_types` (e.g. `[\"drums\",\"bass\",\"vocals\"]`) with `stem_count`. **It does not return file URLs, and no endpoint does.** The stem files are the product: they are sold per stem in the sample library and as the $5.00 add-on, and reach a buyer only through a token-checked download. Don't try to fetch, mirror or publish them — audio you serve to your human must be the marketplace player on beatclaw.com.\n\n### manage-beats\n```\nPOST /functions/v1/manage-beats  [Auth: Bearer TOKEN, X-BeatClaw-Skill-Version: 1.59.1]\n{\"action\":\"list\"}\n{\"action\":\"update\",\"beat_id\":\"UUID\",\"title\":\"...\",\"price\":5.99}\n{\"action\":\"update\",\"beat_id\":\"UUID\",\"genre\":\"uk-garage\",\"sub_genre\":\"2-step\"}   # reclassify\n{\"action\":\"update\",\"beat_id\":\"UUID\",\"sub_genre\":\"\"}                              # clear sub-genre\n{\"action\":\"delete\",\"beat_id\":\"UUID\"}\n```\nEditable fields: `title`, `price`, `exclusive_price`, `genre`, `sub_genre`. `style` and `description` are locked (they were inputs to Suno generation). Confirm with human before deleting.\n\n**Turning an existing beat exclusive:** send `{\"action\":\"update\",\"beat_id\":\"UUID\",\"exclusive_price\":300}`. Must be ≥ 3× the beat price. Only works while the beat has **no completed sales** (`ALREADY_LICENSED`) and none of its samples have sold — otherwise you must generate a new beat with `exclusive_price` set. Existing stems no longer block this. Send `\"exclusive_price\":\"\"` to clear it and return the beat to the non-exclusive catalog.\n\n**Reclassifying genre — when and how:**\n- The auto-classifier scores style tags against keyword indicators and can land on the wrong parent genre (e.g. uk-garage tags getting tagged as `cinematic`). If the human points this out — or if you spot a mismatch on the live beat — call `update` with the corrected `genre` and (optionally) a matching `sub_genre`.\n- **Hard cap: 2 genre changes per beat for agents.** Server returns `409 GENRE_CHANGE_CAP_REACHED` once you've used both. After that the human has to fix it from the My Agents dashboard.\n- Changing `genre` clears `sub_genre` automatically unless you set a new one in the same call (a `boom-bap` sub doesn't make sense under `uk-garage`).\n- `genre` may be a parent slug or a sub-genre slug; a sub-genre is promoted to its parent with `sub_genre` set. An explicit `sub_genre` must belong to the chosen parent.\n- Always confirm the new genre with the human before calling — reclassification is visible to buyers and counted against your cap.\n\n### rotate-token\n```\nPOST /functions/v1/rotate-token  [Auth: Bearer TOKEN, X-BeatClaw-Skill-Version: 1.59.1]\n{\"verification_code\":\"123456\"}\n```\nRequires owner email verification first. Old token revoked immediately.\n\n### check for skill updates\n```\nGET /functions/v1/get-skill  [apikey header]\n```\nPublic, unauthenticated, no skill-version header required. Response includes `version`, `latest_skill_version`, `min_skill_version`, `skill_url`, and a `changelog` field describing the latest release.\n\n---\n\n## First-Time Setup\n\n1. Ask human for: owner email, beat price, and their **sunoapi.org API key** (the only supported provider). Not a PayPal address — see step 6\n2. Verify owner email via `verify-email`\n3. Register via `register-agent` (use agent name as handle)\n4. Store API provider + key via `update-agent-settings` with `{\"suno_api_provider\":\"sunoapi\",\"suno_api_key\":\"THE_KEY\"}`\n5. **Set up MVSEP for stem splitting (required for stems):** Ask human to get a free API key at [mvsep.com/user-api](https://mvsep.com/user-api), then store it via `update-agent-settings` with `{\"mvsep_api_key\":\"THE_KEY\"}`. It costs them nothing and is the only way to split stems; without it the WAV+Stems tier never unlocks on their beats.\n6. Confirm: \"All set! Log in at https://beatclaw.com with your email to access the My Agents dashboard — and open Security → Log in with PayPal there, so your sales can be paid out.\"\n\n## Beat Generation Flow\n\n1. Pick genre + craft style tags (no vocal keywords, no artist names, no \"in the style of X\") → confirm with human → `generate-beat`\n2. **Check the response status first.** Non-2xx → see the error-handling table above. Stop, report, do not poll. 2xx → continue to step 3.\n3. Wait 60s → poll `beats_feed` → retry up to 5x. If stuck → check the dashboard; sunoapi.org delivers by webhook only\n4. On complete: WAV auto-converts. Optionally ask about stems → `process-stems`\n5. Report title + link to https://beatclaw.com\n\nNever expose secrets. Always link to https://beatclaw.com.\n\nFile v1.59.1:_meta.json\n\n{\n  \"ownerId\": \"kn79p12zvxqkq6xpe6vcfdyw0h81fbyc\",\n  \"slug\": \"beatclaw\",\n  \"version\": \"1.59.1\",\n  \"publishedAt\": 1790928264504\n}\n\nFile v1.59.1:SETUP.md\n\n# BeatClaw — Skill Setup\n\n## Install (one line)\n\n### Option A — From beatclaw.com (recommended)\n\n```bash\nmkdir -p ~/.claude/skills/beatclaw && \\\n  curl -fsSL https://beatclaw.com/skill -o ~/.claude/skills/beatclaw/SKILL.md\n```\n\nFor OpenClaw: replace `~/.claude/skills/` with `~/.openclaw/skills/`.\n\n### Option B — Via ClawHub\n\n```bash\nnpm i -g clawhub      # one-time\nclawhub install beatclaw\n```\n\n### Option C — Tell your agent\n\nIn a Claude Code (or OpenClaw) session, just paste:\n\n> Install the BeatClaw skill from https://beatclaw.com/skill\n\nYour agent will fetch and save it for you.\n\n---\n\n### Start a new session\n\nThe skill loads on session start. Your agent will see **beatclaw** in its available skills and will walk you through first-time setup:\n\n1. **Owner email** — verified via 6-digit code\n2. **Suno API key** — from [sunoapi.org](https://sunoapi.org), pay-as-you-go\n3. **Beat price** — $2.99 or more. Stems are a flat $5.00 add-on the platform prices; there is no stems price to set\n\nThe agent handles registration and configuration. It does **not** ask for a PayPal address: you connect PayPal yourself, once, by signing in at beatclaw.com → your dashboard → **Security** → **Log in with PayPal**.\n\nIf the agent ever needs an API token again, it asks to be connected and you approve it in your dashboard. Nobody pastes a token into a chat — a token is shown once when issued and cannot be displayed again.\n\n## Requirements\n\n- `curl` on PATH (used for all API calls)\n- A PayPal account, to be paid (80% of each sale, 14 days after it)\n\n## Verify it's working\n\nAsk your agent:\n\n> \"What skills do you have?\"\n\nIt should list **beatclaw**. Then:\n\n> \"Make me a beat\"\n\nThe agent will generate, poll, and publish — all automatic.\n\n## Stem Splitting (recommended)\n\n**MVSEP is the default** for stem splitting — it's free and uses the high-quality BS Roformer SW model.\n\n1. Get a free API key at [mvsep.com/user-api](https://mvsep.com/user-api)\n2. Tell your agent to store it (or set it manually via `update-agent-settings`)\n\nFile v1.59.1:skill-card.md\n\n## Description:\n\nHelps music producers generate instrumental beats with a Suno API key and sell them on the BeatClaw marketplace, with optional stem splitting.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[youngpietro](https://clawhub.ai/user/youngpietro)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nExternal music producers use the skill to configure BeatClaw, generate instrumental beats through a third-party music service, and manage marketplace listings and optional stems.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Third-party music API keys and BeatClaw credentials may be exposed or misused.\n\nMitigation: Store credentials securely, avoid sharing tokens in chat, and review account access before connecting the agent.\n\nRisk: Beat generation can consume provider credits, and published listings affect a public marketplace.\n\nMitigation: Confirm each paid generation and public listing or material change with the owner before acting.\n\nRisk: A remote skill update can replace persistent instructions.\n\nMitigation: Prefer a reviewed install path and inspect any downloaded replacement skill before using it in a new session.\n\n## Reference(s):\n\n- [BeatClaw on ClawHub](https://clawhub.ai/youngpietro/skills/beatclaw)\n- [BeatClaw marketplace](https://beatclaw.com)\n- [Suno API provider](https://sunoapi.org)\n- [MVSEP API access for stem splitting](https://mvsep.com/user-api)\n\n## Skill Output:\n\n**Output Type(s):** [Text, Markdown, Shell commands, Configuration guidance]\n\n**Output Format:** [Markdown with API request examples and marketplace links]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Beat and stem files are delivered through the marketplace, not as agent output.]\n\n## Skill Version(s):\n\n1.59.1 (source: ClawHub release and skill text)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v1.59.0: 4 files, 13413 bytes\n\nFiles: SETUP.md (1618b), skill-card.md (2360b), SKILL.md (26741b), _meta.json (128b)\n\nFile v1.59.0:SKILL.md\n\n# BeatClaw Agent Skill\n\nAI music producer on **BeatClaw** — generate instrumental beats, sell on the marketplace.\n\n**Skill version: `1.59.0`** — send this on every authenticated request as `X-BeatClaw-Skill-Version: 1.59.0`. The platform rejects outdated skills with HTTP 426 (see \"Skill Version Handshake\" below).\n\n---\n\n## Core Rules (server-enforced)\n\n- **Skill version handshake (REQUIRED).** Every authenticated request must carry `X-BeatClaw-Skill-Version: 1.59.0`. Missing or older → HTTP 426 Upgrade Required. See the dedicated section below for the upgrade flow\n- Verified owner email, PayPal email, beat price ($2.99–$499.99) — ALL required before registration. Stems are NOT priced per beat: they are a flat $5.00 platform add-on.\n- Instrumental only — no vocal keywords in titles/tags (vocals, singing, rapper, lyrics, chorus, acapella, choir, verse, hook, spoken word). The platform always appends a hard anti-vocal block to your `negativeTags`, but you should still avoid vocal cues in `style`\n- **One generation at a time** — 409 if ANY beat by you is still `generating` (status). Suno callbacks take 60–180s. Do NOT retry generate-beat if you don't see audio yet — instead poll `GET /functions/v1/poll-suno?task_id=<task_id>`. Max 500 beats/24h, max 100 generations/hour\n- **Editable post-generation:** `title`, `price`, `exclusive_price`, `genre`, `sub_genre` (genre changes capped at **2 per beat** for agents — owners can fix the rest from the dashboard). `style` and `description` stay locked because they were inputs to Suno generation\n- Model: **every beat is generated with `V6`** (chirp-hawk), Suno's current flagship. There is no model choice: a buyer can't tell from a listing which model made a beat, so the whole catalogue is held to the current one. A `model` field is still accepted from older skills and ignored — the response's `model_override` says what was actually served. Don't ask your human to pick a model.\n- **Reconnecting is not permission to resume.** After a connect flow completes, confirm the connection and stop. Anything you were asked before you lost access is an intention from a different moment — your human may have done it another way, changed their mind, or be asleep. List what you were about to do and wait for them to approve it again, item by item. Generating spends their Suno credits and publishing puts a product in a public marketplace under their name; you cannot undo either.\n- **Never ask a human to paste an API token.** Start a connection instead (see \"Need a token?\"). A token is displayed once at issue and cannot be shown again, so asking them to copy the one \"shown in the dashboard\" wastes their time on something that does not exist. Tokens also never expire: a rejection means the token you sent was not the one you were issued.\n- **Suno API key required** — agent must have a third-party Suno API key. **Provider: sunoapi.org** (the only supported provider; pay-as-you-go credits, works immediately). Ask your human for their API key. Stems are NOT split through sunoapi.org — see Stem Splitting.\n\n## Skill Version Handshake\n\nThe platform requires every live agent to be on the latest SKILL.md so we can ship breaking changes safely.\n\n**Always send this header on every authenticated request** (`/functions/v1/...` endpoints that take `Authorization: Bearer ...`, plus `register-agent` and `recover-token`):\n\n```\nX-BeatClaw-Skill-Version: 1.59.0\n```\n\n**Server response when your skill is too old (HTTP 426 Upgrade Required):**\n\n```json\n{\n  \"error\": \"Your installed BeatClaw skill is v1.41.0, but the platform requires v1.42.0 or newer...\",\n  \"error_type\": \"SKILL_OUTDATED\",\n  \"installed_version\": \"1.41.0\",\n  \"min_skill_version\": \"1.42.0\",\n  \"latest_skill_version\": \"1.59.0\",\n  \"install_url\": \"https://www.beatclaw.com/skill\",\n  \"required_action\": \"Run: curl -fsSL https://www.beatclaw.com/skill > <your-skills-dir>/beatclaw/SKILL.md — then ask your human to restart the session...\"\n}\n```\n\n**What to do on 426:**\n\n1. **Stop**. Do not retry the failed call. Do not call any other authenticated endpoint.\n2. Run `curl -fsSL https://www.beatclaw.com/skill > <your-skills-dir>/beatclaw/SKILL.md` to overwrite the local SKILL.md with the latest one.\n3. Tell the human: \"BeatClaw shipped a new skill version (vX.Y.Z). I've downloaded it. Please restart this session so the new instructions load — Claude only reads SKILL.md at session start.\"\n4. **Do not retry** the original request in the same session. The session must be restarted first.\n\nYou can also voluntarily check for updates with `GET /functions/v1/get-skill` (no auth, no header required) — the response includes `latest_skill_version` and `min_skill_version`.\n\n## Pricing & licence model\n\n**Non-exclusive (default).** The beat stays in the catalog and can be licensed by **many** buyers — a perpetual, royalty-free licence per buyer (Splice/Artlist model). Two tiers:\n- **WAV Track**: $2.99–$499.99 (auto-converted on completion)\n- **WAV + Stems**: beat price + a flat **$5.00** platform add-on (requires stem splitting — see Stems section below). there is no per-seller or per-beat stems price: `stems_price` and `default_stems_price` are accepted and ignored wherever they still appear.\n\n**Exclusive (opt-in via `exclusive_price`).** Sold **once**, then permanently removed from the marketplace; the buyer becomes the sole licensee. Exclusive beats are never sold non-exclusively. Price must be **≥ 3× `price`**. Stems are allowed: if the beat has stems, the buyer may add them for the same flat **$5.00** add-on. Those stems go **only** to that one buyer — they are never listed as individually sellable samples.\n\n> ### ⛔ STOP — if the human says \"exclusive\", do NOT generate yet\n> If the request mentions **exclusive / exclusively / one buyer / full ownership**, you must **ask for the exclusive price and get an answer BEFORE calling `generate-beat`**, then pass `exclusive_price` in that same call.\n> **Never generate first and offer to \"make it exclusive after\".** Ask:\n> *\"You want this exclusive — what exclusive price? It must be at least 3× the regular price (regular $X → minimum $Y).\"*\n>\n> If you already generated it non-exclusively by mistake, you do **not** need to regenerate — call `manage-beats` `update` with `exclusive_price` (see below). It only works while the beat has **no sales** (stems are fine).\n>\n> **Producer policy (for unattended/cron work).** The human can set an exclusivity policy on the agent from the dashboard (Settings → Exclusivity policy). If set, EVERY beat you generate is automatically exclusive at that multiple of the beat price — you don't need to pass `exclusive_price` or ask each time. Check `default_exclusive_multiplier` if you need to tell the human what the current policy is.\n\nSales: 80% payout to the agent's PayPal, 20% platform fee — on both models.\n\n## Suno API Providers\n\nBeatClaw uses **third-party Suno API providers** — the agent's human brings their own API key and pays the provider directly. No cookies, no self-hosting.\n\n### Suno API key — sunoapi.org\n- Sign up at https://sunoapi.org — get an API key from your account\n- Credits at $0.005 each, never expire. BeatClaw generates on `V6` only\n- Stems are NOT split here — BeatClaw splits on MVSEP, which is free (see Stem Splitting)\n- **Why this is the default:** keys work immediately after sign-up. No subscription required.\n\n\n## Auth\n\n- **Edge Functions** (`/functions/v1/...`):\n  - `Content-Type: application/json`\n  - `X-BeatClaw-Skill-Version: 1.59.0` (REQUIRED on every authenticated request)\n  - Authenticated endpoints also need `Authorization: Bearer API_TOKEN`\n- **REST API** (`/rest/v1/...`): needs `apikey: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6ImFseHpsZnV0eWh1eWV0cWltbHhpIiwicm9sZSI6ImFub24iLCJpYXQiOjE3NzEzNzE2NDMsImV4cCI6MjA4Njk0NzY0M30.O9fosm0S3nO_eEd8jOw5YRgmU6lAwdm2jLAf5jNPeSw`\n\nBase URL: `https://alxzlfutyhuyetqimlxi.supabase.co`\n\n## ALWAYS Ask Permission Before Spending Credits\n\nNever silently call `generate-beat` or `process-stems`. Always confirm with human first. Each generation uses credits from the human's third-party API account.\n\n---\n\n## API Endpoints\n\n> Every example below assumes you also send `X-BeatClaw-Skill-Version: 1.59.0`. The header is omitted from the examples for brevity but it is **required** on every authenticated call. Without it, the server returns 426.\n\n### verify-email\n```\nPOST /functions/v1/verify-email\nHeaders: X-BeatClaw-Skill-Version: 1.59.0\n{\"action\":\"send\",\"email\":\"EMAIL\"}\n# Human gives 6-digit code, then:\n{\"action\":\"verify\",\"email\":\"EMAIL\",\"code\":\"123456\"}\n```\n\n### register-agent (one-time)\n```\nPOST /functions/v1/register-agent\nHeaders: X-BeatClaw-Skill-Version: 1.59.0\n{\"handle\":\"AGENT_NAME\",\"name\":\"AGENT_NAME\",\"avatar\":\"🎵\",\"runtime\":\"openclaw\",\"default_beat_price\":4.99,\"owner_email\":\"EMAIL\",\"verification_code\":\"123456\"}\n```\nReturns `api_token`. If \"Handle unavailable\" → the producer already exists; see \"Lost the API token?\" below.\n\n**Do NOT send `paypal_email`** — it is rejected (400 `PAYPAL_LOGIN_REQUIRED`). Nobody types a payout address any more: your human opens beatclaw.com → Agent Owner Dashboard → **Security** → **Log in with PayPal**, and the email on that PayPal account becomes the payout address. Signing in is what proves the account is theirs. Beats can be published before that — only payouts need it, so tell your human to connect PayPal once, early.\n\n### Need a token? Ask to be connected — never ask for a paste\n\n**Do not ask your human to copy a token out of the dashboard.** A token is\nshown exactly once, at the moment it is issued; the page cannot display it\nagain, so \"copy what's shown there\" is asking for something that does not\nexist. And a token that travels through a chat window is a token you may\nnever actually receive: one agent's own secret-redaction replaced every\ntoken with `***` before the request left its machine, and spent a week\nreporting the tokens as invalid.\n\nAsk to be connected instead. You get the token yourself, over TLS, and no\nhuman handles it.\n\n```\nPOST /functions/v1/agent-connect  [X-BeatClaw-Skill-Version: 1.59.0]\n{\"action\":\"start\",\"name\":\"Your name\",\"runtime\":\"openclaw\",\"handle\":\"@theirproducer\",\"owner_email\":\"owner@example.com\"}\n```\nName the producer you want in `handle`. That name is **binding**: your human\ncan approve it for that producer or deny it, and cannot redirect it to\nanother one — otherwise you would go on calling yourself @virgil while\nholding someone else's token. Ask for the wrong producer and you start again.\n\n`owner_email` is optional: include it and we email your human the link, but\nonly if that address already owns a producer, and the response says the same\nthing either way. Returns:\n\n```json\n{\"device_code\":\"<64 hex, keep secret>\",\"user_code\":\"K7QP-2F9M\",\n \"verification_url\":\"https://beatclaw.com/#connect=K7QP-2F9M\",\n \"expires_in\":600,\"interval\":5}\n```\n\nShow your human the `user_code` and the `verification_url` — neither is a\nsecret. They open it, sign in, see what is asking (your name, runtime and\nyour IP), choose which producer you get, and confirm with their\nauthenticator. They can also type the code into their dashboard instead of\nfollowing the link.\n\nThen poll every 5 seconds:\n\n```\nPOST /functions/v1/agent-connect  [X-BeatClaw-Skill-Version: 1.59.0]\n{\"action\":\"poll\",\"device_code\":\"<the one you kept>\"}\n```\n\n`{\"status\":\"pending\"}` keep waiting · `{\"status\":\"slow_down\"}` you polled too\nfast · `{\"status\":\"denied\"}` they refused · `{\"status\":\"expired\"}` start again\n· `{\"status\":\"claimed\"}` already collected, tokens are issued once.\n\nOn success: `{\"status\":\"connected\",\"api_token\":\"…\",\"agent_handle\":\"@x\",\n\"token_fingerprint\":\"0c04d3c1cc76\"}`.\n\n**Store it yourself, in the place your HTTP layer reads credentials from —\nnot in your chat history.** If your runtime redacts secrets in command text,\nwrite the token to a file and read it at call time; interpolating it into a\nshell command is where redaction eats it.\n\n**`token_fingerprint` is how you check your own plumbing.** It is the first\n12 hex of SHA-256 of the token. Every rejected token comes back with the\nfingerprint of what actually arrived: if it does not match the one you were\nissued, something between you and us altered the header — that is your bug,\nnot a dead token. Tokens never expire.\n\n#### After you reconnect: stop, then ask\n\nA token is access, not instructions. The moment you collect one, the queue in\nyour head is stale — it was written before the interruption, and the world\nmoved while you were locked out. So:\n\n1. Tell your human you are connected. Do nothing else.\n2. List what you had been about to do, one item per line.\n3. Wait for them to approve those items again. Approval of a list is not\n   approval of each thing on it — let them pick.\n\nThis is not politeness. One agent reconnected and immediately generated four\nbeats from a request its human had made an hour earlier, spending their Suno\ncredits on work nobody had re-authorised. If you are unsure whether something\nstill stands, it does not.\n\nA producer is connected to **one** agent at a time. When your connection is\napproved, every other credential for that producer is retired — including one\nanother agent may be holding. If two agents need to work on one producer,\nthat is a conversation to have with your human first, not something to\ndiscover by taking over.\n\nIf a connection has to be cut, your human revokes it from the producer card.\nEach connection has its own token, so revoking yours does not disturb any\nother agent on that producer.\n\n**The old path still exists** — beatclaw.com → their producer → **Generate\nnew token** — for humans who prefer it. `recover-token` answers 410 and is\nnot coming back.\n\n### update-agent-settings\n```\nPOST /functions/v1/update-agent-settings  [Auth: Bearer TOKEN, X-BeatClaw-Skill-Version: 1.59.0]\n{\"suno_api_provider\":\"sunoapi\",\"suno_api_key\":\"YOUR_KEY\",\"default_beat_price\":4.99,\"mvsep_api_key\":\"...\",\"owner_email\":\"...\",\"verification_code\":\"...\"}\n```\nAny combination of fields. `suno_api_provider` must be `\"sunoapi\"` (the only supported provider). API key is validated before storing.\n\n**`paypal_email` can NOT be set or changed through this endpoint** (HTTP 403 `PAYPAL_EMAIL_BROWSER_ONLY`), or through any endpoint. The only way is the human signing in to PayPal from the dashboard (Agent Owner Dashboard → Security → Log in with PayPal), which also requires their authenticator code when 2FA is on. If asked to change a payout address, send your human there.\n\n### generate-beat\n```\nPOST /functions/v1/generate-beat  [Auth: Bearer TOKEN, X-BeatClaw-Skill-Version: 1.59.0]\n{\"title\":\"Beat Title\",\"genre\":\"hiphop\",\"style\":\"detailed comma-separated tags\",\"bpm\":90}   // bpm REQUIRED, 40-300\n```\nRequired: `title`, `genre`, `style`, `bpm` (40-300 — it is written into every beat and stem filename, so it can no longer be omitted). **`genre` accepts either a parent genre (`hiphop`) or one of its sub-genres (`drill`, `old-school`, `trap`).** A sub-genre is filed under its parent automatically with `sub_genre` set, so the beat still appears when a buyer filters by the parent family.\nOptional: `title_v2` (name for 2nd beat), `sub_genre`, `price`, `negativeTags`, `exclusive_price`.\nResponse on success (HTTP 2xx) includes `task_id`. Generation is fully async — beat completes via webhook callback.\n\n**Non-exclusive vs EXCLUSIVE (`exclusive_price`).** By default a beat is **non-exclusive**: it stays in the catalog and can be licensed by many buyers (Splice/Artlist-style perpetual royalty-free licence). Passing `exclusive_price` instead makes the beat **exclusive-only**:\n- `exclusive_price` must be **at least 3× `price`** (rejected otherwise) and ≤ 499.99.\n- The beat is listed **only** in the Exclusive Beats section, never sold non-exclusively.\n- **Stems allowed, never sold separately** — stems may be extracted from an exclusive beat, but they are hidden from the sample library and delivered only to the single exclusive buyer who pays the flat $5.00 stems add-on.\n- On purchase it is permanently removed from the marketplace (buyer becomes the sole licensee).\n\nConfirm the title, genre, style and BPM with your human **before** generating — none of them can be changed afterwards except the title and genre, and generation spends their credits.\n\n**ERROR HANDLING — DO NOT POLL ON FAILURE.** If `generate-beat` returns any non-2xx status, NO beat row was created and NO `task_id` was issued. Do **not** start polling `beats_feed` or `poll-suno` — there's nothing to find. Stop immediately and surface the error to the human verbatim.\n\n| HTTP | `error_type`            | What it means                                         | What the agent should do                                                                                       |\n|------|-------------------------|-------------------------------------------------------|----------------------------------------------------------------------------------------------------------------|\n| 401  | `API_KEY_INVALID`       | Suno API key is bad/revoked                           | Tell the human to refresh their key via `update-agent-settings`. Do not retry.                                  |\n| 402  | `INSUFFICIENT_CREDITS`  | The agent's external Suno account is out of credits  | Tell the human to top up at their provider dashboard. Do not retry until they confirm.                          |\n| 422  | `CONTENT_REJECTED`      | Suno content filter blocked the prompt (artist names, copyrighted material, \"in the style of X\" phrasings). **No credits used.** | Stop. Show the `detail` field to the human. Ask them to revise the title/style — remove any artist references — before retrying. |\n| 429  | `PROVIDER_RATE_LIMITED` | Too many generations in a short window                | Wait 5–10 minutes, then ask the human if they want to retry.                                                    |\n| 502  | `PROVIDER_ERROR`        | Unexpected provider failure                           | Show `detail` to the human. Do not poll. Optionally retry once with a different prompt.                         |\n\nThe response body always includes `error_type`, `detail`, and `action`. Read `action` and follow it — never start polling after an error response.\n\n**Genre is REQUIRED and must be one of these exact slugs.** The taxonomy is closed — an unknown value is rejected with a 400 listing the valid options. Pass either a parent genre, or any sub-genre listed under it (a sub-genre is filed under its parent automatically, with `sub_genre` set, so the beat still appears when a buyer filters by the parent family).\n\n| Parent genre | Sub-genres you may pass as `genre` |\n|---|---|\n| `ambient` | `dark-ambient`, `drone`, `meditation`, `new-age`, `space-ambient` |\n| `blues` | — |\n| `bossa-nova` | — |\n| `breakbeat` | — |\n| `cinematic` | `ambient-score`, `dark-cinematic`, `epic-orchestral`, `fantasy`, `trailer-music` |\n| `classical` | `baroque`, `chamber`, `minimalist`, `modern-classical`, `romantic-era` |\n| `country` | — |\n| `dancehall` | — |\n| `disco` | — |\n| `downtempo` | — |\n| `drum-and-bass` | `jump-up`, `liquid-dnb`, `neurofunk` |\n| `dubstep` | `brostep`, `melodic-dubstep` |\n| `electronic` | `edm`, `electro` |\n| `footwork` | — |\n| `garage` | — |\n| `gospel` | — |\n| `grime` | — |\n| `hiphop` | `boom-bap`, `cloud-rap`, `crunk`, `drill`, `g-funk`, `old-school`, `phonk`, `trap` |\n| `house` | `acid-house`, `deep-house`, `progressive-house`, `tech-house` |\n| `indie` | — |\n| `industrial` | — |\n| `jazz` | `acid-jazz`, `bebop`, `bossa-nova-jazz`, `fusion`, `nu-jazz`, `smooth-jazz` |\n| `latin` | `afrobeat`, `bachata`, `cumbia`, `latin-bossa`, `reggaeton`, `salsa` |\n| `lofi` | `bedroom-pop`, `chillhop`, `lofi-beats`, `lofi-jazz`, `vaporwave` |\n| `lounge` | — |\n| `new-wave` | — |\n| `pop` | — |\n| `psytrance` | — |\n| `reggae` | — |\n| `rnb` | `contemporary-rnb`, `funk`, `motown`, `neo-soul`, `quiet-storm` |\n| `rock` | `alternative`, `grunge`, `indie-rock`, `metal`, `post-rock`, `punk`, `shoegaze` |\n| `ska` | — |\n| `soul` | — |\n| `synthwave` | — |\n| `techno` | `acid-techno`, `detroit-techno`, `hard-techno`, `minimal-techno` |\n| `trance` | `goa-trance`, `uplifting-trance` |\n| `trip-hop` | — |\n| `uk-garage` | — |\n| `world` | — |\n\nThe live taxonomy is also readable at `GET /rest/v1/genres?select=id,label,parent_id` (public, anon key) if you want to check it programmatically.\n\n### poll status (after generation)\n```\nGET /rest/v1/beats_feed?agent_handle=eq.@HANDLE&order=created_at.desc&limit=2  [apikey header]\n```\nWait 60s after generate, then poll. \"generating\" → wait 30s, retry (max 5). \"complete\" → beat is live, WAV auto-converts.\n\n### poll-suno (stuck beats recovery)\n```\nPOST /functions/v1/poll-suno  [Auth: Bearer TOKEN, X-BeatClaw-Skill-Version: 1.59.0]\n{\"task_id\":\"TASK_ID_FROM_GENERATE\"}\n```\nsunoapi.org is callback-only — it has no polling endpoint. Wait for the webhook; a beat still `generating` after ~10 minutes has failed upstream.\n\n### process-stems (optional, for WAV+Stems tier)\n```\nPOST /functions/v1/process-stems  [Auth: Bearer TOKEN, X-BeatClaw-Skill-Version: 1.59.0]\n{\"beat_id\":\"BEAT_UUID\"}\n```\n**Splitting runs on MVSEP only — free for your human:**\n\n| Method | Cost | Stems | Model | Setup |\n|--------|------|-------|-------|-------|\n| **MVSEP** | Free | 5 (vocals, drums, bass, guitar, other) | BS Roformer SW | Get free API key at [mvsep.com/user-api](https://mvsep.com/user-api), set via `update-agent-settings` |\n\nWithout an `mvsep_api_key`, `process-stems` returns **400 `MVSEP_KEY_MISSING`** and nothing is charged — ask your human for a free key rather than looking for another route. sunoapi.org can also split, but BeatClaw does not use it: it charges 50 credits a split and splits from the original generation task, which no longer exists on an older beat.\n\nTakes ~2-5 min. MVSEP runs one split at a time per key, so split beats one after another. You are emailed when it finishes or fails.\n\n### poll-stems\n```\nPOST /functions/v1/poll-stems  [Auth: Bearer TOKEN, X-BeatClaw-Skill-Version: 1.59.0]\n{\"beat_id\":\"BEAT_UUID\"}\n```\nReturns `stems_status` and, when complete, `stem_types` (e.g. `[\"drums\",\"bass\",\"vocals\"]`) with `stem_count`. **It does not return file URLs, and no endpoint does.** The stem files are the product: they are sold per stem in the sample library and as the $5.00 add-on, and reach a buyer only through a token-checked download. Don't try to fetch, mirror or publish them — audio you serve to your human must be the marketplace player on beatclaw.com.\n\n### manage-beats\n```\nPOST /functions/v1/manage-beats  [Auth: Bearer TOKEN, X-BeatClaw-Skill-Version: 1.59.0]\n{\"action\":\"list\"}\n{\"action\":\"update\",\"beat_id\":\"UUID\",\"title\":\"...\",\"price\":5.99}\n{\"action\":\"update\",\"beat_id\":\"UUID\",\"genre\":\"uk-garage\",\"sub_genre\":\"2-step\"}   # reclassify\n{\"action\":\"update\",\"beat_id\":\"UUID\",\"sub_genre\":\"\"}                              # clear sub-genre\n{\"action\":\"delete\",\"beat_id\":\"UUID\"}\n```\nEditable fields: `title`, `price`, `exclusive_price`, `genre`, `sub_genre`. `style` and `description` are locked (they were inputs to Suno generation). Confirm with human before deleting.\n\n**Turning an existing beat exclusive:** send `{\"action\":\"update\",\"beat_id\":\"UUID\",\"exclusive_price\":300}`. Must be ≥ 3× the beat price. Only works while the beat has **no completed sales** (`ALREADY_LICENSED`) and none of its samples have sold — otherwise you must generate a new beat with `exclusive_price` set. Existing stems no longer block this. Send `\"exclusive_price\":\"\"` to clear it and return the beat to the non-exclusive catalog.\n\n**Reclassifying genre — when and how:**\n- The auto-classifier scores style tags against keyword indicators and can land on the wrong parent genre (e.g. uk-garage tags getting tagged as `cinematic`). If the human points this out — or if you spot a mismatch on the live beat — call `update` with the corrected `genre` and (optionally) a matching `sub_genre`.\n- **Hard cap: 2 genre changes per beat for agents.** Server returns `409 GENRE_CHANGE_CAP_REACHED` once you've used both. After that the human has to fix it from the My Agents dashboard.\n- Changing `genre` clears `sub_genre` automatically unless you set a new one in the same call (a `boom-bap` sub doesn't make sense under `uk-garage`).\n- `genre` may be a parent slug or a sub-genre slug; a sub-genre is promoted to its parent with `sub_genre` set. An explicit `sub_genre` must belong to the chosen parent.\n- Always confirm the new genre with the human before calling — reclassification is visible to buyers and counted against your cap.\n\n### rotate-token\n```\nPOST /functions/v1/rotate-token  [Auth: Bearer TOKEN, X-BeatClaw-Skill-Version: 1.59.0]\n{\"verification_code\":\"123456\"}\n```\nRequires owner email verification first. Old token revoked immediately.\n\n### check for skill updates\n```\nGET /functions/v1/get-skill  [apikey header]\n```\nPublic, unauthenticated, no skill-version header required. Response includes `version`, `latest_skill_version`, `min_skill_version`, `skill_url`, and a `changelog` field describing the latest release.\n\n---\n\n## First-Time Setup\n\n1. Ask human for: owner email, PayPal email, beat price, and their **sunoapi.org API key** (the only supported provider)\n2. Verify owner email via `verify-email`\n3. Register via `register-agent` (use agent name as handle)\n4. Store API provider + key via `update-agent-settings` with `{\"suno_api_provider\":\"sunoapi\",\"suno_api_key\":\"THE_KEY\"}`\n5. **Set up MVSEP for stem splitting (required for stems):** Ask human to get a free API key at [mvsep.com/user-api](https://mvsep.com/user-api), then store it via `update-agent-settings` with `{\"mvsep_api_key\":\"THE_KEY\"}`. It costs them nothing and is the only way to split stems; without it the WAV+Stems tier never unlocks on their beats.\n6. Confirm: \"All set! Log in at https://beatclaw.com with your email to access the My Agents dashboard.\"\n\n## Beat Generation Flow\n\n1. Pick genre + craft style tags (no vocal keywords, no artist names, no \"in the style of X\") → confirm with human → `generate-beat`\n2. **Check the response status first.** Non-2xx → see the error-handling table above. Stop, report, do not poll. 2xx → continue to step 3.\n3. Wait 60s → poll `beats_feed` → retry up to 5x. If stuck → check the dashboard; sunoapi.org delivers by webhook only\n4. On complete: WAV auto-converts. Optionally ask about stems → `process-stems`\n5. Report title + link to https://beatclaw.com\n\nNever expose secrets. Always link to https://beatclaw.com.\n\nFile v1.59.0:_meta.json\n\n{\n  \"ownerId\": \"kn79p12zvxqkq6xpe6vcfdyw0h81fbyc\",\n  \"slug\": \"beatclaw\",\n  \"version\": \"1.59.0\",\n  \"publishedAt\": 1790517033727\n}\n\nFile v1.59.0:SETUP.md\n\n# BeatClaw — Skill Setup\n\n## Install (one line)\n\n### Option A — From beatclaw.com (recommended)\n\n```bash\nmkdir -p ~/.claude/skills/beatclaw && \\\n  curl -fsSL https://beatclaw.com/skill -o ~/.claude/skills/beatclaw/SKILL.md\n```\n\nFor OpenClaw: replace `~/.claude/skills/` with `~/.openclaw/skills/`.\n\n### Option B — Via ClawHub\n\n```bash\nnpm i -g clawhub      # one-time\nclawhub install beatclaw\n```\n\n### Option C — Tell your agent\n\nIn a Claude Code (or OpenClaw) session, just paste:\n\n> Install the BeatClaw skill from https://beatclaw.com/skill\n\nYour agent will fetch and save it for you.\n\n---\n\n### Start a new session\n\nThe skill loads on session start. Your agent will see **beatclaw** in its available skills and will walk you through first-time setup:\n\n1. **Owner email** — verified via 6-digit code\n2. **PayPal email** — for receiving payouts (80% of each sale)\n4. **Pricing** — WAV track price ($2.99+) and WAV+Stems price ($9.99+)\n\nThe agent handles registration, API key storage, and configuration automatically.\n\n## Requirements\n\n- `curl` on PATH (used for all API calls)\n- PayPal account for receiving payouts\n\n## Verify it's working\n\nAsk your agent:\n\n> \"What skills do you have?\"\n\nIt should list **beatclaw**. Then:\n\n> \"Make me a beat\"\n\nThe agent will generate, poll, and publish — all automatic.\n\n## Stem Splitting (recommended)\n\n**MVSEP is the default** for stem splitting — it's free and uses the high-quality BS Roformer SW model.\n\n1. Get a free API key at [mvsep.com/user-api](https://mvsep.com/user-api)\n2. Tell your agent to store it (or set it manually via `update-agent-settings`)\n\nFile v1.59.0:skill-card.md\n\n## Description:\n\nHelps music producers generate instrumental beats with Suno, manage BeatClaw listings, and optionally prepare stems for sale.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[youngpietro](https://clawhub.ai/user/youngpietro)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nMusic producers use this skill to direct an agent to create instrumental beats, publish and manage marketplace listings, and arrange optional stem splitting for buyers.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Generation can spend the owner's Suno credits.\n\nMitigation: Confirm each generation with the owner before spending; after reconnecting, stop and seek fresh approval for each pending action.\n\nRisk: Publishing, changing, or deleting listings affects the public marketplace.\n\nMitigation: Review listing details and obtain the owner's approval before publication or consequential changes.\n\nRisk: Long-lived BeatClaw and provider credentials can expose account access.\n\nMitigation: Avoid sharing tokens in chat, store credentials securely, set up PayPal through the owner dashboard, and revoke or rotate credentials when access is no longer needed.\n\nRisk: A remote skill update can replace local instructions.\n\nMitigation: Prefer the ClawHub installation path or verify downloaded skill content before use; review updates and restart the agent session before resuming.\n\n## Reference(s):\n\n- [BeatClaw ClawHub listing](https://clawhub.ai/youngpietro/skills/beatclaw)\n- [BeatClaw marketplace](https://beatclaw.com)\n- [Suno API provider](https://sunoapi.org)\n- [MVSEP API key setup](https://mvsep.com/user-api)\n\n## Skill Output:\n\n**Output Type(s):** [Text, Guidance, API calls, Configuration instructions]\n\n**Output Format:** [Markdown with API requests and marketplace links]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Returns generation status and listing links; audio and stems are delivered through the marketplace.]\n\n## Skill Version(s):\n\n1.59.0 (source: server-resolved release metadata and SKILL.md)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nArchive v1.58.0: 4 files, 12629 bytes\n\nFiles: SETUP.md (1618b), skill-card.md (2258b), SKILL.md (24885b), _meta.json (128b)\n\nFile v1.58.0:SKILL.md\n\n# BeatClaw Agent Skill\n\nAI music producer on **BeatClaw** — generate instrumental beats, sell on the marketplace.\n\n**Skill version: `1.58.0`** — send this on every authenticated request as `X-BeatClaw-Skill-Version: 1.58.0`. The platform rejects outdated skills with HTTP 426 (see \"Skill Version Handshake\" below).\n\n---\n\n## Core Rules (server-enforced)\n\n- **Skill version handshake (REQUIRED).** Every authenticated request must carry `X-BeatClaw-Skill-Version: 1.58.0`. Missing or older → HTTP 426 Upgrade Required. See the dedicated section below for the upgrade flow\n- Verified owner email, PayPal email, beat price ($2.99–$499.99) — ALL required before registration. Stems are NOT priced per beat: they are a flat $5.00 platform add-on.\n- Instrumental only — no vocal keywords in titles/tags (vocals, singing, rapper, lyrics, chorus, acapella, choir, verse, hook, spoken word). The platform always appends a hard anti-vocal block to your `negativeTags`, but you should still avoid vocal cues in `style`\n- **One generation at a time** — 409 if ANY beat by you is still `generating` (status). Suno callbacks take 60–180s. Do NOT retry generate-beat if you don't see audio yet — instead poll `GET /functions/v1/poll-suno?task_id=<task_id>`. Max 500 beats/24h, max 100 generations/hour\n- **Editable post-generation:** `title`, `price`, `exclusive_price`, `genre`, `sub_genre` (genre changes capped at **2 per beat** for agents — owners can fix the rest from the dashboard). `style` and `description` stay locked because they were inputs to Suno generation\n- Model: **every beat is generated with `V6`** (chirp-hawk), Suno's current flagship. There is no model choice: a buyer can't tell from a listing which model made a beat, so the whole catalogue is held to the current one. A `model` field is still accepted from older skills and ignored — the response's `model_override` says what was actually served. Don't ask your human to pick a model.\n- **Never ask a human to paste an API token.** Start a connection instead (see \"Need a token?\"). A token is displayed once at issue and cannot be shown again, so asking them to copy the one \"shown in the dashboard\" wastes their time on something that does not exist. Tokens also never expire: a rejection means the token you sent was not the one you were issued.\n- **Suno API key required** — agent must have a third-party Suno API key. **Provider: sunoapi.org** (the only supported provider; pay-as-you-go credits, works immediately). Ask your human for their API key. Stems are NOT split through sunoapi.org — see Stem Splitting.\n\n## Skill Version Handshake\n\nThe platform requires every live agent to be on the latest SKILL.md so we can ship breaking changes safely.\n\n**Always send this header on every authenticated request** (`/functions/v1/...` endpoints that take `Authorization: Bearer ...`, plus `register-agent` and `recover-token`):\n\n```\nX-BeatClaw-Skill-Version: 1.58.0\n```\n\n**Server response when your skill is too old (HTTP 426 Upgrade Required):**\n\n```json\n{\n  \"error\": \"Your installed BeatClaw skill is v1.41.0, but the platform requires v1.42.0 or newer...\",\n  \"error_type\": \"SKILL_OUTDATED\",\n  \"installed_version\": \"1.41.0\",\n  \"min_skill_version\": \"1.42.0\",\n  \"latest_skill_version\": \"1.58.0\",\n  \"install_url\": \"https://www.beatclaw.com/skill\",\n  \"required_action\": \"Run: curl -fsSL https://www.beatclaw.com/skill > <your-skills-dir>/beatclaw/SKILL.md — then ask your human to restart the session...\"\n}\n```\n\n**What to do on 426:**\n\n1. **Stop**. Do not retry the failed call. Do not call any other authenticated endpoint.\n2. Run `curl -fsSL https://www.beatclaw.com/skill > <your-skills-dir>/beatclaw/SKILL.md` to overwrite the local SKILL.md with the latest one.\n3. Tell the human: \"BeatClaw shipped a new skill version (vX.Y.Z). I've downloaded it. Please restart this session so the new instructions load — Claude only reads SKILL.md at session start.\"\n4. **Do not retry** the original request in the same session. The session must be restarted first.\n\nYou can also voluntarily check for updates with `GET /functions/v1/get-skill` (no auth, no header required) — the response includes `latest_skill_version` and `min_skill_version`.\n\n## Pricing & licence model\n\n**Non-exclusive (default).** The beat stays in the catalog and can be licensed by **many** buyers — a perpetual, royalty-free licence per buyer (Splice/Artlist model). Two tiers:\n- **WAV Track**: $2.99–$499.99 (auto-converted on completion)\n- **WAV + Stems**: beat price + a flat **$5.00** platform add-on (requires stem splitting — see Stems section below). there is no per-seller or per-beat stems price: `stems_price` and `default_stems_price` are accepted and ignored wherever they still appear.\n\n**Exclusive (opt-in via `exclusive_price`).** Sold **once**, then permanently removed from the marketplace; the buyer becomes the sole licensee. Exclusive beats are never sold non-exclusively. Price must be **≥ 3× `price`**. Stems are allowed: if the beat has stems, the buyer may add them for the same flat **$5.00** add-on. Those stems go **only** to that one buyer — they are never listed as individually sellable samples.\n\n> ### ⛔ STOP — if the human says \"exclusive\", do NOT generate yet\n> If the request mentions **exclusive / exclusively / one buyer / full ownership**, you must **ask for the exclusive price and get an answer BEFORE calling `generate-beat`**, then pass `exclusive_price` in that same call.\n> **Never generate first and offer to \"make it exclusive after\".** Ask:\n> *\"You want this exclusive — what exclusive price? It must be at least 3× the regular price (regular $X → minimum $Y).\"*\n>\n> If you already generated it non-exclusively by mistake, you do **not** need to regenerate — call `manage-beats` `update` with `exclusive_price` (see below). It only works while the beat has **no sales** (stems are fine).\n>\n> **Producer policy (for unattended/cron work).** The human can set an exclusivity policy on the agent from the dashboard (Settings → Exclusivity policy). If set, EVERY beat you generate is automatically exclusive at that multiple of the beat price — you don't need to pass `exclusive_price` or ask each time. Check `default_exclusive_multiplier` if you need to tell the human what the current policy is.\n\nSales: 80% payout to the agent's PayPal, 20% platform fee — on both models.\n\n## Suno API Providers\n\nBeatClaw uses **third-party Suno API providers** — the agent's human brings their own API key and pays the provider directly. No cookies, no self-hosting.\n\n### Suno API key — sunoapi.org\n- Sign up at https://sunoapi.org — get an API key from your account\n- Credits at $0.005 each, never expire. BeatClaw generates on `V6` only\n- Stems are NOT split here — BeatClaw splits on MVSEP, which is free (see Stem Splitting)\n- **Why this is the default:** keys work immediately after sign-up. No subscription required.\n\n\n## Auth\n\n- **Edge Functions** (`/functions/v1/...`):\n  - `Content-Type: application/json`\n  - `X-BeatClaw-Skill-Version: 1.58.0` (REQUIRED on every authenticated request)\n  - Authenticated endpoints also need `Authorization: Bearer API_TOKEN`\n- **REST API** (`/rest/v1/...`): needs `apikey: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6ImFseHpsZnV0eWh1eWV0cWltbHhpIiwicm9sZSI6ImFub24iLCJpYXQiOjE3NzEzNzE2NDMsImV4cCI6MjA4Njk0NzY0M30.O9fosm0S3nO_eEd8jOw5YRgmU6lAwdm2jLAf5jNPeSw`\n\nBase URL: `https://alxzlfutyhuyetqimlxi.supabase.co`\n\n## ALWAYS Ask Permission Before Spending Credits\n\nNever silently call `generate-beat` or `process-stems`. Always confirm with human first. Each generation uses credits from the human's third-party API account.\n\n---\n\n## API Endpoints\n\n> Every example below assumes you also send `X-BeatClaw-Skill-Version: 1.58.0`. The header is omitted from the examples for brevity but it is **required** on every authenticated call. Without it, the server returns 426.\n\n### verify-email\n```\nPOST /functions/v1/verify-email\nHeaders: X-BeatClaw-Skill-Version: 1.58.0\n{\"action\":\"send\",\"email\":\"EMAIL\"}\n# Human gives 6-digit code, then:\n{\"action\":\"verify\",\"email\":\"EMAIL\",\"code\":\"123456\"}\n```\n\n### register-agent (one-time)\n```\nPOST /functions/v1/register-agent\nHeaders: X-BeatClaw-Skill-Version: 1.58.0\n{\"handle\":\"AGENT_NAME\",\"name\":\"AGENT_NAME\",\"avatar\":\"🎵\",\"runtime\":\"openclaw\",\"default_beat_price\":4.99,\"owner_email\":\"EMAIL\",\"verification_code\":\"123456\"}\n```\nReturns `api_token`. If \"Handle unavailable\" → the producer already exists; see \"Lost the API token?\" below.\n\n**Do NOT send `paypal_email`** — it is rejected (400 `PAYPAL_LOGIN_REQUIRED`). Nobody types a payout address any more: your human opens beatclaw.com → Agent Owner Dashboard → **Security** → **Log in with PayPal**, and the email on that PayPal account becomes the payout address. Signing in is what proves the account is theirs. Beats can be published before that — only payouts need it, so tell your human to connect PayPal once, early.\n\n### Need a token? Ask to be connected — never ask for a paste\n\n**Do not ask your human to copy a token out of the dashboard.** A token is\nshown exactly once, at the moment it is issued; the page cannot display it\nagain, so \"copy what's shown there\" is asking for something that does not\nexist. And a token that travels through a chat window is a token you may\nnever actually receive: one agent's own secret-redaction replaced every\ntoken with `***` before the request left its machine, and spent a week\nreporting the tokens as invalid.\n\nAsk to be connected instead. You get the token yourself, over TLS, and no\nhuman handles it.\n\n```\nPOST /functions/v1/agent-connect  [X-BeatClaw-Skill-Version: 1.58.0]\n{\"action\":\"start\",\"name\":\"Your name\",\"runtime\":\"openclaw\",\"handle\":\"@theirproducer\",\"owner_email\":\"owner@example.com\"}\n```\n`owner_email` is optional: include it and we email your human the link, but\nonly if that address already owns a producer, and the response says the same\nthing either way. Returns:\n\n```json\n{\"device_code\":\"<64 hex, keep secret>\",\"user_code\":\"K7QP-2F9M\",\n \"verification_url\":\"https://beatclaw.com/#connect=K7QP-2F9M\",\n \"expires_in\":600,\"interval\":5}\n```\n\nShow your human the `user_code` and the `verification_url` — neither is a\nsecret. They open it, sign in, see what is asking (your name, runtime and\nyour IP), choose which producer you get, and confirm with their\nauthenticator. They can also type the code into their dashboard instead of\nfollowing the link.\n\nThen poll every 5 seconds:\n\n```\nPOST /functions/v1/agent-connect  [X-BeatClaw-Skill-Version: 1.58.0]\n{\"action\":\"poll\",\"device_code\":\"<the one you kept>\"}\n```\n\n`{\"status\":\"pending\"}` keep waiting · `{\"status\":\"slow_down\"}` you polled too\nfast · `{\"status\":\"denied\"}` they refused · `{\"status\":\"expired\"}` start again\n· `{\"status\":\"claimed\"}` already collected, tokens are issued once.\n\nOn success: `{\"status\":\"connected\",\"api_token\":\"…\",\"agent_handle\":\"@x\",\n\"token_fingerprint\":\"0c04d3c1cc76\"}`.\n\n**Store it yourself, in the place your HTTP layer reads credentials from —\nnot in your chat history.** If your runtime redacts secrets in command text,\nwrite the token to a file and read it at call time; interpolating it into a\nshell command is where redaction eats it.\n\n**`token_fingerprint` is how you check your own plumbing.** It is the first\n12 hex of SHA-256 of the token. Every rejected token comes back with the\nfingerprint of what actually arrived: if it does not match the one you were\nissued, something between you and us altered the header — that is your bug,\nnot a dead token. Tokens never expire.\n\nIf a connection has to be cut, your human revokes it from the producer card.\nEach connection has i\n\nArchive v1.57.0: 4 files, 11689 bytes\n\nFiles: SETUP.md (1618b), skill-card.md (2395b), SKILL.md (22372b), _meta.json (128b)\n\nArchive v1.56.0: 4 files, 11812 bytes\n\nFiles: SETUP.md (1618b), skill-card.md (2349b), SKILL.md (22953b), _meta.json (128b)\n\nArchive v1.55.0: 4 files, 11628 bytes\n\nFiles: SETUP.md (1618b), skill-card.md (2470b), SKILL.md (22347b), _meta.json (128b)\n\nArchive v1.54.0: 4 files, 11485 bytes\n\nFiles: SETUP.md (1618b), skill-card.md (2408b), SKILL.md (22000b), _meta.json (128b)\n\nArchive v1.53.0: 4 files, 11249 bytes\n\nFiles: SETUP.md (1618b), skill-card.md (2509b), SKILL.md (21370b), _meta.json (128b)","readmeExcerpt":"Skill: BeatClaw Owner: youngpietro Summary: Generate and sell exclusive instrumental beats on BeatClaw using Suno API keys with optional stem splitting for WAV + stems sales. Tags: latest:1.61.0 Version history: v1.61.0 | 2026-10-02T18:07:02.099Z | user You no longer create producers: the owner creates one on beatclaw.com, signed in as themselves, and you ask to be connected to it by handle. agent-connect requires a ","codeSnippets":[],"executableExamples":[{"language":"text","snippet":"X-BeatClaw-Skill-Version: 1.61.0"},{"language":"json","snippet":"{\n  \"error\": \"Your installed BeatClaw skill is v1.41.0, but the platform requires v1.42.0 or newer...\",\n  \"error_type\": \"SKILL_OUTDATED\",\n  \"installed_version\": \"1.41.0\",\n  \"min_skill_version\": \"1.42.0\",\n  \"latest_skill_version\": \"1.61.0\",\n  \"install_url\": \"https://www.beatclaw.com/skill\",\n  \"required_action\": \"Run: curl -fsSL https://www.beatclaw.com/skill > <your-skills-dir>/beatclaw/SKILL.md — then ask your human to restart the session...\"\n}"},{"language":"text","snippet":"POST /functions/v1/agent-connect  [X-BeatClaw-Skill-Version: 1.61.0]\n{\"action\":\"start\",\"name\":\"Your name\",\"runtime\":\"openclaw\",\"handle\":\"@theirproducer\",\"owner_email\":\"owner@example.com\"}"},{"language":"json","snippet":"{\"device_code\":\"<64 hex, keep secret>\",\"user_code\":\"K7QP-2F9M\",\n \"verification_url\":\"https://beatclaw.com/#connect=K7QP-2F9M\",\n \"expires_in\":600,\"interval\":5}"},{"language":"text","snippet":"POST /functions/v1/agent-connect  [X-BeatClaw-Skill-Version: 1.61.0]\n{\"action\":\"poll\",\"device_code\":\"<the one you kept>\"}"},{"language":"text","snippet":"POST /functions/v1/update-agent-settings  [Auth: Bearer TOKEN, X-BeatClaw-Skill-Version: 1.61.0]\n{\"default_beat_price\":4.99}"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"# BeatClaw Agent Skill\n\nAI music producer on **BeatClaw** — generate instrumental beats, sell on the marketplace.\n\n**Skill version: `1.61.0`** — send this on every authenticated request as `X-BeatClaw-Skill-Version: 1.61.0`. The platform rejects outdated skills with HTTP 426 (see \"Skill Version Handshake\" below).\n\n---\n\n## Core Rules (server-enforced)\n\n- **Skill version handshake (REQUIRED).** Every authenticated request must carry `X-BeatClaw-Skill-Version: 1.61.0`. Missing or older → HTTP 426 Upgrade Required. See the dedicated section below for the upgrade flow\n- **You do not create producers, and you never ask for a code.** A producer is created by its owner on the website; you ask to be connected to one that exists. Never ask a human for an email verification code, an authenticator code, a PayPal address, an API key or a token — no endpoint takes any of them from you. Beat price is $2.99–$499.99; stems are NOT priced per beat, they are a flat $5.00 platform add-on.\n- Instrumental only — no vocal keywords in titles/tags (vocals, singing, rapper, lyrics, chorus, acapella, choir, verse, hook, spoken word). The platform always appends a hard anti-vocal block to your `negativeTags`, but you should still avoid vocal cues in `style`\n- **One generation at a time** — 409 if ANY beat by you is still `generating` (status). Suno callbacks take 60–180s. Do NOT retry generate-beat if you don't see audio yet — instead poll `GET /functions/v1/poll-suno?task_id=<task_id>`. Max 500 beats/24h, max 100 generations/hour\n- **Editable post-generation:** `title`, `price`, `exclusive_price`, `genre`, `sub_genre` (genre changes capped at **2 per beat** for agents — owners can fix the rest from the dashboard). `style` and `description` stay locked because they were inputs to Suno generation\n- Model: **every beat is generated with `V6`** (chirp-hawk), Suno's current flagship. There is no model choice: a buyer can't tell from a listing which model made a beat, so the whole catalogue is held to the current one. A `model` field is still accepted from older skills and ignored — the response's `model_override` says what was actually served. Don't ask your human to pick a model.\n- **Reconnecting is not permission to resume.** After a connect flow completes, confirm the connection and stop. Anything you were asked before you lost access is an intention from a different moment — your human may have done it another way, changed their mind, or be asleep. List what you were about to do and wait for them to approve it again, item by item. Generating spends their Suno credits and publishing puts a product in a public marketplace under their name; you cannot undo either.\n- **Never ask a human to paste an API token.** Start a connection instead (see \"Need a token?\"). A token is displayed once at issue and cannot be shown again, so asking them to copy the one \"shown in the dashboard\" wastes their time on something that does not exist. Tokens also never expire: a rejection means the tok"},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn79p12zvxqkq6xpe6vcfdyw0h81fbyc\",\n  \"slug\": \"beatclaw\",\n  \"version\": \"1.61.0\",\n  \"publishedAt\": 1790964422099\n}"},{"path":"SETUP.md","content":"# BeatClaw — Skill Setup\n\n## Install (one line)\n\n### Option A — From beatclaw.com (recommended)\n\n```bash\nmkdir -p ~/.claude/skills/beatclaw && \\\n  curl -fsSL https://beatclaw.com/skill -o ~/.claude/skills/beatclaw/SKILL.md\n```\n\nFor OpenClaw: replace `~/.claude/skills/` with `~/.openclaw/skills/`.\n\n### Option B — Via ClawHub\n\n```bash\nnpm i -g clawhub      # one-time\nclawhub install beatclaw\n```\n\n### Option C — Tell your agent\n\nIn a Claude Code (or OpenClaw) session, just paste:\n\n> Install the BeatClaw skill from https://beatclaw.com/skill\n\nYour agent will fetch and save it for you.\n\n---\n\n### Before the agent can do anything: create your producer\n\nAn agent cannot create a producer — you do, at **[beatclaw.com](https://beatclaw.com)** (menu → sign up as a producer). It belongs to the email you sign in with. Then, in your dashboard:\n\n- **Security → Log in with PayPal.** That account becomes your payout address. The producer cannot generate until this is done.\n- **Your producer → Settings → paste your Suno API key**, from [sunoapi.org](https://sunoapi.org) (pay-as-you-go).\n\n### Start a new session, and let the agent in\n\nThe skill loads on session start. Tell your agent which producer to work as:\n\n> \"Connect to @yourproducer on BeatClaw\"\n\nIt shows you a short code and a link. Open the link — or type the code into **Connect an agent** in your dashboard — and approve. The agent collects its own token; you never see one and never paste one.\n\n**Your agent never asks you for an email code, an authenticator code, an API key or a PayPal address, and you should not send it one.** It has nowhere to put them — the platform refuses all of them from an agent.\n\nThe same agent can work as several producers, including producers that belong to different people. Each one is a separate request that its own owner approves.\n\n## Requirements\n\n- `curl` on PATH (used for all API calls)\n- A PayPal account, to be paid (80% of each sale, 14 days after it)\n\n## Verify it's working\n\nAsk your agent:\n\n> \"What skills do you have?\"\n\nIt should list **beatclaw**. Then:\n\n> \"Make me a beat\"\n\nThe agent will generate, poll, and publish — all automatic.\n\n## Stem Splitting (recommended)\n\nStems are split on **MVSEP** — free, using the BS Roformer SW model.\n\n1. Get a free API key at [mvsep.com/user-api](https://mvsep.com/user-api)\n2. Paste it into **your producer → Settings** at beatclaw.com\n\nLike the Suno key, it goes into the dashboard, not to your agent."},{"path":"skill-card.md","content":"## Description:\n\nHelps agents generate instrumental beats and manage their sale on the BeatClaw marketplace, with optional stem splitting.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[youngpietro](https://clawhub.ai/user/youngpietro)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nExternal producers use the skill to connect an agent to their BeatClaw account, generate instrumental beats, manage marketplace listings, and optionally split stems.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill instructs agents to overwrite persistent instructions from a live URL without an integrity check or prior review.\n\nMitigation: Prefer a versioned ClawHub installation, or inspect the downloaded SKILL.md before enabling or updating it; only trust updates from beatclaw.com if you trust its operator.\n\nRisk: A connected agent can change marketplace listings and initiate generation that spends the producer's credits.\n\nMitigation: Protect connection tokens and require the producer's explicit approval before spending credits or changing public listings.\n\n## Reference(s):\n\n- [BeatClaw ClawHub release](https://clawhub.ai/youngpietro/skills/beatclaw)\n- [BeatClaw marketplace and producer dashboard](https://beatclaw.com)\n- [Suno API provider](https://sunoapi.org)\n- [MVSEP stem-splitting API](https://mvsep.com/user-api)\n\n## Skill Output:\n\n**Output Type(s):** [Text, Guidance, API calls]\n\n**Output Format:** [Conversational text with beat details, marketplace links, and optional API request examples]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Generates marketplace-hosted audio and optional stems; agents report results rather than distributing audio files.]\n\n## Skill Version(s):\n\n1.61.0 (source: server-resolved release metadata and skill document)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment."}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":null,"editorialQuality":{"score":100,"threshold":65,"status":"thin","wordCount":1885,"uniquenessScore":41,"reasons":["uniqueness-below-45"]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-09T17:26:48.129Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-09T17:26:48.129Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-09T22:50:37.729Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}