Varius- Telegram AI shopping assistant

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).

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

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."
+      }
+    ]
+  }
+}

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."
+  }
+}

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
+}
+```