feat: Marketing Swarm v2 — templates, SDK, CLI, MCP, and docs

.claude/rules/agentlaunch.md

@@ -26,13 +26,22 @@ When working with AgentLaunch tokens and the platform API:
 - Set `AGENT_LAUNCH_ENV=dev` to use dev URLs
 - Direct override: set `AGENT_LAUNCH_API_URL`
 
-## Handoff Protocol
+## Wallet & Key Management
 
-- Agents NEVER hold private keys
-- All on-chain actions go through handoff links
+- Agents have auto-provisioned Fetch.ai wallets (`fetch1...`) via `agent.wallet`
+- For BSC/EVM operations, agents store private keys via Agentverse Secrets API
+- Handoff links are used for irreversible actions (token deployment, 120 FET)
+- Autonomous trading uses agent-held keys for routine operations
 - Deploy link: `https://agent-launch.ai/deploy/{tokenId}`
 - Trade link: `https://agent-launch.ai/trade/{tokenAddress}?action=buy&amount=100`
 
+### Wallet Access (Runtime-Verified)
+
+- `ctx.wallet` **DOES NOT EXIST** — never use it
+- `agent.wallet` **EXISTS** — `cosmpy.aerial.wallet.LocalWallet`
+- `ctx.ledger` **EXISTS** — `cosmpy.aerial.client.LedgerClient`
+- Balance query: `ctx.ledger.query_bank_balance(str(agent.wallet.address()), "atestfet")`
+
 ## Key Endpoints (VERIFIED - always use these exact paths)
 
 ```

.claude/rules/consumer-payments.md

@@ -0,0 +1,157 @@
+# Consumer Payments Rules
+
+## Multi-Token Support
+
+The toolkit supports FET and USDC on BSC (Testnet chain 97, Mainnet chain 56).
+
+### Known Token Addresses
+
+| Token | Chain | Address |
+|-------|-------|---------|
+| FET | BSC Testnet (97) | `0x304ddf3eE068c53514f782e2341B71A80c8aE3C7` |
+| FET | BSC Mainnet (56) | `0xBd5df99ABe0E2b1e86BE5eC0039d1e24de28Fe87` |
+| USDC | BSC Testnet (97) | `0x64544969ed7EBf5f083679233325356EbE738930` |
+| USDC | BSC Mainnet (56) | `0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d` |
+
+### Token Registry
+
+Use `getToken(symbol, chainId)` to look up tokens. Never hardcode addresses.
+
+```typescript
+import { getToken, KNOWN_TOKENS } from 'agentlaunch-sdk';
+const fet = getToken('FET', 97);   // PaymentToken object
+const usdc = getToken('USDC', 97); // PaymentToken object
+```
+
+## Spending Delegation
+
+Uses standard ERC-20 `approve()` / `transferFrom()` — no custom contracts.
+
+### Flow
+
+1. Agent generates delegation handoff link → sends to human
+2. Human opens link, connects wallet, signs `approve()` transaction
+3. Agent checks allowance on-chain with `checkAllowance()`
+4. Agent spends from delegation with `spendFromDelegation()` (calls `transferFrom`)
+
+### SDK Functions
+
+```typescript
+import { checkAllowance, spendFromDelegation, createSpendingLimitHandoff } from 'agentlaunch-sdk';
+
+// Generate link for human to approve
+const link = createSpendingLimitHandoff({ tokenSymbol: 'FET', amount: '100' }, agentWallet);
+
+// Check on-chain allowance
+const limit = await checkAllowance(tokenAddress, ownerAddress, spenderAddress, 97);
+
+// Spend from delegation
+const result = await spendFromDelegation(tokenAddress, owner, recipient, '10');
+```
+
+## Invoices
+
+Invoices are stored in Agentverse agent storage (consistent with existing revenue/pricing patterns).
+
+### Storage Keys
+
+- `invoice_{id}` — Individual invoice JSON
+- `invoice_index` — Array of invoice IDs
+
+### Invoice Lifecycle
+
+`pending` → `paid` → (done)
+`pending` → `expired`
+`paid` → `refunded`
+`paid` → `disputed`
+
+### SDK Functions
+
+```typescript
+import { createInvoice, getInvoice, listInvoices, updateInvoiceStatus } from 'agentlaunch-sdk';
+
+const inv = await createInvoice(agentAddress, { id, issuer, payer, service, amount });
+const invoices = await listInvoices(agentAddress, 'pending');
+await updateInvoiceStatus(agentAddress, invoiceId, 'paid', txHash);
+```
+
+## Fiat Onramp
+
+Fiat is handoff-only — generate URLs to MoonPay/Transak, never process fiat directly.
+
+### Supported Providers
+
+| Provider | Env Var | URL |
+|----------|---------|-----|
+| MoonPay | `MOONPAY_API_KEY` | `https://buy.moonpay.com` |
+| Transak | `TRANSAK_API_KEY` | `https://global.transak.com` |
+
+### SDK Function
+
+```typescript
+import { generateFiatOnrampLink } from 'agentlaunch-sdk';
+
+const link = generateFiatOnrampLink({
+  fiatAmount: '50',
+  fiatCurrency: 'USD',
+  cryptoToken: 'FET',
+  walletAddress: '0x...',
+  provider: 'moonpay',
+});
+// Returns { provider, url }
+```
+
+## Consumer Commerce Template
+
+The `consumer-commerce` template generates agents with:
+- MultiTokenPricingTable — FET + USDC columns
+- InvoiceManager — CRUD in ctx.storage
+- FiatOnrampHelper — card purchase link generation
+- DelegationChecker — verify allowance before auto-pay
+
+### Presets
+
+| Preset | Symbol | Use Case |
+|--------|--------|----------|
+| `payment-processor` | $PAY | Multi-token payment routing |
+| `booking-agent` | $BOOK | Service booking + payment |
+| `subscription-manager` | $SUB | Recurring billing with delegation |
+| `escrow-service` | $ESCR | Funds held until delivery confirmed |
+
+### Scaffold Command
+
+```bash
+agentlaunch scaffold my-agent --type consumer-commerce
+```
+
+## MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `multi_token_payment` | Send FET, USDC, or ERC-20 payment |
+| `check_spending_limit` | Read ERC-20 allowance |
+| `create_delegation` | Generate delegation handoff link |
+| `get_fiat_link` | Generate MoonPay/Transak URL |
+| `create_invoice` | Create payment invoice |
+| `list_invoices` | List invoices by status |
+| `get_multi_token_balances` | Query FET + USDC + BNB balances |
+
+## CLI Commands
+
+```bash
+agentlaunch wallet balances                          # Multi-token balance display
+agentlaunch wallet delegate FET 100 --spender 0x...  # Generate delegation link
+agentlaunch wallet allowance FET --owner 0x... --spender 0x...  # Check limit
+agentlaunch wallet send USDC 0x... 10                # Multi-token transfer
+agentlaunch pay 0x... 10 --token USDC                # Pay in any token
+agentlaunch invoice create --agent agent1q... --payer 0x... --service api --amount 10
+agentlaunch invoice list --agent agent1q... --status pending
+```
+
+## Backward Compatibility
+
+- All new type fields are optional — existing FET-only agents are unchanged
+- New fields on PricingEntry: `altPrices?`, `acceptedTokens?`
+- New fields on AgentRevenue: `revenueByToken?`
+- New fields on AgentCommerceStatus: `usdcBalance?`, `tokenBalances?`, `activeInvoices?`, `delegations?`
+- Default token is always FET when not specified

.claude/rules/marketing-swarm.md

@@ -0,0 +1,61 @@
+# Marketing Team Swarm Rules
+
+## The 7 Roles
+
+| Role | Token | Services | Price/call | Interval |
+|------|-------|----------|-----------|----------|
+| Writer | $WRITE | blog_post, tweet_thread, newsletter, ad_copy | 0.01 FET | on-demand |
+| Social | $POST | post_tweet, schedule_thread, reply_mentions | 0.005 FET | 5 min |
+| Community | $COMM | moderate, answer_faq, run_poll | 0.002 FET | 1 min |
+| Analytics | $STATS | engagement_report, audience_insights, content_performance | 0.005 FET | 5 min |
+| Outreach | $REACH | find_partners, draft_pitch, send_email | 0.01 FET | on-demand |
+| Ads | $ADS | create_ad, ab_test, campaign_report | 0.01 FET | 5 min |
+| Strategy | $PLAN | content_calendar, brand_audit, competitor_analysis, campaign_plan | 0.02 FET | on-demand |
+
+## Build Order
+
+Writer -> Community -> Social -> Analytics -> Outreach -> Ads -> Strategy
+
+Writer first (everyone needs content), Community second (standalone engagement).
+
+## Starter Configurations
+
+- **Content only**: Writer (1 agent)
+- **Social presence**: Writer + Social (2 agents)
+- **Community**: Writer + Community + Social (3 agents)
+- **Analytics stack**: Writer + Social + Analytics (3 agents)
+- **Full team**: All 7
+
+## Customizing SwarmBusiness
+
+The swarm-starter template marks the business logic section:
+```python
+# === YOUR SWARM LOGIC ===
+```
+
+This is where you add:
+- Custom message handlers for your services
+- Interval tasks for background work
+- Integration with external APIs
+- Agent-to-agent communication logic
+
+## Adding New Roles
+
+1. Define the role's services and pricing
+2. Create a preset in `packages/templates/src/presets.ts`
+3. Generate from swarm-starter template with role variables
+4. Deploy and wire into the swarm
+
+## Cross-Holdings
+
+Agents can buy each other's tokens:
+- Strategy buys Writer tokens (values its content)
+- Writer buys Analytics tokens (values its performance data)
+- Creates economic alignment between agents
+
+## Token Lifecycle
+
+1. Deploy agent on Agentverse
+2. Tokenize on AgentLaunch (120 FET deploy fee)
+3. Bonding curve active (2% fee to protocol treasury, NO creator fee)
+4. At 30,000 FET -> auto DEX listing (graduation)

.claude/rules/payment-protocol.md

@@ -1,5 +1,7 @@
 # Payment Protocol Rules
 
+> **Status:** Payment protocol import verified available on Agentverse (2026-03-04).
+
 ## Official Imports (uagents_core)
 
 ```python
@@ -19,15 +21,14 @@ from uagents_core.contrib.protocols.payment import (
 ```python
 from uagents import Protocol
 
-# Create payment protocol instance (role is inferred from handlers you register)
-payment_proto = Protocol(spec=payment_protocol_spec)
+# Seller side (agents that charge for services):
+payment_proto = Protocol(spec=payment_protocol_spec, role="seller")
 
-# Register seller handlers (CommitPayment, RejectPayment, CancelPayment)
-# OR buyer handlers (RequestPayment, CompletePayment)
-# The handlers you register determine the role
+# Buyer side (agents that pay for services):
+payment_proto = Protocol(spec=payment_protocol_spec, role="buyer")
 ```
 
-**Note:** `agent.create_protocol()` does NOT exist on Agentverse. Always use `Protocol(spec=...)`.
+**Note:** The payment protocol has defined roles. You MUST specify `role="seller"` or `role="buyer"` when creating the protocol. `agent.create_protocol()` does NOT exist on Agentverse. Always use `Protocol(spec=..., role=...)`.
 
 ## Payment Flow