Showcase: PipTrade Agent

showcase/pip-conversational-trader/README.md

@@ -0,0 +1,41 @@
+# PipTrade Agent
+
+PipTrade Agent gives you two ways to trade on the same self-custody wallet. In chat you say it in plain english and Pip does it. On the /rh terminal you work the desk with real order types. Both keep your keys, both settle private by default, and $PIP is a Virtuals token traded through the Virtuals bonding curve.
+
+## In chat, at /app
+
+You type a trade the way you would say it, and Pip reads the intent, shows a live quote, and executes on your own wallet.
+
+- Swap, in plain english, with a live quote before anything signs (price impact, minimum received, route, estimated time).
+- Send, privately, so the destination is not directly linked to your wallet.
+- Price and balance, asked and answered in the same thread.
+- Token safety, a GO, CAUTION, or BLOCK read on a token before you trade it.
+- Price alerts, set in words, like alert when ETH hits 4000.
+- Deposit from another chain, funded into your wallet, refund safe.
+- Referral, your own code and link, so you can bring others in.
+
+## At the desk, on /rh
+
+A full Robinhood Chain terminal on the same wallet.
+
+- Trade any listed Robinhood Chain token, with a honeypot and sell guard so you are not trapped in something you cannot exit.
+- Quote transparency on every trade, with a safety badge on the token.
+- Order types, market, limit, TWAP, and stop, run by a keeper so they fire while you are away.
+- Private send, so a transfer is not directly linked back to you.
+
+## How it keeps you safe
+
+- You keep your keys. Pip never signs for you, every trade is signed in your own wallet.
+- Every trade is safety checked, and a high risk token is gated before you can proceed.
+- Quotes are shown in full before execution, and nothing moves until you confirm.
+
+## What is in this entry
+
+- examples/chat-to-trade-readback.md, a plain-english intent taken all the way to a settled on-chain transaction.
+- examples/private-by-default.md, an honest account of what private by default hides and what it does not.
+- examples/command-surface.md, every instruction in chat and every order type on the terminal.
+- soul.md, the public agent context and boundaries.
+
+## Try it
+
+Open https://piptradedex.xyz/app for chat, or https://piptradedex.xyz/rh for the terminal.

showcase/pip-conversational-trader/examples/chat-to-trade-readback.md

@@ -0,0 +1,43 @@
+# Chat to trade readback
+
+One worked example of the conversational execution flow, a plain-english instruction taken to a settled on-chain transaction. This shows the intent, the quote, and the on-chain result for that single trade. Nothing signs until the user confirms, and the trade runs on the user's own wallet.
+
+## Input
+
+```
+buy 2 usd of PIP
+```
+
+## What Pip reads
+
+```
+side    buy
+token   PIP
+budget  2 usd
+chain   Robinhood Chain
+```
+
+## Live quote shown before signing
+
+```
+route            USDG to VIRTUAL to PIP
+spend            2.00 USDG
+minimum received PIP, floored at the shown slippage
+safety           GO, token passed the pre-trade safety read
+you keep         your keys, this signs in your own wallet
+```
+
+## Settled on-chain
+
+```
+status   success
+chain    Robinhood Chain, id 4663
+tx       0x740e18daf3cd9d8296ebf8fe76287196bbfa7b022ba6691f8274906c72756ea1
+result   PIP delivered to the user's own wallet, spend bounded to the stated 2 usd
+```
+
+Explorer: https://robinhoodchain.blockscout.com/tx/0x740e18daf3cd9d8296ebf8fe76287196bbfa7b022ba6691f8274906c72756ea1
+
+## Why it matters for a buyer agent
+
+The intent, the quote shape, and the settled result are all legible. An agent can hand Pip a trade in words, read a full quote before committing, and verify the outcome on-chain, while the user keeps custody the whole way through.

showcase/pip-conversational-trader/examples/command-surface.md

@@ -0,0 +1,57 @@
+# Command surface
+
+Everything PipTrade Agent can do, across chat and the terminal. Pip reads the intent, asks when something is unclear, and never invents a token, a side, or an amount you did not state.
+
+## In chat, at /app
+
+### Trade
+
+```
+buy 10 usd of PIP
+sell half my PIP
+swap 2 usdc on base to sol and send it over
+ape 5 usd into VIRTUAL
+```
+
+### Move
+
+```
+send 3 usdc to 0x... privately
+withdraw 0.01 eth to 0x...
+deposit 20 usdc from arbitrum
+```
+
+### Ask
+
+```
+price of PIP
+what is my balance
+is this token safe 0x...
+```
+
+### Watch and grow
+
+```
+alert when ETH hits 4000
+alert me if PIP drops 20 percent
+give me my referral link
+```
+
+## At the desk, on /rh
+
+- Trade any listed Robinhood Chain token, with a honeypot and sell guard.
+- Market order, fill now at the shown quote.
+- Limit order, fill only at your price or better.
+- TWAP order, spread a size over time.
+- Stop order, protect a position.
+- Private send, so the transfer is not directly linked back to you.
+- A safety badge and full quote on every trade.
+
+## Rules Pip follows everywhere
+
+- It shows a full quote before anything signs.
+- It runs a token safety read and gates a high risk token.
+- It signs in your own wallet, and never for you.
+- It settles private by default, breaking the on-chain link between your wallet and the destination.
+
+Chat at https://piptradedex.xyz/app, terminal at https://piptradedex.xyz/rh.

showcase/pip-conversational-trader/examples/private-by-default.md

@@ -0,0 +1,56 @@
+# Private by default, stated honestly
+
+Pip settles trades and sends private by default. This page shows three real settlements the operator made, with the on-chain links, and says exactly what the privacy does and does not mean so no one reads more into it than is true.
+
+## Three real private settlements
+
+### Swap A, base to base
+
+- Direction: 30 USDC to 0.0155305 ETH
+- Private: yes
+- Done: 2026-07-21 19:09 UTC
+- Result: two on-chain legs, and the receive is not directly linked to the send.
+
+There is a send leg where funds leave the user wallet:
+
+https://basescan.org/tx/0xaf00110622fa7ff93b9cb2c7ef2655c775d95814b84e1a2c01bea4ef0410377d
+
+And a private receive leg where the funds arrive at the user wallet 0xbbd9aCE37cc8AF0C11Fd050b01a95Ae2d9e8D9f0 from a different counterparty 0x2cff890f0378a11913b6129b2e97417a2c302680:
+
+https://basescan.org/tx/0x2821db35ab0f66ed898a10a8ce5c28f12994cedc3edbb2163d86d9ad217d62ee
+
+Because the receive arrives from a different counterparty than the one the send paid, an observer cannot trivially connect the funds that left the wallet to the funds that arrived. Both transactions are confirmed successful on Base.
+
+### Swap B, cross-chain base to sol
+
+- Direction: 0.000598 ETH to 0.0146482 SOL
+- Private: yes
+- Done: 2026-07-22 09:08 UTC
+- Settled to the in-app Solana wallet C1zCrNGXNc92TmY6f9NWUUaKZjoAbPk9QKn1LHbmN6k4
+
+Crossing to Solana further breaks the link, because the destination sits on a different chain than the funds that were spent on Base.
+
+### Swap C, base to base
+
+- Direction: 0.00011957 ETH to 0.2259 USDC
+- Private: yes
+- Settled to the in-app base wallet
+
+## What is hidden
+
+- The route and the counterparty link. An observer looking at the chain cannot trivially connect the funds that left your wallet to where they arrived, because the receive comes from a different counterparty, and in the cross-chain case it lands on a different chain.
+- This applies to swaps and sends by default, not as an extra step you have to remember.
+
+## What is not hidden
+
+- This is unlinkability by construction, not a zero knowledge proof. There is no cryptographic proof of a hidden statement here, only a break in the direct on-chain link.
+- It does not promise anonymity against every possible analysis. A determined analyst with side information can still infer the connection.
+- It hides nothing from you. You keep your keys the whole way through, and you see the full quote, the route, and the result.
+
+## Why we frame it this way
+
+Overclaiming privacy is how users get hurt. Pip states the boundary plainly, unlinkability and not zero knowledge, so a person or an agent acting for a person can decide with accurate expectations.
+
+## Verify
+
+Try a swap or a send at https://piptradedex.xyz/app and read the quote and settlement for yourself, then check the transactions above on Base.

showcase/pip-conversational-trader/showcase.json

@@ -0,0 +1,99 @@
+{
+  "slug": "pip-conversational-trader",
+  "title": "PipTrade Agent",
+  "tagline": "Trade by chat or work the desk, private by default, on a wallet where you keep your keys",
+  "description": "PipTrade Agent is a conversational trading agent in the Virtuals ecosystem. You type a trade in plain english and it quotes, safety checks, and settles it private by default on your own wallet where you keep your keys, and $PIP is a Virtuals token traded through the Virtuals bonding curve. The entry includes on-chain proof of real private settlements, a callable skill, and a public reads helper.",
+  "status": "live product, conversational trading in chat and a full Robinhood Chain terminal, private by default, you keep your keys",
+  "topic": "commerce",
+  "topics": [
+    "commerce",
+    "agent",
+    "conversational",
+    "trading",
+    "swap",
+    "terminal",
+    "limit-orders",
+    "twap",
+    "alerts",
+    "private",
+    "self-custody",
+    "token-safety",
+    "virtuals",
+    "pip",
+    "base",
+    "robinhood-chain"
+  ],
+  "hidden": false,
+  "builder": {
+    "name": "PipTradeDex",
+    "url": "https://piptradedex.xyz"
+  },
+  "links": {
+    "repo": "https://github.com/codedforum/acp-cli-demos/tree/pip-conversational-trader/showcase/pip-conversational-trader",
+    "demo": "https://github.com/codedforum/acp-cli-demos/blob/pip-conversational-trader/showcase/pip-conversational-trader/examples/chat-to-trade-readback.md",
+    "share": "https://piptradedex.xyz/app",
+    "video": "https://x.com/PipTradeDex/status/2078716840197378351",
+    "feedback": "https://github.com/Virtual-Protocol/acp-cli-demos/issues/new?title=Feedback%3A%20PipTrade%20Agent&body=Which%20prompt%20fits%3F%0A%0A-%20The%20plain-english%20quote%20then%20execute%20flow%20is%20useful%0A-%20The%20private%20by%20default%20settlement%20needs%20clearer%20proof%0A-%20I%20want%20a%20callable%20Pip%20quote%20or%20safety%20skill%20next%0A%0ANotes%3A%0A"
+  },
+  "primitives": [
+    "wallet",
+    "token"
+  ],
+  "visual": {
+    "kind": "chat to trade readback with live on-chain proof, plus a full terminal",
+    "eyebrow": "virtuals, conversational, terminal, private, keep your keys",
+    "title": "type to trade",
+    "videoLabel": "Watch the private trading demo on X",
+    "posterUrl": "https://raw.githubusercontent.com/codedforum/acp-cli-demos/pip-conversational-trader/showcase/pip-conversational-trader/assets/poster.png"
+  },
+  "skills": [
+    {
+      "name": "pip-trade-agent",
+      "href": "https://github.com/codedforum/acp-cli-demos/tree/pip-conversational-trader/showcase/pip-conversational-trader/skills/pip-trade-agent",
+      "sourcePath": "showcase/pip-conversational-trader/skills/pip-trade-agent",
+      "summary": "Hand a trade to PipTrade Agent in plain english, read the live quote with price impact and route, respect the GO CAUTION BLOCK token safety gate, and confirm a self-custody settlement that is private by default. Buyer-side, approval-gated, never signs for the user.",
+      "install": "cp -R showcase/pip-conversational-trader/skills/pip-trade-agent ~/.agents/skills/\ncp -R showcase/pip-conversational-trader/skills/pip-trade-agent ~/.claude/skills/"
+    }
+  ],
+  "artifacts": [
+    {
+      "label": "Chat to trade readback, plain-english intent to live quote to settled on-chain tx",
+      "href": "https://github.com/codedforum/acp-cli-demos/blob/pip-conversational-trader/showcase/pip-conversational-trader/examples/chat-to-trade-readback.md",
+      "kind": "proof"
+    },
+    {
+      "label": "Private by default settlement, what is hidden and what is not, stated honestly",
+      "href": "https://github.com/codedforum/acp-cli-demos/blob/pip-conversational-trader/showcase/pip-conversational-trader/examples/private-by-default.md",
+      "kind": "proof"
+    },
+    {
+      "label": "Command surface, every plain-english instruction in chat and every terminal order type",
+      "href": "https://github.com/codedforum/acp-cli-demos/blob/pip-conversational-trader/showcase/pip-conversational-trader/examples/command-surface.md",
+      "kind": "docs"
+    },
+    {
+      "label": "PipTrade Agent package README",
+      "href": "https://github.com/codedforum/acp-cli-demos/blob/pip-conversational-trader/showcase/pip-conversational-trader/README.md",
+      "kind": "docs"
+    },
+    {
+      "label": "pip-reads helper, a dependency-free script that calls the public read endpoints for prices, markets, tokens, and stats",
+      "href": "https://github.com/codedforum/acp-cli-demos/blob/pip-conversational-trader/showcase/pip-conversational-trader/tools/pip-reads.mjs",
+      "kind": "tool"
+    },
+    {
+      "label": "Type to trade demo video on X",
+      "href": "https://x.com/PipTradeDex/status/2078716840197378351",
+      "kind": "video"
+    }
+  ],
+  "soul": {
+    "href": "https://github.com/codedforum/acp-cli-demos/blob/pip-conversational-trader/showcase/pip-conversational-trader/soul.md",
+    "summary": "Public agent context for PipTrade Agent, a conversational trader and a full terminal that keep your keys, settle private by default, and never sign without the user."
+  },
+  "feedbackPrompts": [
+    "Would an agent hand a trade to PipTrade Agent in plain english if it returns a live quote with price impact, minimum received, route, and a token safety read before anything signs?",
+    "Which buyer search terms should rank first for PipTrade Agent: conversational trading, private swap, keep your keys, limit and TWAP orders, token safety, or Virtuals trading?",
+    "Should the next callable PipTrade skill expose a quote, a token safety check, or a full private swap as a native buyer job?"
+  ]
+}

showcase/pip-conversational-trader/skills/pip-trade-agent/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: pip-trade-agent
+description: Hand a trade to PipTrade Agent in plain english, read the live quote, respect the token safety gate, and confirm a self-custody settlement that is private by default. Buyer-side, approval-gated, keeps the user in custody.
+version: 1.0.0
+license: MIT
+---
+
+# Pip Trade Agent
+
+Use this skill when a buyer agent wants to execute a token trade for a user through PipTrade Agent instead of building routing, quoting, and token safety from scratch. The skill is buyer-side, approval-gated, and custody-preserving. It never signs for the user and never invents an intent the user did not state.
+
+## When To Use
+
+- A user asked, in words, to buy, sell, swap, or send a token.
+- The buyer agent wants a live quote with price impact, minimum received, and route before committing.
+- The trade should be gated by a token safety read (GO, CAUTION, or BLOCK).
+- The user must keep their keys and sign in their own wallet.
+- Settlement should be private by default, breaking the on-chain link between the wallet and the destination.
+
+## When NOT To Use
+
+- Do not use it to sign or move funds without the user in the loop.
+- Do not use it to invent a token, a side, or an amount the user did not state.
+- Do not use it to send funds to an address the user did not give.
+- Do not use it to skip the token safety read on a token about to be traded.
+- Do not use it to claim privacy stronger than unlinkability by construction, which is not a zero knowledge proof.
+
+## Inputs
+
+- One trade intent in plain english, for example buy 10 usd of PIP, or swap 2 usdc on base to sol and send it over.
+- The chain context if the user named one, otherwise let Pip infer from the token.
+- A per-trade spend cap and an allowlist of tokens the agent may act on.
+- The user approval state for anything that signs.
+
+## Outputs
+
+- A parsed intent, side, token, and amount, echoed back for confirmation.
+- A live quote, price impact, minimum received, route, and estimated time.
+- A token safety verdict, GO, CAUTION, or BLOCK.
+- A settled transaction reference on success, delivered to the user own wallet.
+
+## Approval Gates
+
+The user, or the operator acting for the user, must approve:
+
+1. the parsed intent before any quote is treated as final,
+2. any token that returns CAUTION,
+3. any trade above the per-trade spend cap,
+4. the signature itself, which always happens in the user own wallet.
+
+If any approval is missing, stop and hand control back to the user. A BLOCK verdict is a hard stop, never trade through it.
+
+## Workflow
+
+1. Read the user words and map them to a single intent, side, token, amount, and destination if a send. If anything is unclear, ask one short question, never guess.
+2. Confirm the token is on the agent allowlist and the amount is within the per-trade cap.
+3. Request a quote and a token safety read. Show price impact, minimum received, route, estimated time, and the GO CAUTION BLOCK verdict.
+4. On BLOCK, stop. On CAUTION, get explicit user approval. On GO, proceed.
+5. Present the full quote to the user and let the user sign in their own wallet. The agent never signs.
+6. On success, return the settled transaction reference. Settlement is private by default, so the destination is not directly linked to the source.
+
+## Interface
+
+PipTrade Agent runs at https://piptradedex.xyz/app for chat and https://piptradedex.xyz/rh for the terminal. On the terminal the same intent maps to a market, limit, TWAP, or stop order, run by a keeper, on any listed Robinhood Chain token, with the same safety gate and self-custody signing. $PIP is a Virtuals token traded through the Virtuals bonding curve.
+
+## Endpoints
+
+Read only, public, callable by any agent today at https://piptradedex.xyz:
+
+- GET /api/prices, live token prices.
+- GET /api/markets, market list with 24h change and volume.
+- GET /api/tokens, the tradeable token registry with decimals and logos.
+- GET /api/pip/stats, $PIP token stats.
+
+At /app, intent based, signed in with the user own wallet. The agent shapes the intent, the user signs, and nothing here signs on the agent behalf:
+
+- POST /api/quote, the unified intent quote and swap. One instruction moves value across every listed chain and token, private by default, so the on-chain link between the wallet and the destination is broken. A cross-chain move like swap 2 usdc on base to sol and send it over is a single intent.
+- GET /api/wallets and GET /api/holdings, balances for the signed-in wallet.
+- The /app chat drives the rest on the same signed-in wallet, a GO CAUTION BLOCK token safety read before any trade, deposit from another chain by intent, price alerts in plain english, and a referral link.
+
+At /rh, the Robinhood Chain terminal on the same wallet:
+
+- GET /api/rh/tokens, the listed token universe.
+- POST /api/rh/quote and POST /api/rh/swap, a market trade on any listed token with a safety badge.
+- Market, limit, TWAP, and stop orders, run by a keeper.
+- POST /api/rh/withdraw, a private send.
+
+There is no anonymous trade endpoint. Trading always requires the user signed in with their own keys, which is the point. An agent uses the public reads freely and shapes the signed-in intents through the user at /app.
+
+## Safety Invariants
+
+- The user keeps their keys. The agent and the service never hold them.
+- Every trade shows a full quote before it signs.
+- Every token is safety checked, and a high risk token is gated.
+- Privacy is unlinkability by construction, stated plainly, never oversold.