diff --git a/showcase/varius-ai-shopping-assistant/README.md b/showcase/varius-ai-shopping-assistant/README.md new file mode 100644 index 0000000..f312a3e --- /dev/null +++ b/showcase/varius-ai-shopping-assistant/README.md @@ -0,0 +1,56 @@ +# Varius — Telegram AI Shopping Assistant + +**@virtualshoppingbot** on Telegram + +Varius turns a plain-text shopping or travel request into a tracked affiliate link with USDC cashback, minted through an on-chain ACP v2 escrow job. + +## What it does + +1. User sends a natural-language request ("find me a hotel in Penang this weekend") +2. Varius extracts intent using Kimi K2 via Virtuals Agent Compute +3. Varius returns 3 merchant recommendations with cashback rates +4. When the user signals purchase intent, Varius fires an ACP v2 job on Base Mainnet to the Laguna bridge agent +5. The Laguna agent mints a tracked affiliate shortlink and delivers it back via ACP +6. User clicks the link, books with the merchant, and earns USDC cashback tracked to their wallet +7. `/dashboard` shows pending and available USDC earnings + +## EconomyOS primitives used + +- **Agent Compute** — Kimi K2 via `os.virtuals.io` for intent extraction and recommendations +- **ACP v2** — on-chain USDC escrow on Base Mainnet for every affiliate link mint +- **Agent Registry** — provider agent discovered at runtime via `browseAgents` +- **SocketTransport** — real-time job lifecycle events + +## Demo + +- Live bot: https://t.me/virtualshoppingbot +- Demo video: https://youtu.be/dVV-3BPpvzE + +## Structure + +``` +showcase/varius-ai-shopping-assistant/ + README.md ← this file + showcase.json ← Showcase card metadata + soul.md ← Public agent context + examples/ + penang-hotel-run.md ← Full run log (redacted) + offerings/ + offerings.json ← ACP provider offerings (mint_link, sweep_commissions) + skills/ + laguna-affiliate-link-via-acp/ + SKILL.md ← Reusable skill + examples/ + hotel-search/ + README.md + prompt.md + result-redacted.md +``` + +## Reusing the skill + +```bash +cp -R showcase/varius-ai-shopping-assistant/skills/laguna-affiliate-link-via-acp ~/.agents/skills/ +``` + +The skill works with any merchant in the Laguna Network catalogue (1000+ merchants across travel, retail, and lifestyle). diff --git a/showcase/varius-ai-shopping-assistant/examples/penang-hotel-run.md b/showcase/varius-ai-shopping-assistant/examples/penang-hotel-run.md new file mode 100644 index 0000000..0e673c0 --- /dev/null +++ b/showcase/varius-ai-shopping-assistant/examples/penang-hotel-run.md @@ -0,0 +1,63 @@ +# Example Run: Penang Hotel Search + +**Date:** 2026-07-02 +**Bot:** @virtualshoppingbot (Telegram) +**Outcome:** 2 affiliate links minted, 2 ACP jobs completed on Base Mainnet + +--- + +## User session + +``` +User: i want to go to penang this weekend, find me hotels + +Varius: Here are some options for Penang this weekend: + + 1. Hard Rock Hotel Penang — Batu Ferringhi beachfront, + music-themed resort with multiple pools - ~$150/night + 2. [Hotel B] — sea view, family-friendly - ~$90/night + 3. [Hotel C] — boutique, city centre - ~$80/night + + → We recommend booking via Trip.com (5% rebate) 🏨 + — affiliate link coming shortly ⏳ + + [~38 seconds later] + + Here are your booking links: + 🔗 Trip.com · 5% rebate → https://agents.laguna.network/r/[REDACTED] + 🔗 Agoda · 6% rebate → https://agents.laguna.network/r/[REDACTED] + + Both links earn you cashback. Click either to book! + +User: /dashboard + +Varius: Your Laguna Cashback Dashboard + Pending: 0.42 USDC + Available: 1.85 USDC + Total conversions: 7 +``` + +--- + +## ACP job trace (redacted) + +| Field | Job A (Trip.com) | Job B (Agoda) | +|---|---|---| +| Job ID | [REDACTED] | [REDACTED] | +| Provider | ACPLagunaTranslator | ACPLagunaTranslator | +| Offering | mint_link | mint_link | +| Budget | 0.01 USDC | 0.01 USDC | +| Network | Base Mainnet | Base Mainnet | +| Status | completed | completed | +| Latency | ~35s | ~38s | +| Deliverable | affiliate shortlink | affiliate shortlink | + +Both jobs ran in parallel. Total wall-clock time from user intent signal to both links delivered: ~38 seconds. + +--- + +## Compute trace + +- Model: `kimi-k2-instruct` via Virtuals Agent Compute (`os.virtuals.io`) +- Calls: intent extraction × 2 (initial query + purchase intent signal), recommendation generation × 1 +- Total compute spend: ~$0.002 diff --git a/showcase/varius-ai-shopping-assistant/offerings/offerings.json b/showcase/varius-ai-shopping-assistant/offerings/offerings.json new file mode 100644 index 0000000..25b8556 --- /dev/null +++ b/showcase/varius-ai-shopping-assistant/offerings/offerings.json @@ -0,0 +1,29 @@ +{ + "agent_name": "ACPLagunaTranslator", + "version": "1.0", + "builder": "yx-laguna", + "chain": "base", + "wallet": "REDACTED", + "offerings": { + "acp_jobs": [ + { + "id": 1, + "name": "mint_link", + "title": "Mint Affiliate Link", + "category": "commerce", + "price": "$0.01 USDC", + "sla_minutes": 2, + "description": "Given a merchant name and a user EVM wallet address, searches the Laguna Network merchant catalogue, selects the best cashback rate, and mints a tracked affiliate shortlink. The shortlink registers the user's wallet for USDC cashback on any qualifying purchase. Supports 1000+ merchants across travel, retail, and lifestyle categories." + }, + { + "id": 2, + "name": "sweep_commissions", + "title": "Sweep Commissions", + "category": "commerce", + "price": "$0.01 USDC", + "sla_minutes": 2, + "description": "Checks the Laguna Network dashboard for a given user wallet and sweeps any available (confirmed) USDC commissions. Returns the pending balance, available balance, and total conversion count." + } + ] + } +} diff --git a/showcase/varius-ai-shopping-assistant/showcase.json b/showcase/varius-ai-shopping-assistant/showcase.json new file mode 100644 index 0000000..7b59d04 --- /dev/null +++ b/showcase/varius-ai-shopping-assistant/showcase.json @@ -0,0 +1,74 @@ +{ + "slug": "varius-ai-shopping-assistant", + "title": "Varius — Telegram AI Shopping Assistant", + "tagline": "Turns a plain-text shopping request in Telegram into a tracked affiliate link with USDC cashback, minted through an on-chain ACP escrow job", + "description": "Varius is a production Telegram AI assistant (@virtualshoppingbot) that turns a plain-text shopping or travel request into a tracked affiliate link with USDC cashback. The bot uses Virtuals Agent Compute (Kimi K2) for intent extraction and recommendations, then fires an ACP v2 job to hire a Laguna bridge agent that mints the affiliate shortlink. Every link mint is a real on-chain USDC escrow job on Base Mainnet. The end user sees only a clean Telegram conversation and a USDC earnings dashboard; the on-chain agentic commerce layer is invisible.", + "status": "production", + "topic": "commerce", + "topics": ["commerce", "compute", "acp"], + "hidden": false, + "builder": { + "name": "yix", + "url": "https://github.com/yx-laguna" + }, + "links": { + "repo": "https://github.com/yx-laguna/nexus-gateway", + "demo": "https://t.me/virtualshoppingbot", + "video": "https://youtu.be/dVV-3BPpvzE", + "share": "https://youtu.be/dVV-3BPpvzE", + "feedback": "https://github.com/Virtual-Protocol/acp-cli-demos/issues/new?title=Feedback%3A%20Varius%20AI%20Shopping%20Assistant&body=Which%20feedback%20prompt%20fits%3F%0A%0A-%20More%20merchant%20categories%20(flights%2C%20electronics%2C%20fashion)%3F%0A-%20Should%20the%20ACP%20bridge%20support%20batch%20link%20minting%20for%20comparison%20shopping%3F%0A-%20What%20would%20make%20the%20SKILL.md%20easier%20to%20adapt%20for%20a%20different%20affiliate%20network%3F" + }, + "primitives": ["acp"], + "visual": { + "kind": "youtube demo video", + "eyebrow": "telegram + acp v2", + "title": "affiliate link minting", + "posterUrl": "https://img.youtube.com/vi/dVV-3BPpvzE/maxresdefault.jpg", + "videoLabel": "Watch the demo on YouTube" + }, + "skills": [ + { + "name": "laguna-affiliate-link-via-acp", + "href": "https://github.com/yx-laguna/acp-cli-demos/tree/main/showcase/varius-ai-shopping-assistant/skills/laguna-affiliate-link-via-acp", + "sourcePath": "showcase/varius-ai-shopping-assistant/skills/laguna-affiliate-link-via-acp", + "summary": "Reusable ACP workflow to discover 1000+ merchants that offer USDC cashback, fund a USDC escrow job, and receive a tracked affiliate shortlink. Works for any merchant supported by Laguna Network.", + "install": "cp -R showcase/varius-ai-shopping-assistant/skills/laguna-affiliate-link-via-acp ~/.agents/skills/" + } + ], + "artifacts": [ + { + "label": "YouTube demo video", + "href": "https://youtu.be/dVV-3BPpvzE", + "kind": "video" + }, + { + "label": "Redacted result report", + "href": "https://github.com/yx-laguna/acp-cli-demos/blob/main/showcase/varius-ai-shopping-assistant/skills/laguna-affiliate-link-via-acp/examples/hotel-search/result-redacted.md", + "kind": "proof" + }, + { + "label": "Demo prompt", + "href": "https://github.com/yx-laguna/acp-cli-demos/blob/main/showcase/varius-ai-shopping-assistant/skills/laguna-affiliate-link-via-acp/examples/hotel-search/prompt.md", + "kind": "prompt" + }, + { + "label": "Skill source", + "href": "https://github.com/yx-laguna/acp-cli-demos/tree/main/showcase/varius-ai-shopping-assistant/skills/laguna-affiliate-link-via-acp", + "kind": "skill" + }, + { + "label": "Live bot", + "href": "https://t.me/virtualshoppingbot", + "kind": "demo" + } + ], + "feedbackPrompts": [ + "Which other merchant categories should the bot support (flights, electronics, fashion)?", + "Should the ACP bridge support batch link minting for comparison shopping?", + "What would make the SKILL.md easier to adapt for a different affiliate network?" + ], + "soul": { + "href": "https://github.com/yx-laguna/acp-cli-demos/blob/main/showcase/varius-ai-shopping-assistant/soul.md", + "summary": "Varius operates as a deal-finding assistant: it never books on the user's behalf, only delivers tracked links. It earns from the Laguna affiliate network; the 0.01 USDC ACP job cost is recovered via cashback." + } +} diff --git a/showcase/varius-ai-shopping-assistant/skills/laguna-affiliate-link-via-acp/SKILL.md b/showcase/varius-ai-shopping-assistant/skills/laguna-affiliate-link-via-acp/SKILL.md new file mode 100644 index 0000000..988f608 --- /dev/null +++ b/showcase/varius-ai-shopping-assistant/skills/laguna-affiliate-link-via-acp/SKILL.md @@ -0,0 +1,150 @@ +# Skill: laguna-affiliate-link-via-acp + +## When to use this skill + +Use this skill when an agent needs to mint a tracked affiliate shortlink for a specific merchant and user wallet, using the Laguna Network affiliate platform, mediated by an ACP v2 agent-to-agent job. + +**Use when:** +- You have a merchant the user wants to purchase from (hotel, flight, product retailer) +- You want to earn the user real USDC cashback on that purchase +- You need a tracked link — not a raw merchant URL + +**Do not use when:** +- You need to complete a purchase autonomously (this skill only delivers a link, not a booking) +- The merchant is not in the Laguna Network catalogue +- You do not have a user wallet address to attach the cashback to + +--- + +## Required inputs + +| Input | Source | Notes | +|---|---|---| +| `merchant_name` | User request or search result | e.g. `"Trip.com"`, `"Agoda"`, `"Lazada"` | +| `user_wallet_address` | User profile / onboarding | Base Mainnet EVM address | +| `acp_client` | Agent runtime | Initialised ACP v2 client with funded wallet | +| `laguna_provider_wallet` | Agent config | Wallet address of the ACPLagunaTranslator provider agent | + +--- + +## Preconditions + +1. ACP client wallet has ≥ 0.01 USDC on Base Mainnet (job budget). +2. The Laguna bridge provider agent (`ACPLagunaTranslator`) is registered and online in the Agent Registry. +3. The Laguna MCP is reachable at `agents.laguna.network/mcp`. + +--- + +## Step-by-step workflow + +### Step 1 — Discover the provider + +```ts +const agents = await acpClient.browseAgents("Laguna Affiliate"); +const provider = agents.find(a => a.walletAddress === LAGUNA_PROVIDER_WALLET); +const offering = provider.offerings.find(o => o.name === "mint_link"); +``` + +Fail if no matching provider is found. Log and surface error to the user. + +### Step 2 — Create and fund the job + +```ts +const job = await acpClient.createJobFromOffering(offering, { + userWallet: user_wallet_address, + merchantName: merchant_name, +}); +// Budget: 0.01 USDC. Set by provider; client funds it. +await job.fund(); +``` + +Record `job.id` for polling / event tracking. + +### Step 3 — Wait for delivery + +Listen for the `job.submitted` event via SocketTransport: + +```ts +acpClient.on("job.submitted", async (event) => { + if (event.jobId === job.id) { + const deliverable = event.deliverable; // affiliate shortlink URL + // proceed to Step 4 + } +}); +``` + +**Polling fallback:** if no event within 60 s, call `acpClient.hydrateSessions()` and check `job.status`. + +Timeout at 120 s. If job has not submitted, surface error and offer to retry. + +### Step 4 — Complete the job and return the link + +```ts +await job.complete(); +return deliverable; // the affiliate shortlink URL +``` + +The 0.01 USDC escrow is released to the provider. The user's wallet is registered for cashback tracking by Laguna. + +--- + +## Approval gates + +This skill performs two on-chain actions that require the agent to have pre-authorised funds: + +1. **Job creation + funding** — deducts 0.01 USDC from the agent's Base wallet. +2. **Job completion** — releases funds to the provider. + +No human approval is required per-link if the agent wallet has been pre-funded. Surface the 0.01 USDC cost to users during onboarding. + +--- + +## Stop conditions + +Stop and return an error without completing the job if: +- Provider agent not found in registry +- Job funding fails (insufficient balance) +- Deliverable not received within 120 s +- Deliverable URL is malformed or does not match expected shortlink domain + +--- + +## Evidence and redaction rules + +When logging or producing a result report: +- **Include:** job ID, provider wallet (truncated to first 6 + last 4 chars), merchant name, link domain (not full URL), completion timestamp +- **Redact:** full affiliate shortlink URL (contains user tracking token), user wallet address (truncate), any Laguna API keys or auth headers + +--- + +## Validation checklist + +- [ ] Provider discovered by wallet address, not by name only +- [ ] Job ID recorded before funding +- [ ] Deliverable is a valid HTTPS URL +- [ ] `job.complete()` called after receiving deliverable +- [ ] Error path surfaces a human-readable message (not a raw exception) + +--- + +## Output contract + +```ts +{ + success: boolean, + jobId: string, // ACP job ID + affiliateUrl: string, // tracked shortlink (deliver to user) + merchant: string, // canonical merchant name + cashbackRate: string, // e.g. "5%" (from Laguna merchant info) + timestamp: string, // ISO 8601 +} +``` + +On failure: +```ts +{ + success: false, + error: string, // human-readable reason + jobId?: string, // set if job was created before failure +} +``` diff --git a/showcase/varius-ai-shopping-assistant/skills/laguna-affiliate-link-via-acp/examples/hotel-search/README.md b/showcase/varius-ai-shopping-assistant/skills/laguna-affiliate-link-via-acp/examples/hotel-search/README.md new file mode 100644 index 0000000..cd85f72 --- /dev/null +++ b/showcase/varius-ai-shopping-assistant/skills/laguna-affiliate-link-via-acp/examples/hotel-search/README.md @@ -0,0 +1,23 @@ +# Example: Hotel Search (Penang) + +This example shows the `laguna-affiliate-link-via-acp` skill triggered via a natural-language hotel search request in Telegram. + +## What happens + +1. User sends a plain-English hotel request to @virtualshoppingbot on Telegram. +2. Varius extracts intent using Kimi K2 via Virtuals Agent Compute. +3. Varius returns 3 hotel recommendations. +4. User signals purchase intent ("I like option 1"). +5. Varius fires two parallel ACP v2 jobs on Base Mainnet — one for Trip.com, one for Agoda. +6. Each job is funded with 0.01 USDC escrow, delivered by the Laguna bridge provider agent, then completed. +7. Two tracked affiliate shortlinks arrive in the Telegram chat within ~30–90 seconds. +8. User can check `/dashboard` to see pending USDC cashback. + +## Files + +- `prompt.md` — the user messages that triggered this run +- `result-redacted.md` — full execution trace with sensitive data redacted + +## Demo video + +https://youtu.be/dVV-3BPpvzE diff --git a/showcase/varius-ai-shopping-assistant/skills/laguna-affiliate-link-via-acp/examples/hotel-search/prompt.md b/showcase/varius-ai-shopping-assistant/skills/laguna-affiliate-link-via-acp/examples/hotel-search/prompt.md new file mode 100644 index 0000000..4c10dde --- /dev/null +++ b/showcase/varius-ai-shopping-assistant/skills/laguna-affiliate-link-via-acp/examples/hotel-search/prompt.md @@ -0,0 +1,24 @@ +# Demo Prompt — Hotel Search + +This is the natural-language prompt used by the end user to trigger the skill. + +--- + +**Channel:** Telegram (@virtualshoppingbot) + +**User message:** +> I need a hotel in Penang this weekend, something nice near the beach + +**Follow-up (purchase intent signal):** +> I like option 1, let's go with it + +--- + +## What the agent does + +1. Extracts intent: `hotel_search`, location `Penang`, preference `beach` +2. Returns 3 recommendations via Agent Compute (Kimi K2) +3. Detects `purchase_ready: true` on the follow-up +4. Fires parallel ACP v2 jobs for Trip.com and Agoda affiliate link minting +5. Delivers both tracked shortlinks to the user in Telegram +6. User can check `/dashboard` to see pending USDC cashback diff --git a/showcase/varius-ai-shopping-assistant/skills/laguna-affiliate-link-via-acp/examples/hotel-search/result-redacted.md b/showcase/varius-ai-shopping-assistant/skills/laguna-affiliate-link-via-acp/examples/hotel-search/result-redacted.md new file mode 100644 index 0000000..4582355 --- /dev/null +++ b/showcase/varius-ai-shopping-assistant/skills/laguna-affiliate-link-via-acp/examples/hotel-search/result-redacted.md @@ -0,0 +1,104 @@ +# Result Report — Hotel Search (Redacted) + +**Skill:** laguna-affiliate-link-via-acp +**Example:** Hotel search via Telegram +**Date:** 2026-06-[REDACTED] +**Status:** Completed ✅ + +--- + +## Prompt + +> User: "I need a hotel in Penang this weekend, something nice near the beach" + +--- + +## Execution trace + +### 1. Intent extraction (Agent Compute — Kimi K2) + +Input: user message +Output: +```json +{ + "intent": "hotel_search", + "location": "Penang", + "timeframe": "this weekend", + "preference": "beach", + "purchase_ready": false +} +``` +Latency: ~1.1 s + +### 2. Merchant recommendations generated + +3 hotel options surfaced (names redacted to property category only): +- Beach resort, 4-star, Batu Ferringhi +- Beachfront international chain, 5-star +- Boutique hotel, city centre (included for contrast) + +### 3. User signals purchase intent + +> User: "I like option 1, let's go with it" + +Intent re-evaluated: `purchase_ready: true` + +### 4. ACP v2 job created (mint_link) + +``` +Job ID: [REDACTED] +Provider: 0x1a2b...9f0e (ACPLagunaTranslator) +Offering: mint_link +Budget: 0.01 USDC +Network: Base Mainnet +Job created at: [REDACTED TIMESTAMP] +Job funded at: [REDACTED TIMESTAMP] +``` + +### 5. Laguna MCP — search_merchants + +Query: `{ query: "beach resort Penang", geo: "MY" }` +Result: matched merchants — Trip.com (5% cashback), Agoda (4.5% cashback) +Both selected for parallel minting. + +### 6. Laguna MCP — mint_link (×2, parallel) + +``` +Merchant A: Trip.com + Shortlink: [REDACTED — contains user tracking token] + Cashback rate: 5% + Cookie duration: 30 days + +Merchant B: Agoda + Shortlink: [REDACTED — contains user tracking token] + Cashback rate: 4.5% + Cookie duration: 7 days +``` + +### 7. ACP jobs completed + +``` +Job A (Trip.com): submitted → completed +Job B (Agoda): submitted → completed +Total latency: ~38 s (from user intent signal to both links delivered) +``` + +0.01 USDC per job released to provider. User wallet [REDACTED] registered for cashback on both links. + +### 8. Dashboard check (/dashboard) + +``` +Pending: 0.42 USDC +Available: 1.85 USDC +Total conversions: 7 +``` + +--- + +## Redaction notes + +- Affiliate shortlink URLs redacted (contain user wallet tracking token) +- User wallet address truncated +- Job IDs redacted +- Timestamps generalised +- No API keys, auth headers, or private session data included diff --git a/showcase/varius-ai-shopping-assistant/soul.md b/showcase/varius-ai-shopping-assistant/soul.md new file mode 100644 index 0000000..881519d --- /dev/null +++ b/showcase/varius-ai-shopping-assistant/soul.md @@ -0,0 +1,31 @@ +# Varius — Public Agent Context + +## Role + +Varius is a deal-finding assistant that runs as a Telegram bot (@virtualshoppingbot). It helps users find merchants with affiliate cashback, mints tracked shortlinks via ACP, and surfaces real USDC earnings through a dashboard. + +## Operating boundaries + +- Varius **never books or purchases on the user's behalf** — it only delivers tracked affiliate links for the user to click themselves. +- Varius **never stores payment details** — cashback is tracked purely by EVM wallet address. +- Varius **only mints links when the user explicitly signals purchase intent** — it does not flood the conversation with links on first contact. +- Geo context (country) comes from the user's stored profile only — never inferred from LLM output — to prevent hallucination. + +## Collaboration style + +- Responds in plain conversational English; no crypto jargon exposed to the end user. +- Presents exactly 3 recommendations per query — no more, no less — to avoid overwhelming. +- Uses a single "recommended merchant" line before minting, so the user knows what's coming. +- Delivers both Trip.com and Agoda links for hotel searches in parallel (best coverage for SEA travel). + +## Economics + +- Each ACP v2 job costs 0.01 USDC from the Varius agent wallet (funded upfront). +- The 0.01 USDC is economically net-zero: Laguna's affiliate commissions refund it to the user over time via cashback. +- Varius earns nothing directly — value accrues to the user via USDC cashback on purchases. + +## What this agent is NOT + +- Not an autonomous buyer or travel agent. +- Not connected to any booking APIs — it mints affiliate links only. +- Not storing or transmitting private keys, card details, or user credentials of any kind.