Showcase: HoodFlow Agent API + lifecycle-aware routing on Robinhood Chain

showcase/hoodflow/README.md

@@ -0,0 +1,65 @@
+# HoodFlow
+
+HoodFlow is a self-custody Robinhood Chain market interface. Its public Agent API lets an agent read route-reviewed Stock Token markets and prepare a short-lived buy or sell preflight before handing the exact intent to the user's wallet. Its Virtuals adapter separately distinguishes lifecycle discovery from execution: bonding-stage markets use VIRTUAL as settlement, while graduated markets become executable only when a live liquid route returns a valid quote.
+
+This submission does not claim a live Virtuals ACP listing or autonomous signing. It publishes an inspectable provider manifest, market registry, and quote-preflight contract so reviewers can evaluate whether the bounded surface should become an ACP resource. HoodFlow never holds funds, requests private keys, or submits a transaction for the user.
+
+## Review the agent surface
+
+1. Open the [interactive agent workspace](https://hoodflow.app/?view=agents).
+2. Inspect the [public Agent API manifest](https://hoodflow.app/api/agents/hoodflow) for capabilities, safety boundaries, and endpoint contracts.
+3. Read the [execution-market registry](https://hoodflow.app/api/agents/markets) exposed to agents.
+4. Use the [Agent API guide](https://hoodflow.app/docs#agents) to prepare a bounded buy or sell preflight.
+5. Confirm that the result is indicative, expires after 75 seconds, and requires a fresh HoodFlow quote before the user signs.
+
+## Completed execution proof
+
+On 2026-07-22, a HoodFlow Agent API preflight prepared a 1 USDG INTC buy intent. HoodFlow carried that exact side, asset, amount, and slippage into a fresh quote; the user wallet then confirmed the router transaction. Robinhood Chain finalized the transaction successfully in block `16478330`.
+
+- Transaction: [`0x7c9d...03c3`](https://robinhoodchain.blockscout.com/tx/0x7c9d4dcea9c32b5df03283b010617084499d5ab29ca8a093c9f49a6e5c2303c3)
+- Machine-readable receipt: [Blockscout API](https://robinhoodchain.blockscout.com/api/v2/transactions/0x7c9d4dcea9c32b5df03283b010617084499d5ab29ca8a093c9f49a6e5c2303c3)
+- Decoded proof: [`proofs/executed-intc-buy-4663.json`](./proofs/executed-intc-buy-4663.json)
+- Input transfer: `1.0 USDG`
+- Output transfer: `0.00937386626109376 INTC`
+
+This records a completed user-wallet token trade after an Agent API preflight. It does not evidence an EconomyOS Agent Wallet or ACP job. The Agent API did not initiate, sign, or submit the transaction; the user wallet remained the signer. The receipt independently proves the trade, but the preceding offchain preflight is builder-attested and is not cryptographically bound to the transaction.
+
+## Reuse the preflight workflow
+
+The [`hoodflow-route-preflight` skill](./skills/hoodflow-route-preflight/SKILL.md) packages the public API workflow for another agent. It verifies the capability manifest and reviewed-market registry, requests a short-lived quote, checks the oracle/deviation/slippage/expiry fields, and returns the exact user-wallet handoff. Its stop conditions forbid wallet connection, token approval, signing, transaction submission, fabricated fallbacks, and ACP claims.
+
+Install after cloning this repository:
+
+```bash
+cp -R showcase/hoodflow/skills/hoodflow-route-preflight ~/.agents/skills/
+cp -R showcase/hoodflow/skills/hoodflow-route-preflight ~/.claude/skills/
+```
+
+## Media proof
+
+- [Commit-pinned 16:9 Showcase poster](https://raw.githubusercontent.com/dereliapps/acp-cli-demos/8245617/showcase/hoodflow/assets/poster.png)
+- [Watch the 30-second H.264 product tour](https://cdn.jsdelivr.net/gh/dereliapps/acp-cli-demos@b34a371c1a44f0d43416b0d83914cb1b2a2308b3/showcase/hoodflow/assets/demo.mp4)
+- [Commit-pinned source asset](https://raw.githubusercontent.com/dereliapps/acp-cli-demos/b34a371c1a44f0d43416b0d83914cb1b2a2308b3/showcase/hoodflow/assets/demo.mp4)
+
+## Review the community-market workflow
+
+1. Open [hoodflow.app](https://hoodflow.app) and enter the community-markets workspace.
+2. Select a listed market or import a Robinhood Chain token contract.
+3. Inspect the detected lifecycle state and choose an available settlement token.
+4. Refresh the quote. HoodFlow enables execution only when a live route returns an executable output.
+5. Connect a self-custody wallet to review the exact approval and swap transaction before signing.
+
+## Public proof
+
+- [Public Agent API manifest](https://hoodflow.app/api/agents/hoodflow)
+- [Agent API guide](https://hoodflow.app/docs#agents)
+- [Completed user-signed wallet/token transaction](https://robinhoodchain.blockscout.com/tx/0x7c9d4dcea9c32b5df03283b010617084499d5ab29ca8a093c9f49a6e5c2303c3)
+- [Integration review brief](https://github.com/dereliapps/hoodflow/blob/main/docs/VIRTUALS_REVIEW.md)
+- [Block-pinned route proof](https://github.com/dereliapps/hoodflow/blob/main/docs/proofs/virtuals-karma-route-4663.json)
+- [Release notes](https://github.com/dereliapps/hoodflow/releases/tag/v0.7.0)
+
+The proof records the Robinhood Chain ID, block number, token addresses, pair reserves, input amount, route, and computed output for a USDG to VIRTUAL to KARMA quote. It contains no wallet credentials or private infrastructure values.
+
+## Safety boundary
+
+HoodFlow never treats launchpad metadata as proof of liquidity. A discovered token remains watch-only until an executable onchain quote passes the route checks. Agent preflights are short-lived, never execution-bound, and cannot sign or submit a transaction. Users keep custody and approve each transaction in their own wallet; the recurring contracts remain clearly labeled pre-audit.

showcase/hoodflow/proofs/executed-intc-buy-4663.json

@@ -0,0 +1,66 @@
+{
+  "schemaVersion": 1,
+  "proofType": "completed_wallet_token_trade",
+  "network": {
+    "name": "Robinhood Chain Mainnet",
+    "chainId": 4663
+  },
+  "execution": {
+    "source": "HoodFlow public Agent API preflight handoff",
+    "signerPolicy": "user_wallet_only",
+    "side": "buy",
+    "asset": "INTC",
+    "settlementAsset": "USDG",
+    "maxSlippageBps": 50
+  },
+  "transaction": {
+    "hash": "0x7c9d4dcea9c32b5df03283b010617084499d5ab29ca8a093c9f49a6e5c2303c3",
+    "status": "success",
+    "statusCode": 1,
+    "blockNumber": 16478330,
+    "timestamp": "2026-07-22T13:56:55.000Z",
+    "from": "0xaE40947b604A5861bac432F7D0d52970B6c08a95",
+    "router": "0x8876789976dEcBfCbBbe364623C63652db8C0904",
+    "gasUsed": "182008",
+    "explorerUrl": "https://robinhoodchain.blockscout.com/tx/0x7c9d4dcea9c32b5df03283b010617084499d5ab29ca8a093c9f49a6e5c2303c3",
+    "receiptApiUrl": "https://robinhoodchain.blockscout.com/api/v2/transactions/0x7c9d4dcea9c32b5df03283b010617084499d5ab29ca8a093c9f49a6e5c2303c3"
+  },
+  "transfers": [
+    {
+      "direction": "input",
+      "token": "0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168",
+      "symbol": "USDG",
+      "from": "0xaE40947b604A5861bac432F7D0d52970B6c08a95",
+      "to": "0x8366a39CC670B4001A1121B8F6A443A643e40951",
+      "rawAmount": "1000000",
+      "decimals": 6,
+      "amount": "1.0"
+    },
+    {
+      "direction": "output",
+      "token": "0xc72b96e0E48ecd4DC75E1e45396e26300BC39681",
+      "symbol": "INTC",
+      "from": "0x8366a39CC670B4001A1121B8F6A443A643e40951",
+      "to": "0xaE40947b604A5861bac432F7D0d52970B6c08a95",
+      "rawAmount": "9373866261093760",
+      "decimals": 18,
+      "amount": "0.00937386626109376"
+    }
+  ],
+  "scope": {
+    "showcasePrimitives": [
+      "wallet",
+      "token"
+    ],
+    "economyOsAgentWalletUsed": false,
+    "acpJobUsed": false,
+    "agentPrepared": true,
+    "preflightEvidence": "builder_attestation_only",
+    "preflightCryptographicallyBoundToTransaction": false,
+    "agentSigned": false,
+    "agentSubmitted": false,
+    "userWalletConfirmed": true,
+    "liveAcpProviderClaimed": false,
+    "proofLimitations": "The receipt proves the completed wallet/token trade. It does not independently prove the preceding offchain preflight or an ACP job."
+  }
+}

showcase/hoodflow/showcase.json

@@ -0,0 +1,118 @@
+{
+  "slug": "hoodflow",
+  "title": "HoodFlow — Markets on Robinhood Chain",
+  "tagline": "Exposes reviewed Robinhood Chain markets and prepares bounded, self-custody quote preflights for users and agents",
+  "description": "HoodFlow is a self-custody market interface for Robinhood Chain. Its public Agent API exposes route-reviewed Stock Token markets and prepares short-lived buy or sell preflights with slippage and oracle-deviation guards; every execution is requoted and signed by the user. The Virtuals lifecycle adapter classifies bonding-stage launches, exposes their VIRTUAL settlement context, and links them to the official Virtuals market; HoodFlow enables embedded execution only after graduation when live DEX liquidity returns an executable quote. The API manifest and route proof expose the read and preflight surfaces, while a separate user-signed mainnet INTC receipt proves the wallet/token execution path, not an ACP job.",
+  "status": "public preflight API live · user-signed execution proof · ACP not published",
+  "topic": "agents",
+  "topics": [
+    "robinhood-chain",
+    "virtuals",
+    "agent-api",
+    "quote-preflight",
+    "token-routing",
+    "self-custody",
+    "wallet",
+    "defi"
+  ],
+  "hidden": false,
+  "builder": {
+    "name": "HoodFlow",
+    "url": "https://hoodflow.app"
+  },
+  "links": {
+    "repo": "https://github.com/dereliapps/hoodflow",
+    "demo": "https://hoodflow.app",
+    "share": "https://hoodflow.app/?view=agents",
+    "video": "https://cdn.jsdelivr.net/gh/dereliapps/acp-cli-demos@b34a371c1a44f0d43416b0d83914cb1b2a2308b3/showcase/hoodflow/assets/demo.mp4",
+    "feedback": "https://github.com/dereliapps/hoodflow/issues/new?title=Virtuals%20integration%20feedback"
+  },
+  "primitives": [
+    "wallet",
+    "token"
+  ],
+  "visual": {
+    "kind": "Reviewed route preflight + user-signed handoff",
+    "eyebrow": "agents · token routes · robinhood chain",
+    "title": "inspect the route before the user signs",
+    "posterUrl": "https://raw.githubusercontent.com/dereliapps/acp-cli-demos/591f38029fcaf4bf96ea88dd24786a26d6b29cb0/showcase/hoodflow/assets/poster.png",
+    "videoUrl": "https://cdn.jsdelivr.net/gh/dereliapps/acp-cli-demos@b34a371c1a44f0d43416b0d83914cb1b2a2308b3/showcase/hoodflow/assets/demo.mp4",
+    "videoLabel": "Watch the 0:30 demo"
+  },
+  "skills": [
+    {
+      "name": "hoodflow-route-preflight",
+      "href": "https://github.com/Virtual-Protocol/acp-cli-demos/tree/main/showcase/hoodflow/skills/hoodflow-route-preflight",
+      "sourcePath": "showcase/hoodflow/skills/hoodflow-route-preflight",
+      "summary": "Read HoodFlow's reviewed Robinhood Chain markets, request a short-lived oracle-checked quote preflight, validate its slippage floor and expiry, and return a self-custody handoff without signing or submitting a transaction.",
+      "install": "cp -R showcase/hoodflow/skills/hoodflow-route-preflight ~/.agents/skills/\ncp -R showcase/hoodflow/skills/hoodflow-route-preflight ~/.claude/skills/"
+    }
+  ],
+  "artifacts": [
+    {
+      "label": "Live HoodFlow interface",
+      "href": "https://hoodflow.app",
+      "kind": "demo"
+    },
+    {
+      "label": "Interactive HoodFlow agent workspace",
+      "href": "https://hoodflow.app/?view=agents",
+      "kind": "demo"
+    },
+    {
+      "label": "HoodFlow public Agent API manifest",
+      "href": "https://hoodflow.app/api/agents/hoodflow",
+      "kind": "api"
+    },
+    {
+      "label": "Agent API guide and request contract",
+      "href": "https://hoodflow.app/docs#agents",
+      "kind": "docs"
+    },
+    {
+      "label": "Reusable HoodFlow route-preflight skill",
+      "href": "https://github.com/Virtual-Protocol/acp-cli-demos/tree/main/showcase/hoodflow/skills/hoodflow-route-preflight",
+      "kind": "skill"
+    },
+    {
+      "label": "Commit-pinned 16:9 Showcase poster preview",
+      "href": "https://raw.githubusercontent.com/dereliapps/acp-cli-demos/8245617/showcase/hoodflow/assets/poster.png",
+      "kind": "image"
+    },
+    {
+      "label": "Watch the 30-second HoodFlow product tour",
+      "href": "https://cdn.jsdelivr.net/gh/dereliapps/acp-cli-demos@b34a371c1a44f0d43416b0d83914cb1b2a2308b3/showcase/hoodflow/assets/demo.mp4",
+      "kind": "video"
+    },
+    {
+      "label": "Virtuals integration review brief",
+      "href": "https://github.com/dereliapps/hoodflow/blob/main/docs/VIRTUALS_REVIEW.md",
+      "kind": "docs"
+    },
+    {
+      "label": "Successful user-signed mainnet trade: 1 USDG to 0.00937386626109376 INTC",
+      "href": "https://robinhoodchain.blockscout.com/tx/0x7c9d4dcea9c32b5df03283b010617084499d5ab29ca8a093c9f49a6e5c2303c3",
+      "kind": "proof"
+    },
+    {
+      "label": "Decoded user-signed INTC trade proof — not an ACP job",
+      "href": "https://github.com/dereliapps/hoodflow/blob/main/docs/proofs/executed-intc-buy-4663.json",
+      "kind": "proof"
+    },
+    {
+      "label": "Block-pinned USDG to VIRTUAL to KARMA route proof",
+      "href": "https://github.com/dereliapps/hoodflow/blob/main/docs/proofs/virtuals-karma-route-4663.json",
+      "kind": "proof"
+    },
+    {
+      "label": "HoodFlow 0.7.0 release",
+      "href": "https://github.com/dereliapps/hoodflow/releases/tag/v0.7.0",
+      "kind": "release"
+    }
+  ],
+  "feedbackPrompts": [
+    "Should HoodFlow's bounded quote-preflight surface be published as a Virtuals ACP resource?",
+    "Which execution-market fields would make the manifest easier for Virtuals agents to consume?",
+    "Which additional Virtuals lifecycle or mainnet route proofs should the adapter expose?"
+  ]
+}

showcase/hoodflow/skills/hoodflow-route-preflight/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: hoodflow-route-preflight
+description: Inspect HoodFlow's public Robinhood Chain market registry and prepare a short-lived, read-only Stock Token quote preflight. Use when an agent needs to verify a reviewed USDG route, oracle deviation, slippage floor, expiry, and user-wallet handoff without signing, submitting, or claiming an ACP job.
+---
+
+# HoodFlow Route Preflight
+
+Prepare an indicative HoodFlow route check from public HTTPS endpoints. Keep the workflow read-only: HoodFlow must requote the intent and the user must approve any wallet action.
+
+## Preconditions
+
+- Use `https://hoodflow.app` as the canonical origin.
+- Require an asset ticker, `buy` or `sell`, a positive decimal amount, and an optional slippage limit in basis points.
+- Treat buy amounts as USDG and sell amounts as Stock Token units.
+- Do not request a private key, seed phrase, wallet session, API key, or RPC credential.
+
+## Workflow
+
+1. Fetch `GET https://hoodflow.app/api/agents/hoodflow`.
+2. Require chain ID `4663`, `autonomousSubmission: false`, and `registryStatus: "not-published"`. Stop if the capability or safety boundary differs.
+3. Fetch `GET https://hoodflow.app/api/agents/markets` and select the exact ticker only when its status is `route-reviewed`.
+4. Normalize the request:
+   - uppercase the ticker;
+   - keep side to `buy` or `sell`;
+   - keep amount as a positive decimal string;
+   - allow at most 6 decimals and 100,000 units for buys;
+   - allow at most 18 decimals and 1,000,000 units for sells;
+   - require integer `slippageBps` from 1 to 500, defaulting to 50 only when the caller did not specify it.
+5. Submit the normalized JSON to `POST https://hoodflow.app/api/agents/quote` with `Content-Type: application/json`.
+6. Validate the response before presenting it:
+   - `status` is `indicative-preflight` and chain ID is `4663`;
+   - asset, side, and slippage match the request, and pay amount is numerically equal after decimal normalization;
+   - route protocol is Uniswap V3 or V4;
+   - the reference is live, `oraclePaused` is false, `updatedAt` is present and not in the future, and `deviationBps` does not exceed `maxDeviationBps`; treat `status: live` as the API's freshness verdict rather than inventing a separate market-calendar threshold;
+   - estimated and indicative-minimum outputs are positive;
+   - `dataExpiresAt` is still in the future;
+   - `executionBinding` is `none-requote-required`;
+   - `custody` is `self-custody` and `requiresUserSignature` is true;
+   - the handoff intent exactly matches the normalized request and the handoff URL uses HTTPS on the exact `hoodflow.app` host.
+7. Return the bounded preflight summary and `executionHandoff.marketUrl`. State that the number is indicative, expires quickly, and must be requoted before the user signs.
+
+Example request:
+
+```bash
+curl -sS https://hoodflow.app/api/agents/quote \
+  -H 'content-type: application/json' \
+  --data '{"asset":"AAPL","side":"buy","amount":"10","slippageBps":50}'
+```
+
+## Approval gates
+
+- Stop before connecting a wallet, granting token approval, signing, or submitting a transaction.
+- Continue into a value-moving flow only after the user separately approves the exact asset, side, amount, slippage, fresh quote, and destination chain.
+- Never describe this preflight as an ACP job, Agent Wallet transaction, executed order, or guaranteed price.
+
+## Stop conditions
+
+- Stop on an unsupported ticker or any response/request mismatch.
+- Stop when the quote is expired, the oracle is paused or stale, the deviation guard fails, or minimum output is zero.
+- On HTTP `422`, correct the caller's input; do not guess a replacement.
+- On HTTP `408`, report the timeout and retry only after a short delay.
+- On HTTP `429`, respect `Retry-After`; do not create a retry storm.
+- On HTTP `503`, report that no safe executable route is available; do not synthesize a quote or use cached output.
+
+## Output contract
+
+Return:
+
+- asset, side, pay amount and ticker;
+- estimated receive amount and indicative minimum;
+- route protocol plus both `fee` and `feeBps` exactly as returned, without reinterpreting the pool fee units;
+- oracle reference price and deviation;
+- expiry timestamp;
+- exact HoodFlow handoff URL;
+- the boundary: `preflight only; fresh quote and user signature required`.
+
+Do not include credentials, private infrastructure URLs, wallet secrets, or invented execution evidence.

showcase/hoodflow/skills/hoodflow-route-preflight/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "HoodFlow Route Preflight"
+  short_description: "Inspect a bounded HoodFlow token route"
+  default_prompt: "Use $hoodflow-route-preflight to inspect a reviewed HoodFlow market and prepare a non-custodial quote handoff."