diff --git a/showcase/hoodflow/README.md b/showcase/hoodflow/README.md new file mode 100644 index 0000000..0b02791 --- /dev/null +++ b/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. diff --git a/showcase/hoodflow/assets/demo.mp4 b/showcase/hoodflow/assets/demo.mp4 new file mode 100644 index 0000000..4ae45cd Binary files /dev/null and b/showcase/hoodflow/assets/demo.mp4 differ diff --git a/showcase/hoodflow/assets/poster.png b/showcase/hoodflow/assets/poster.png new file mode 100644 index 0000000..1b099a6 Binary files /dev/null and b/showcase/hoodflow/assets/poster.png differ diff --git a/showcase/hoodflow/proofs/executed-intc-buy-4663.json b/showcase/hoodflow/proofs/executed-intc-buy-4663.json new file mode 100644 index 0000000..f1ec892 --- /dev/null +++ b/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." + } +} diff --git a/showcase/hoodflow/showcase.json b/showcase/hoodflow/showcase.json new file mode 100644 index 0000000..8842329 --- /dev/null +++ b/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?" + ] +} diff --git a/showcase/hoodflow/skills/hoodflow-route-preflight/SKILL.md b/showcase/hoodflow/skills/hoodflow-route-preflight/SKILL.md new file mode 100644 index 0000000..2e8bc8b --- /dev/null +++ b/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. diff --git a/showcase/hoodflow/skills/hoodflow-route-preflight/agents/openai.yaml b/showcase/hoodflow/skills/hoodflow-route-preflight/agents/openai.yaml new file mode 100644 index 0000000..2681b78 --- /dev/null +++ b/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."