{"id":"63347e55-f48a-47ef-bd59-12d259c4ebf6","entityType":"agent","slug":"clawhub-powerloom-bot-powerloom-bds-univ3","name":"πŸ¦„ Powerloom Uniswap V3 timeseries data","canonicalUrl":"https://www.xpersona.co/agent/clawhub-powerloom-bot-powerloom-bds-univ3","canonicalPath":"/agent/clawhub-powerloom-bot-powerloom-bds-univ3","generatedAt":"2026-10-11T10:52:26.416Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T08:17:55.695Z","emptyReason":null},"description":"Autonomous Uniswap V3 monitoring on consensus-backed data with onchain provenance. Every data point is finalized on-chain by Powerloom's DSV network and inde...","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.1K downloads reported by the source. Last updated 10/11/2026.","installCommand":"clawhub skill install s176mrxdfpcbst221tw1g4jkf585fvh0:powerloom-bds-univ3","sourceUrl":"https://clawhub.ai/powerloom-bot/powerloom-bds-univ3","homepage":"https://clawhub.ai/powerloom-bot/skills/powerloom-bds-univ3","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/powerloom-bot/powerloom-bds-univ3","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/powerloom-bot/skills/powerloom-bds-univ3","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":61,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"πŸ¦„ Powerloom Uniswap V3 timeseries data technical dossier on Xpersona with agent coverage, OPENCLEW support, and live trust metadata."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-11T08:17:55.695Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T08:17:55.695Z","emptyReason":null},"stars":null,"forks":null,"downloads":1115,"packageName":null,"latestVersion":"0.2.6","tractionLabel":"1.1K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T08:17:55.626Z","emptyReason":null},"lastUpdatedAt":"2026-10-11T08:17:55.695Z","lastCrawledAt":"2026-10-11T08:17:55.626Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-12T08:17:55.626Z","lastVerifiedAt":null,"highlights":[{"version":"0.2.6","createdAt":"2026-05-14T17:55:55.949Z","changelog":"powerloom-bds-univ3 v0.2.6 - Version bump to 0.2.6; no file changes detected. - Clarify and correct 1 credit = 7200 epochs worth of polled data - All features, onboarding flows, and environment settings remain unchanged from the previous release.","fileCount":34,"zipByteSize":53957},{"version":"0.2.5","createdAt":"2026-05-12T03:24:23.263Z","changelog":"### Summary: Simplified onboarding and documentation for the free Uniswap V3 monitoring service. - Streamlined SKILL.md description and install instructions for clarity and brevity. - Updated free onboarding flow: users now obtain an API key instantly via https://bds-metering.powerloom.io/metering (no CLI or wallet required). - Emphasized the free 2-credit API key and how to acquire it with just an email and agent name. - Removed verbose step-by-step instructions and references to lesser-used flows. - Clarified trigger phrases and reduced description complexity for easier understanding.","fileCount":33,"zipByteSize":52275},{"version":"0.2.4","createdAt":"2026-05-10T08:24:57.915Z","changelog":"- Version bump to 0.2.4; no file changes detected. - Updated documentation to clarify confirmation options for wallet-funded scripts: - Emphasizes using --yes for OpenClaw/invocation and environment variables only for CI. - No changes to functionality or codebase.","fileCount":33,"zipByteSize":52342},{"version":"0.2.3","createdAt":"2026-05-10T07:24:19.473Z","changelog":"- Added scripts/lib/confirm-spend.mjs to implement broadcast protection for spend actions. - scripts/signup-pay.mjs and scripts/credits-topup.mjs now require explicit confirmation (via prompt, --yes, or environment variable) before broadcasting on-chain transactions. - Both scripts now support a --dry-run mode to print a summary and exit without sending a transaction. - Enhanced safety for wallet-funded flows to prevent accidental transactions.","fileCount":33,"zipByteSize":51980},{"version":"0.2.2","createdAt":"2026-05-09T16:59:41.551Z","changelog":"Version 0.2.2 - Version bump from 0.2.1 to 0.2.2. - enhance signup-pay one-shot instructions to emphasize required inputs for Telegram alerts and clarify cron job creation steps","fileCount":32,"zipByteSize":49387},{"version":"0.2.1","createdAt":"2026-05-09T16:43:13.097Z","changelog":"- Patch release: version bump from 0.2 to 0.2.1. - No code or content changes detected. - Maintains feature set and onboarding flows as in the previous version.","fileCount":32,"zipByteSize":48389},{"version":"0.1.1","createdAt":"2026-05-09T16:29:00.846Z","changelog":"Version 0.2 β€” Adds support for free onboarding via API key only (no wallet required). - Introduced a free onboarding path: run bds-agent signup to obtain a 2-credit free API key; set only POWERLOOM_API_KEY to start monitoring with no wallet required. - Existing wallet-funded onboarding remains; scripts for autonomous on-chain payments now clearly optional and separated from the default flow. - Metadata and environment variable requirements updated: only POWERLOOM_API_KEY is mandatory by default, wallet credentials are optional and needed only for pay/top-up scripts. - Added reference file references/09-openclaw-one-shot-free-key.md describing the free onboarding flow. - Documentation clarified and streamlined to highlight the two onboarding options (free and wallet-funded).","fileCount":32,"zipByteSize":47520},{"version":"0.1.0","createdAt":"2026-05-01T16:53:40.227Z","changelog":"### v0.1.0 β€” Breaking update: snapshot-only tooling, clearer usage - All recipes and scripts refactored to use only **snapshot/BATCH (bounded)** MCP calls; streaming tools (`bds_mpp_stream_*`) are no longer invoked. - Common task table and usage instructions updated to clarify bounded snapshot vs. streaming distinction. - Default tool options and examples reflect snapshot-focused flows (supporting reliable agent/cron operation). - Documentation updated for plan selection and metering environment variables. - Version number format normalized (0.1).","fileCount":31,"zipByteSize":43629}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s176mrxdfpcbst221tw1g4jkf585fvh0:powerloom-bds-univ3","setupComplexity":"low","setupSteps":["Install using `clawhub skill install s176mrxdfpcbst221tw1g4jkf585fvh0:powerloom-bds-univ3` in an isolated environment before connecting it to live workloads.","No published capability contract is available yet, so validate auth and request/response behavior manually.","Review the upstream CLAWHUB listing at https://clawhub.ai/powerloom-bot/powerloom-bds-univ3 before using production credentials."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-powerloom-bot-powerloom-bds-univ3/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-powerloom-bot-powerloom-bds-univ3/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-powerloom-bot-powerloom-bds-univ3/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-powerloom-bot-powerloom-bds-univ3/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-powerloom-bot-powerloom-bds-univ3/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-powerloom-bot-powerloom-bds-univ3/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-11T10:52:26.413Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-powerloom-bot-powerloom-bds-univ3/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-powerloom-bot-powerloom-bds-univ3/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-powerloom-bot-powerloom-bds-univ3/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-powerloom-bot-powerloom-bds-univ3/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-11T08:17:55.695Z","emptyReason":null},"readme":"Skill: πŸ¦„ Powerloom Uniswap V3 timeseries data\n\nOwner: powerloom-bot\n\nSummary: Autonomous Uniswap V3 monitoring on consensus-backed data with onchain provenance. Every data point is finalized on-chain by Powerloom's DSV network and inde...\n\nTags: latest:0.2.6\n\nVersion history:\n\nv0.2.6 | 2026-05-14T17:55:55.949Z | user\n\npowerloom-bds-univ3 v0.2.6\n\n- Version bump to 0.2.6; no file changes detected.\n- Clarify and correct 1 credit = 7200 epochs worth of polled data\n- All features, onboarding flows, and environment settings remain unchanged from the previous release.\n\nv0.2.5 | 2026-05-12T03:24:23.263Z | user\n\n### Summary: Simplified onboarding and documentation for the free Uniswap V3 monitoring service.\n\n- Streamlined SKILL.md description and install instructions for clarity and brevity.\n- Updated free onboarding flow: users now obtain an API key instantly via https://bds-metering.powerloom.io/metering (no CLI or wallet required).\n- Emphasized the free 2-credit API key and how to acquire it with just an email and agent name.\n- Removed verbose step-by-step instructions and references to lesser-used flows.\n- Clarified trigger phrases and reduced description complexity for easier understanding.\n\nv0.2.4 | 2026-05-10T08:24:57.915Z | user\n\n- Version bump to 0.2.4; no file changes detected.\n- Updated documentation to clarify confirmation options for wallet-funded scripts:\n - Emphasizes using --yes for OpenClaw/invocation and environment variables only for CI.\n- No changes to functionality or codebase.\n\nv0.2.3 | 2026-05-10T07:24:19.473Z | user\n\n- Added scripts/lib/confirm-spend.mjs to implement broadcast protection for spend actions.\n- scripts/signup-pay.mjs and scripts/credits-topup.mjs now require explicit confirmation (via prompt, --yes, or environment variable) before broadcasting on-chain transactions.\n- Both scripts now support a --dry-run mode to print a summary and exit without sending a transaction.\n- Enhanced safety for wallet-funded flows to prevent accidental transactions.\n\nv0.2.2 | 2026-05-09T16:59:41.551Z | user\n\nVersion 0.2.2\n\n- Version bump from 0.2.1 to 0.2.2.\n- enhance signup-pay one-shot instructions to emphasize required inputs for Telegram alerts and clarify cron job creation steps\n\nv0.2.1 | 2026-05-09T16:43:13.097Z | user\n\n- Patch release: version bump from 0.2 to 0.2.1.\n- No code or content changes detected.\n- Maintains feature set and onboarding flows as in the previous version.\n\nv0.1.1 | 2026-05-09T16:29:00.846Z | user\n\nVersion 0.2 β€” Adds support for free onboarding via API key only (no wallet required).\n\n- Introduced a free onboarding path: run bds-agent signup to obtain a 2-credit free API key; set only POWERLOOM_API_KEY to start monitoring with no wallet required.\n- Existing wallet-funded onboarding remains; scripts for autonomous on-chain payments now clearly optional and separated from the default flow.\n- Metadata and environment variable requirements updated: only POWERLOOM_API_KEY is mandatory by default, wallet credentials are optional and needed only for pay/top-up scripts.\n- Added reference file references/09-openclaw-one-shot-free-key.md describing the free onboarding flow.\n- Documentation clarified and streamlined to highlight the two onboarding options (free and wallet-funded).\n\nv0.1.0 | 2026-05-01T16:53:40.227Z | user\n\n### v0.1.0 β€” Breaking update: snapshot-only tooling, clearer usage\n\n- All recipes and scripts refactored to use only **snapshot/BATCH (bounded)** MCP calls; streaming tools (`bds_mpp_stream_*`) are no longer invoked.\n- Common task table and usage instructions updated to clarify bounded snapshot vs. streaming distinction.\n- Default tool options and examples reflect snapshot-focused flows (supporting reliable agent/cron operation).\n- Documentation updated for plan selection and metering environment variables.\n- Version number format normalized (0.1).\n\nv0.0.9 | 2026-05-01T16:33:41.977Z | user\n\nVersion 0.0.9\n\n- Added scripts/lib/powerloom-env.mjs for environment handling.\n- Changed all environment variable names to a POWERLOOM_ prefix (e.g., EVM_PRIVATE_KEY β†’ POWERLOOM_EVM_PRIVATE_KEY).\n- Updated documentation to emphasize the requirement for a burner wallet/private key for on-chain payments to purchase and top-up API credits.\n- Clarified the setup flow and environment variables in the SKILL.md, including new configuration and security warnings.\n- No changes to existing interfaces or core featuresβ€”update is focused on security, clarity, and environment variable standardization.\n\nv0.0.8 | 2026-04-26T13:51:23.444Z | user\n\n- Version bump from 0.0.6 to 0.0.8.\n- Documentation updates only; no code or functional changes detected\n\nv0.0.7 | 2026-04-26T13:47:40.925Z | user\n\n- State maintenance tip for oneshot Whale tracking cron job doc in references/\n\nv0.0.6 | 2026-04-26T13:25:15.351Z | user\n\npowerloom-bds-univ3 v0.0.6\n\n- Added a whale alert \"one shot\" recipe for OpenClaw and periodic hosts, documented in references/08-openclaw-one-shot.md.\n- Introduced scripts/whale-cron.mjs for bounded, one-shot whale alerts using bds_mpp_snapshot_allTrades, suitable for cron and OpenClaw integration.\n- Updated documentation to reflect the new whale cron recipe and OpenClaw integration instructions.\n\nv0.0.5 | 2026-04-26T12:51:29.035Z | user\n\nVersion 0.0.5\n\n- Updated signup-pay script to use `quote.payment_kind` for payment: supports both native/CGT and ERC-20 flows. \n- Clarified that POWER (7869) CGT plans require native payments only; ERC-20 path should not be used for these.\n\nv0.0.4 | 2026-04-25T07:38:02.571Z | user\n\n- Improved instructions for specifying `EVM_RPC_URL` when the default chain RPC is unavailable or empty in metering plans.\n- Clarified that `chains[].rpc_url` in `/credits/plans` is a public hint only, not always present, and to use `EVM_RPC_URL` directly when needed.\n- Added guidance for hosts and integrators, especially for scheduled or cron-style runs, recommending snapshot/poll mode tools over streaming tools for reliability and credit efficiency.\n- Expanded details about usage scenarios and appropriate tool/mode selection to help avoid timeouts and optimize metering usage.\n\nv0.0.3 | 2026-04-24T20:15:19.289Z | user\n\n**Added credits top-up script and clarified metering APIs.**\n\n- Added new script: scripts/credits-topup.mjs for direct ERC-20/native credit top-up via HTTP API.\n- Expanded SKILL.md with clear metering API usage: pay-signup, device signup, and top-up, reducing reliance on the Python bds-agent CLI.\n- Improved instructions for Node-based signup, credit top-up, and balance checksβ€”no Python required.\n- Clarified environment variable requirements and default endpoint details.\n- Bumped version to 0.0.3.\n\nv0.0.2 | 2026-04-24T17:53:56.349Z | user\n\n- Switched to an β€œagent-first” onboarding flow: EVM wallet, chain, plan, and token now required for setup and signup-pay; browser/device path is secondary.\n- Expanded required environment variables to include EVM and plan fields (`EVM_PRIVATE_KEY`, `EVM_RPC_URL`, `EVM_CHAIN_ID`, `PLAN_ID`, `TOKEN_SYMBOL`, `POWERLOOM_API_KEY`).\n- Clarified and restructured installation and top-up instructions to favor headless and automated agent environments.\n- Updated metadata to reflect new environment requirements and clarify optional parameters.\n- Updated documentation for Python and Node compatibility, highlighting β€œtop-up” flow for recharging credits.\n\nv0.0.1 | 2026-04-24T17:22:54.192Z | user\n\nInitial release of powerloom-bds-univ3: \n- Autonomous Uniswap V3 monitoring leveraging Powerloom’s consensus-backed on-chain data. \n- Key features: Whale Radar, Token-Flow, and DeFi Analyst with default recipes and script utilities. \n- Every data point verifiable on-chain via Powerloom DSV; includes guide for API key setup (browser/device and wallet-funded flows). \n- Supports event/phrase-triggered actions (e.g., \"whale alert\", \"track trades\", \"verify on-chain\"). \n- Detailed setup, usage, and model recommendations included in documentation.\n\nArchive index:\n\nArchive v0.2.6: 34 files, 53957 bytes\n\nFiles: package-lock.json (4617b), package.json (305b), README.md (6476b), recipes/defi-analyst.yaml (813b), recipes/token-flow.yaml (412b), recipes/whale-radar.yaml (751b), references/01-quickstart.md (1419b), references/02-tool-catalog.md (935b), references/03-verification.md (1037b), references/04-credit-budget.md (500b), references/05-data-market-scope.md (814b), references/06-troubleshooting.md (3592b), references/07-prompt-patterns.md (675b), references/08-openclaw-one-shot.md (8455b), references/09-openclaw-one-shot-free-key.md (8866b), scripts/credits-topup.mjs (6546b), scripts/defi-analyst.mjs (8252b), scripts/ensure-credits.mjs (1300b), scripts/lib/confirm-spend.mjs (2016b), scripts/lib/dispatch.mjs (1400b), scripts/lib/mcp.mjs (11542b), scripts/lib/powerloom-env.mjs (1667b), scripts/lib/recipe-config.mjs (690b), scripts/lib/state.mjs (1519b), scripts/lib/trade-utils.mjs (2134b), scripts/list-mcp-tools.mjs (488b), scripts/powerloom-mcp-client.mjs (644b), scripts/signup-pay.mjs (6462b), scripts/token-flow.mjs (4915b), scripts/whale-cron.mjs (9815b), scripts/whale-radar.mjs (4599b), skill-card.md (3360b), SKILL.md (12658b), _meta.json (138b)\n\nFile v0.2.6:SKILL.md\n\n---\nname: powerloom-bds-univ3\ndescription: |\n Autonomous Uniswap V3 monitoring on consensus-backed data with onchain provenance.\n Every data point is finalized on-chain by Powerloom's DSV network and independently\n verifiable. Ships with Whale Radar, Token-Flow, and DeFi Analyst recipes.\n Free API key at bds-metering.powerloom.io/metering (2 credits, no wallet).\n Triggers on \"whale alert\", \"track trades\", \"all trades for\", \"by token\",\n \"Powerloom\", \"verify on-chain\", \"verified data\".\nversion: 0.2.6\nhomepage: https://bds-metering.powerloom.io\nrepository: https://github.com/powerloom/powerloom-bds-univ3\ntags:\n - defi\n - uniswap\n - ethereum\n - on-chain\n - verifiable\n - consensus\n - agent\nmetadata:\n openclaw:\n emoji: \"πŸ¦„\"\n requires:\n bins: [\"node\"]\n env:\n # Only POWERLOOM_API_KEY is mandatory at install time. The free-key path\n # (references/09-openclaw-one-shot-free-key.md) needs nothing else from\n # this skill's perspective. Wallet/plan envs below are optional and only\n # consumed by scripts/signup-pay.mjs and scripts/credits-topup.mjs.\n - POWERLOOM_API_KEY\n optional_env:\n # Wallet-funded variants (signup-pay or credits-topup) β€” only required\n # if the user invokes those scripts. See references/08-openclaw-one-shot.md.\n - POWERLOOM_EVM_PRIVATE_KEY\n - POWERLOOM_EVM_RPC_URL\n - POWERLOOM_EVM_CHAIN_ID\n - POWERLOOM_PLAN_ID\n - POWERLOOM_TOKEN_SYMBOL\n # Dispatch + transport overrides β€” never required.\n - POWERLOOM_MCP_URL\n - POWERLOOM_TELEGRAM_BOT_TOKEN\n - POWERLOOM_TELEGRAM_CHAT_ID\n - POWERLOOM_DISCORD_WEBHOOK_URL\n - POWERLOOM_BDS_MCP_CALL_TIMEOUT_MS\n - POWERLOOM_BDS_MCP_DEBUG\n - POWERLOOM_METERING_BASE_URL\n - POWERLOOM_AGENT_NAME\n - POWERLOOM_EMAIL\n---\n\n# Powerloom BDS β€” Uniswap V3\n\n## Install\n\n> **Two onboarding paths.**\n>\n> **Free** β€” sign up at [`bds-metering.powerloom.io/metering`](https://bds-metering.powerloom.io/metering) (enter email + agent name, complete Turnstile, get `sk_live_...` immediately β€” no CLI, no wallet, 2 free credits). Alternatively, `bds-agent signup` runs the same flow from the terminal. Then paste [`references/09-openclaw-one-shot-free-key.md`](references/09-openclaw-one-shot-free-key.md) into OpenClaw. Sets `POWERLOOM_API_KEY` and a Whale Radar cron. Nothing else needed.\n>\n> **Wallet-funded** β€” paste [`references/08-openclaw-one-shot.md`](references/08-openclaw-one-shot.md) and `scripts/signup-pay.mjs` runs an autonomous on-chain payment for a 10-credit plan in the same prompt.\n>\n> **⚠️ WARNING β€” wallet-funded path only:** `signup-pay.mjs` and `credits-topup.mjs` need an EVM private key to broadcast on-chain payments. Use a **burner wallet** with limited funds dedicated to this purpose. Never use a wallet holding significant assets or with extensive transaction history for agentic setups. The free-key path **does not** require any wallet credentials.\n\n**Contract:** [bds-agenthub-billing-metering](https://github.com/powerloom/bds-agenthub-billing-metering). **ClawHub** users only need a **single origin** (default [bds-metering.powerloom.io](https://bds-metering.powerloom.io))β€” **`bds-agent` commands are optional**; they are a reference CLI for the same JSON bodies you can send with `curl` + a wallet or `ethers`.\n\n### Metering HTTP (authoritative)\n\n| What | How |\n|------|-----|\n| List SKUs | `GET {BASE}/credits/plans` β€” no auth. Choose a plan row: `id`, `chain_id`, `token_symbol` (and note `payment_kind`: ERC-20 vs native / CGT). **`chains[].rpc_url`** is a **public** JSON-RPC hint only when the metering deployment sets it; it may be **empty** β€” use **`POWERLOOM_EVM_RPC_URL`** for wallet / script calls in that case. |\n| New key, wallet-only | **Pay-signup:** `POST {BASE}/signup/pay/quote` β†’ pay on chain β†’ `POST {BASE}/signup/pay/claim` with `signup_nonce` + `tx_hash`. Returns `api_key`. |\n| New key, browser | Human device flow on [`{BASE}/metering`](https://bds-metering.powerloom.io/metering) (same service). Enter email + agent name, complete Turnstile, get `sk_live_...` immediately. |\n| More credits, existing key | `POST {BASE}/credits/topup` with `Authorization: Bearer sk_live_…` and tx / plan (not the pay-signup endpoints). |\n| Check balance | `GET {BASE}/credits/balance` with `Authorization: Bearer …` |\n\n`{BASE}` is **`POWERLOOM_METERING_BASE_URL`**, e.g. `https://bds-metering.powerloom.io`. Set **`POWERLOOM_API_KEY`** to the `sk_live_...` you get after pay-signup, device signup, or copy from the dashboard.\n\n### OpenClaw env vars (mandatory vs optional)\n\n| Field | When required | Role |\n|-------|---------------|------|\n| `POWERLOOM_API_KEY` | **Always** β€” only mandatory env at install time | `sk_live_...` from [`bds-metering.powerloom.io/metering`](https://bds-metering.powerloom.io/metering) or `bds-agent signup` (free path) or `signup-pay.mjs` claim (wallet path) |\n| `POWERLOOM_EVM_PRIVATE_KEY` | Wallet-funded path only | Payer wallet β€” **use a burner wallet** |\n| `POWERLOOM_EVM_RPC_URL` | Wallet-funded path only | JSON-RPC for that chain |\n| `POWERLOOM_EVM_CHAIN_ID` | Wallet-funded path only | Must match the plan's `chain_id` |\n| `POWERLOOM_PLAN_ID` | Wallet-funded path only | e.g. `launch_10_pl_power_cgt` from `GET /credits/plans` |\n| `POWERLOOM_TOKEN_SYMBOL` | Wallet-funded path only | e.g. `POWER` (must match that row) |\n\nThe schema in `metadata.openclaw.requires.env` lists only `POWERLOOM_API_KEY` as required; the wallet/plan envs above sit in `optional_env` and are read only by `scripts/signup-pay.mjs` (new key, pay-signup) and `scripts/credits-topup.mjs` (more credits on an existing key). Free-key flows pass straight through.\n\n### Reference client: `bds-agent` (optional)\n\n[docs/USER_GUIDE.md](https://github.com/powerloom/bds-agent-py/blob/main/docs/USER_GUIDE.md) in **bds-agent-py** has the end-to-end order: **Metering service API** table β†’ pay-signup β†’ device β†’ top-up. One-liner sequence:\n\n1. `bds-agent credits plans` β€” same as `GET /credits/plans`\n2. `bds-agent credits setup-evm` β€” writes `~/.config/bds-agent/profiles/.evm.env`\n3. `bds-agent signup-pay --plan-id … --chain-id … --token-symbol …` β€” implements quote / broadcast / claim (including **native** `payment_kind` plans)\n\n### This repo: Node scripts (no Python, no `bds-agent` required)\n\n| Script | What it does |\n|--------|----------------|\n| `node scripts/signup-pay.mjs` | **New** key: pay-signup (quote β†’ on-chain pay β†’ claim). Uses **`quote.payment_kind`**: `native_value` = send **native/CGT** (`tx.value` to `recipient`); `erc20` = token **`transfer`**. For **POWER (7869) CGT** plans, metering uses **`native_value`** β€” do not force ERC-20. **Broadcast protection:** interactive shells prompt `CONFIRM`; non-interactive shells require **`--yes`** (preferred for OpenClaw β€” ephemeral argv, do not persist in skill env) **or** `POWERLOOM_SIGNUP_PAY_CONFIRM=yes` (CI one-shot only). **`--dry-run`** prints quote summary and exits without sending a tx. |\n| `node scripts/credits-topup.mjs` | **More** credits: uses existing **`POWERLOOM_API_KEY`**, fetches `GET /credits/plans`, matches **`POWERLOOM_PLAN_ID` + `POWERLOOM_EVM_CHAIN_ID` + `POWERLOOM_TOKEN_SYMBOL`**, sends **ERC-20** or **native** per `payment_kind`, then **`POST /credits/topup`**. Same confirmation gate as signup-pay (**`--yes`** preferred; **`POWERLOOM_CREDITS_TOPUP_CONFIRM=yes`** for CI one-shot only; TTY `CONFIRM`). **`--dry-run`** prints summary only. Set **`POWERLOOM_EVM_RPC_URL`** when **`chains[].rpc_url`** is empty or you need a specific node (the API never exposes the server's private RPC). |\n| `node scripts/ensure-credits.mjs` | **Balance** only (`GET /credits/balance`); no purchase. |\n\n`npm install` once (adds `ethers`).\n\n**Optional env (signup script):** `POWERLOOM_METERING_BASE_URL`, `POWERLOOM_AGENT_NAME`, `POWERLOOM_EMAIL` (see [metering README](https://github.com/powerloom/bds-agenthub-billing-metering#readme)).\n\n### After you have a key β€” more credits (top-up)\n\n**Spec:** `POST {BASE}/credits/topup` with `Authorization: Bearer` and JSON `{ \"plan_id\", \"chain_id\", \"tx_hash\" }` after an on-chain payment that matches the plan. **In this repo:** `node scripts/credits-topup.mjs`. **Reference CLI:** [USER_GUIDE](https://github.com/powerloom/bds-agent-py/blob/main/docs/USER_GUIDE.md) (EVM `credits topup` / Tempo per deployment). **Check balance:** `node scripts/ensure-credits.mjs`.\n\n**Default MCP endpoint:** `https://bds-mcp.powerloom.io/sse` β€” override with `POWERLOOM_MCP_URL` if needed.\n\nGeneric tool runner: `node scripts/powerloom-mcp-client.mjs '{}'`\n\n## Common tasks β†’ which tool\n\n| Task phrase | Tool(s) |\n|-------------|---------|\n| Track **all swaps for token X** (multi-pool) | **Token-Flow** recipe (`bds_mpp_snapshot_trades_pool_address` per pool) or `bds_mpp_snapshot_allTrades` via **`whale-cron.mjs`** |\n| **Whale** / USD threshold | **`whale-cron.mjs`** (all pools, bounded) or **`whale-radar.mjs`** (fixed pool list, per-pool snapshots) |\n| **One pool only** | `bds_mpp_snapshot_trades_pool_address` after `bds_mpp_token_token_address_pools` or `bds_mpp_dailyActivePools` |\n| **Verify** on-chain | `verify_data_provenance` with `cid`, `epoch_id`, `project_id` from API β€” never substitute block for epoch |\n\n**Timeouts:** default `POWERLOOM_BDS_MCP_CALL_TIMEOUT_MS=60000`. Raise it (e.g. **120000**) if `bds_mpp_snapshot_allTrades` times out under backlog.\n\n## Recipes (supported surface)\n\nPre-built scripts + `recipes/*.yaml` defaults β€” prefer these over ad-hoc scripts on weaker models. **This skill does not call streaming catalog tools** (`bds_mpp_stream_*`); every recipe uses **bounded snapshot** MCP calls so runs fit cron and agent sandboxes.\n\n**Cron default:** `whale-radar.mjs`, `token-flow.mjs`, and `defi-analyst.mjs` each run **one bounded round** and **exit** (safe for OpenClaw cron). Pass **`--daemon`** to repeat with `heartbeat.interval_seconds` between rounds (local / long-running only).\n\n| Recipe / entrypoint | Script |\n|---------------------|--------|\n| Whale Radar (fixed pools) | `node scripts/whale-radar.mjs` β€” one round over `poll_fallback_pools`; **`--daemon`** for repeat |\n| Whale alerts (cron, all pools) | `node scripts/whale-cron.mjs` β€” **bounded** one-shot: `bds_mpp_snapshot_allTrades` + pool metadata; alerts include **snapshot** `cid` / epoch / project from `data.verification` β€” see **Verification provenance** in `references/08-openclaw-one-shot.md` |\n| Token-Flow | `node scripts/token-flow.mjs` (`--token 0x...`) β€” one round per pool for that token; **`--daemon`** for repeat |\n| DeFi Analyst | `node scripts/defi-analyst.mjs` β€” one round: **multi-pool** (`bds_mpp_snapshot_allTrades` + all-pools volume) or `filters.scope: single_pool`; **`--daemon`** for repeat |\n\n## Model guidance\n\nRecipes produce the same stdout/Telegram output regardless of model. Ad-hoc \"compose your own\" prompts work best on GPT-4–class or GLM-5+; weaker local models may collapse multi-pool prompts onto one pool β€” **use the Token-Flow recipe** instead.\n\n## Hosts & integrators (OpenClaw, cron, heartbeats)\n\n**OpenClaw \"one shot\" setups** β€” pick the variant that matches the user's onboarding state:\n\n| Variant | Use when | Reference |\n|---------|----------|-----------|\n| Free-key cron | The user already has `sk_live_...` from [`bds-metering.powerloom.io/metering`](https://bds-metering.powerloom.io/metering) or `bds-agent signup` (2 free credits, no wallet) | [`references/09-openclaw-one-shot-free-key.md`](references/09-openclaw-one-shot-free-key.md) |\n| Pay-signup + cron | The user wants autonomous wallet-funded onboarding for a 10-credit plan in the same prompt | [`references/08-openclaw-one-shot.md`](references/08-openclaw-one-shot.md) |\n\nBoth prompts produce the same `Whale Radar` cron firing `node scripts/whale-cron.mjs` every 15s with onchain verification surfaced in every alert. Agents should default to the free-key variant unless the user explicitly asks for autonomous on-chain payment.\n\n**Scheduled / cron-style runs:** Prefer **`whale-cron.mjs`**, **`whale-radar.mjs`**, **`token-flow.mjs`**, or **`defi-analyst.mjs`** with **no** `--daemon` so each invocation **exits**. **Streaming trade tools** (`bds_mpp_stream_*`) are **not** used by this skill.\n\n## References\n\nSee `references/` for quickstart, full tool table, verification, credit budget, scope, troubleshooting, prompt patterns, **`08-openclaw-one-shot.md`** (copy-paste OpenClaw runbook), and cron notes in quickstart + tool catalog.\n\nFile v0.2.6:README.md\n\n# Powerloom BDS β€” Uniswap V3 (ClawHub skill)\n\n## Autonomous Uniswap V3 monitoring + onchain provenance verification, in minutes. Decentralized data, not trust-me data.\n\nEvery data point this skill fetches is finalized onchain by Powerloom's decentralized sequencer-validator network. The `verify_data_provenance` tool compares API CIDs to onchain commitments so alerts can carry a cryptographic receipt, not a vendor's word.\n\n## Recipes\n\n- **Whale Radar** β€” USD-threshold alerts: **`bds_mpp_snapshot_trades_pool_address`** for each pool in `poll_fallback_pools`. For **cron / OpenClaw heartbeats** over **all** pools in one bounded batch, use **`node scripts/whale-cron.mjs`** (`bds_mpp_snapshot_allTrades` + pool metadata).\n- **Token-Flow** β€” all swaps touching a configured token (default USDC) across pools derived at runtime.\n- **Autonomous DeFi Analyst** β€” default **multi-pool** `bds_mpp_snapshot_allTrades` + all-pools token volume; set **`filters.scope: single_pool`** in `recipes/defi-analyst.yaml` for single-pool snapshots only.\n\n## Integrators (OpenClaw, cron)\n\n**End-to-end one-shot prompts** β€” pick by onboarding state:\n\n| Variant | Use when | Reference |\n|---------|----------|-----------|\n| Free-key cron | You already have `sk_live_...` from `bds-agent signup` (2 free credits, no wallet) | **`references/09-openclaw-one-shot-free-key.md`** |\n| Pay-signup + cron | You want autonomous wallet-funded onboarding for a 10-credit plan in the same prompt | **`references/08-openclaw-one-shot.md`** |\n\n**Default behavior:** `whale-radar.mjs`, `token-flow.mjs`, and `defi-analyst.mjs` each run **one bounded round** and **exit** (safe for cron). Use **`--daemon`** only if you want a local repeat loop (`heartbeat.interval_seconds` between rounds).\n\nFor **scheduled heartbeats**, prefer **`whale-cron.mjs`** (exits) or the recipe scripts **without** `--daemon`. This repo does not ship streaming trade consumption.\n\n## Setup\n\n```bash\ncd powerloom-bds-univ3\nnpm install\nexport POWERLOOM_API_KEY=sk_live_...\nnode scripts/ensure-credits.mjs\n```\n\n**Where to get `POWERLOOM_API_KEY`:**\n\n- **Free** (no wallet, 2 credits): `bds-agent signup` β€” browser device flow on the metering service. Same `sk_live_...` works against this skill, the hosted MCP server, and any pay-signup top-up later.\n- **Wallet-funded** (10-credit plan): `node scripts/signup-pay.mjs --dry-run` (quote summary only), then **`node scripts/signup-pay.mjs --yes`** once after verifying stderr output β€” prefer argv over env so confirmation bypass is **not** persisted in OpenClaw skill config. CI may use `POWERLOOM_SIGNUP_PAY_CONFIRM=yes` for a single invocation only. **Native or ERC-20** per `quote.payment_kind` (POWER CGT on 7869 = native).\n- **More credits, existing key**: `node scripts/credits-topup.mjs` β€” same `--dry-run` β†’ **`--yes`** pattern (or one-shot env for CI only). See **`SKILL.md`**.\n\nOptional: `POWERLOOM_TELEGRAM_BOT_TOKEN`, `POWERLOOM_TELEGRAM_CHAT_ID`, and `dispatch.channel: telegram` in `recipes/*.yaml`.\n\n## Links (metering service)\n\nOne deploy (`npm run build` + `npm start` on **`bds-agenthub-billing-metering`**) serves both:\n\n- **Agent signup (CLI / API)** β€” origin only: [bds-metering.powerloom.io](https://bds-metering.powerloom.io) (`BDS_AGENT_SIGNUP_URL` / `bds-agent signup --base-url …`).\n- **Browser signup + billing UI** β€” [bds-metering.powerloom.io/metering](https://bds-metering.powerloom.io/metering)\n\n- Hosted MCP SSE: `https://bds-mcp.powerloom.io/sse`\n\n## Naming (ClawHub skill vs MCP tools)\n\n| What | Name |\n|------|------|\n| ClawHub / OpenClaw skill folder & slug | **`powerloom-bds-univ3`** |\n| MCP tools on the hosted server | **`bds_mpp_*`**, **`get_credit_balance`**, **`verify_data_provenance`** β€” there is **no** tool named `bds_univ3`. |\n\nTo print the live tool list from the API (same handshake as `callTool`):\n\n```bash\nexport POWERLOOM_API_KEY=sk_live_...\nnode scripts/list-mcp-tools.mjs\n```\n\n## Test locally (without publishing to ClawHub)\n\nPublishing is optional for trying the **scripts** and **SKILL.md** instructions:\n\n1. **Scripts only** β€” From this directory, with `POWERLOOM_API_KEY` set, run `node scripts/ensure-credits.mjs`, `node scripts/list-mcp-tools.mjs` (proves tool names), `node scripts/powerloom-mcp-client.mjs get_credit_balance '{}'`, or a recipe (`whale-radar.mjs`, etc.). That validates MCP wiring end-to-end against the hosted server.\n\n2. **OpenClaw / ClawHub** β€” If **`skills list`** and the **dashboard** show **`powerloom-bds-univ3`** as **ready**, the skill is **on disk and registered**. That is not the same as β€œthe main chat always loads **`SKILL.md`** into the model on every turn.” If chat still acts blind, check your OpenClaw **agent** actually **uses** that skill (per-agent skill selection / defaults), then **new session** after changes. The reliable execution path is still **`node scripts/…`** with **`POWERLOOM_API_KEY`**; chat is best-effort unless you also wire **BDS MCP** for tools in the tool list.\n\n - **Registry:** `clawhub install powerloom-bds-univ3` only pulls **published** builds. **Local dev:** copy this repo’s root into **`…/workspace/skills/powerloom-bds-univ3/`** with **`SKILL.md`** at the folder root, set **`POWERLOOM_API_KEY`** in `openclaw.json` skill `entries`, restart the gateway.\n - **Compose / `OPENCLAW_WORKSPACE_DIR`:** The stack usually reads a **`.env` file next to `docker-compose.yml`**. [Docker Compose](https://docs.docker.com/compose/how-tos/environment-variables/variable-interpolation/) substitutes **`${OPENCLAW_WORKSPACE_DIR}`** from: that `.env` file, or **exported** variables in the shell you run `docker compose` from, or a **`.env` override** your vendor documents. It is not magic β€” if unset, the mount line can be wrong or empty. Set it to the **host** path that should map to `…/workspace` in the container (often your user’s `…/.openclaw/workspace` as an **absolute** path). Check `docker compose config` to see the resolved value.\n\n Docker bind mounts, **`ENOENT`**, symlinks, UI quirks: **`references/06-troubleshooting.md`**.\n\n3. **After publish** β€” `clawhub install powerloom-bds-univ3` (or the slug you published).\n\n## Publish (maintainers)\n\n```bash\nnpx clawhub login\nnpx clawhub publish . --slug powerloom-bds-univ3 --version 0.1.0\n```\n\n## Repository\n\nSource: [github.com/powerloom/powerloom-bds-univ3](https://github.com/powerloom/powerloom-bds-univ3) (mirror this folder into that org repo).\n\nFile v0.2.6:_meta.json\n\n{\n \"ownerId\": \"kn7a3wb3bny97qvtprbgh9cxe185fms0\",\n \"slug\": \"powerloom-bds-univ3\",\n \"version\": \"0.2.6\",\n \"publishedAt\": 1778781355949\n}\n\nFile v0.2.6:references/01-quickstart.md\n\n# Quickstart (~10 minutes)\n\n1. **Get an API key** β€” **CLI / API:** metering origin [bds-metering.powerloom.io](https://bds-metering.powerloom.io) (`bds-agent signup`; see [agent guide](https://github.com/powerloom/bds-agent-py/blob/main/docs/USER_GUIDE.md)). **Browser:** signup and top-ups at [bds-metering.powerloom.io/metering](https://bds-metering.powerloom.io/metering).\n2. **Export** `POWERLOOM_API_KEY=sk_live_...` in the environment OpenClaw uses (or your shell profile).\n3. **Optional** β€” default MCP URL is `https://bds-mcp.powerloom.io/sse`. Override with `POWERLOOM_MCP_URL` if directed.\n4. **Check credits**: `node scripts/ensure-credits.mjs` β€” should print balance JSON and exit 0.\n5. **OpenClaw / cron** β€” for **one-shot schedulers** (recommended), use **`node scripts/whale-cron.mjs`** and the full copy-paste flow in **`references/08-openclaw-one-shot.md`**. For a **fixed pool list** and local poll loop, use **`whale-radar.mjs`** (per-pool snapshots only).\n6. **Run a recipe** (stdout first):\n - Whale cron (bounded, all pools): `node scripts/whale-cron.mjs`\n - Whale Radar (fixed pools, poll): `node scripts/whale-radar.mjs`\n - Token-Flow: `node scripts/token-flow.mjs`\n - DeFi Analyst (one round, cron): `node scripts/defi-analyst.mjs`\n7. **Telegram** β€” set `POWERLOOM_TELEGRAM_BOT_TOKEN` and `POWERLOOM_TELEGRAM_CHAT_ID`, set `dispatch.channel` to `telegram` in the recipe yaml.\n\nFile v0.2.6:references/02-tool-catalog.md\n\n# BDS MCP tool catalog (representative)\n\nAll calls are metered unless noted. **Defaults:** `POWERLOOM_BDS_MCP_CALL_TIMEOUT_MS=60000` (raise for large `bds_mpp_snapshot_allTrades` responses under backlog, e.g. `120000`).\n\n**Skill note:** `powerloom-bds-univ3` recipes use **snapshot** tools only (`bds_mpp_snapshot_*`). Streaming catalog tools exist on the hosted MCP server for direct/advanced use but are **not** invoked by shipped scripts.\n\n| Tool | What | Typical latency | Skill usage |\n|------|------|-----------------|-------------|\n| `bds_mpp_snapshot_allTrades` | One-shot all pools (bounded batch) | 8–45s | `whale-cron.mjs`, DeFi Analyst multi |\n| `bds_mpp_snapshot_trades_pool_address` | One pool snapshot | 2–15s | `whale-radar.mjs`, `token-flow.mjs` |\n| `bds_mpp_stream_allTrades` | Streaming batches (long-lived upstream) | varies | **Not used by skill** |\n\nSee the live server’s `tools/list` for the full catalog.\n\nFile v0.2.6:references/03-verification.md\n\n# `verify_data_provenance`\n\nCompares a snapshot **CID** to on-chain `maxSnapshotsCid` for `(data_market, project_id, epoch_id)` via the Powerloom protocol state contract.\n\n**Inputs:** `cid` (string), `epoch_id` (integer), `project_id` (string). Optional `data_market` override.\n\n**Hosted MCP** runs the `eth_call` on the server (configured RPC is **not** included in the tool response). If the server’s RPC is unset, the tool returns a clear configuration error β€” not a silent pass. For a **local** second check, use the same `cid` / `epoch_id` / `project_id` with your own provider **`POWERLOOM_EVM_RPC_URL`** (e.g. public Powerloom JSON-RPC) and the documented ProtocolState / DataMarket addresses β€” do not expect MCP to echo an RPC URL.\n\n**Metering** `GET /credits/plans` exposes **`chains[].rpc_url`** only as an optional **public** hint; it can be empty.\n\n**In alerts:** only print verification lines when `cid`, `epoch_id`, and `project_id` are all known from the API response. Do not substitute block numbers for epoch IDs.\n\nFile v0.2.6:references/04-credit-budget.md\n\n# Credit budget (targets β€” validate in dry run)\n\n| Recipe | Mode | Steady credits/hour (target) | Free tier (~100 cr) |\n|--------|------|------------------------------|---------------------|\n| Whale Radar (poll) | per-pool snapshots | TBD | TBD |\n| Token-Flow | per-pool snapshots | TBD | TBD |\n| Whale cron | bounded `snapshot_allTrades` | TBD | TBD |\n| DeFi Analyst | 5m + p=0.2 verify | ~40 | ~2.5 h |\n\nUpdate this table after measured burn from `get_credit_balance` deltas during a 1-hour run.\n\nFile v0.2.6:references/05-data-market-scope.md\n\n# Data market scope (ETH mainnet Uniswap V3)\n\n## Canonical worked example (single pool)\n\n| Pool | Address | Fee tier |\n|------|---------|----------|\n| WETH/USDC | `0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640` | 0.05% |\n\nSome fee tiers (e.g. 0.3% WETH/USDC) may **not** be indexed in this data market β€” check `bds_mpp_pool_pool_address_metadata` / `bds_mpp_dailyActivePools` before assuming coverage.\n\n## Multi-pool / token-first\n\n- **All pools / all trades (bounded):** `bds_mpp_snapshot_allTrades` (skill + cron). Streaming variants may exist on MCP for direct use outside the skill.\n- **Token-scoped:** `bds_mpp_token_token_address_pools`, `bds_mpp_tradeVolumeAllPools_token_address_time_interval`.\n- **Single pool:** `bds_mpp_snapshot_trades_pool_address` β€” use only when the user explicitly wants one pool.\n\nFile v0.2.6:references/06-troubleshooting.md\n\n# Troubleshooting\n\n| Symptom | Cause | Fix |\n|---------|--------|-----|\n| Pay-signup \"recipient did not match\" / wrong first tx (POWER 7869) | **`signup-pay.mjs` used ERC-20** while plan is **`payment_kind: native_value`** (CGT) | **Update** the script from the current skill repo, or use a flow that checks **`quote.payment_kind`**: native = `sendTransaction({ to, value })` only, not `token.transfer`. `credits-topup.mjs` already branches on `payment_kind`. |\n| HTTP 401 | Bad or missing API key | Re-copy key from the metering dashboard ([bds-metering.powerloom.io/metering](https://bds-metering.powerloom.io/metering)) or your CLI profile; fix `POWERLOOM_API_KEY`. |\n| HTTP 402 | Credits exhausted | Top up; reduce recipe cadence; run `ensure-credits.mjs` before crons. |\n| HTTP 429 | Rate limit | Increase heartbeat interval; for **cron** schedules prefer **poll** (fewer parallel calls) instead of many snapshot fan-outs. |\n| Tool timeout | Backlog / slow finalization | Raise `POWERLOOM_BDS_MCP_CALL_TIMEOUT_MS`; reduce snapshot scope (`max_events` / fewer pools). |\n| Empty snapshot | Idle chain / catch-up | Wait; check `from_epoch` in state file (cron / DeFi Analyst). |\n| Wrong verify | Confused epoch vs block | Use `epoch_id` from snapshot / `verification` payload, not `blockNumber`. |\n| Odd outputs after model swap | OpenClaw context mismatch | Restart OpenClaw; recipes are script-driven β€” state files live under `.powerloom/`. |\n| Skill β€œready” in `skills list` / dashboard but main chat ignores it | **Install β‰  injection.** The chat agent may not attach every skill to every session; per-agent config, a **new** session after enabling the skill, or product limits on which skills the model sees. | Enable the skill for **that** agent; start a new chat; add **BDS MCP** in config if you need tools in the tool list. For deterministic behavior, run **`node scripts/…`**. |\n| `OPENCLAW_WORKSPACE_DIR` seems wrong in Docker | Compose interpolates `${VAR}` from a **`.env` next to `docker-compose.yml`**, the shell **environment**, or an `env_file` the compose file references β€” whatever OpenClaw’s install template ships. | Set **`OPENCLAW_WORKSPACE_DIR=`** in that `.env` to the **host** absolute path for workspace (e.g. `/Users/you/.openclaw/workspace`). Run **`docker compose config`** to verify substitution; **recreate** containers after changing `.env` (`up -d` / `up --force-recreate` as needed). |\n| `NO_SESSION` / β€œsession_id never arrived” | SSE bootstrap did not expose a parseable `session_id` (UUID vs hex, proxy, or stale client) | Confirm `POWERLOOM_MCP_URL` ends with `/sse` reachable from the runtime (e.g. Docker). Set **`POWERLOOM_BDS_MCP_DEBUG=1`** once to log the first bytes of the SSE stream in the error. |\n| `ENOENT` on `.../skills/.../SKILL.md` (OpenClaw in Docker) | The **container** does not have that file at the path the process checks. Common: wrong **host** tree for **`OPENCLAW_WORKSPACE_DIR`** (compose often mounts `${OPENCLAW_WORKSPACE_DIR}:/home/node/.openclaw/workspace` β€” skills belong under that dir’s `skills/` on the host, not a second guess at `~` if the env points elsewhere), nested slug folder, or symlink outside the mount. | **In the failing container:** `ls -la /home/node/.openclaw/workspace/skills/powerloom-bds-univ3/SKILL.md` (official compose) **or** `ls` under `/app/skills/...` if your error path uses `/app`. Copy/rsync the skill to the **host path** that maps to the shown prefix, with **`SKILL.md` at the slug root**; restart the gateway. `EACCES` (rare): `chmod -R a+rX` on the skill tree. |\n\nFile v0.2.6:references/07-prompt-patterns.md\n\n# Prompt patterns β†’ tools\n\n| User intent | Primary path |\n|-------------|--------------|\n| β€œAll USDC swaps”, β€œevery trade for token X” | **Token-Flow** (`token-flow.yaml`) β€” per-pool snapshots; or `bds_mpp_snapshot_allTrades` via **`whale-cron.mjs`** for all pools in one batch. |\n| β€œWhale”, β€œabove $X” | **`whale-cron.mjs`** (all pools, bounded) or **`whale-radar.mjs`** (fixed pool list). |\n| β€œOne pool” | `bds_mpp_snapshot_trades_pool_address` after resolving the pool. |\n| β€œIs this CID real?” | `verify_data_provenance` with `cid`, `epoch_id`, `project_id`. |\n\nThe skill does **not** ship streaming trade consumption; use snapshot tools only.\n\nFile v0.2.6:references/08-openclaw-one-shot.md\n\n# OpenClaw: pay-signup + whale cron (one-shot prompt)\n\nUse this as a **single agent message** after installing the skill from ClawHub. It matches how the skill is meant to run: **bounded** `bds_mpp_snapshot_allTrades` via `scripts/whale-cron.mjs`. The skill does **not** use streaming trade tools.\n\n---\n\n## Copy-paste prompt\n\n````\nInstall the skill \"πŸ¦„ Powerloom Uniswap V3 timeseries data\" (powerloom-bds-univ3) from ClawHub.\nAfter install, run npm install in the skill directory.\n\n**REQUIRED INPUTS β€” gather BOTH from me in chat BEFORE running `signup-pay.mjs` or creating any cron job. STOP and ask if either is missing. Do NOT proceed past this section with values unresolved. Asking me for any of these AFTER the cron job is created is a failure mode β€” re-ask BEFORE cron creation.**\n\na. **Payer wallet private key** β€” paste your EVM private key for the funded wallet that will pay 50 $POWER for the credit plan. **Use a burner wallet only** β€” never a wallet holding significant assets or with extensive transaction history. This key is consumed by `node scripts/signup-pay.mjs` and stored in OpenClaw env as `POWERLOOM_EVM_PRIVATE_KEY`.\n\nb. **Telegram alerts** β€” ask explicitly: \"Do you want Telegram alerts for whale swaps? If yes, paste your `POWERLOOM_TELEGRAM_BOT_TOKEN` and `POWERLOOM_TELEGRAM_CHAT_ID`. If no, type 'skip' and alerts will print to stdout only.\"\n - If I give you both tokens β†’ use them in the cron env (step 5 below).\n - If I explicitly say \"skip\" / \"no Telegram\" / \"stdout only\" β†’ proceed without TG envs and tell me clearly in the final cron summary that alerts will only print to stdout (the cron `--no-deliver` flag means OpenClaw's chat won't see them either).\n - Do NOT silently default to \"stdout is fine.\" Either both TG values, or an explicit opt-out.\n - Do NOT look up TG credentials from any OpenClaw config source (`channels.telegram`, `openclaw.json`, etc.) β€” only use what I paste in this conversation.\n\nOnce (a) and (b) are resolved in chat, proceed with the steps below.\n\nThen set up pay-signup and a whale radar cron. Details:\n\n1. PLAN: launch_10_pl_power_cgt (POWER native on chain 7869, rpc-v2.powerloom.network)\n2. Pay-signup using `scripts/signup-pay.mjs` with the private key from input (a):\n - **Recommended:** run `node scripts/signup-pay.mjs --dry-run` first β€” prints quote summary (recipient, amount_atomic, chain, payment_kind) to stderr; paste into chat so I can confirm values against metering UI / `/credits/plans`.\n - **Broadcast (non-interactive):** run `node scripts/signup-pay.mjs --yes` as a **one-off shell command** after review β€” **do not** persist `--yes` or any confirmation bypass inside OpenClaw long-lived skill env (`skills.entries.*.env`). CI operators may instead use `POWERLOOM_SIGNUP_PAY_CONFIRM=yes` for a single invocation; avoid leaving that variable set in autonomous sessions.\n - **TTY:** omit `--yes`; the script prompts `CONFIRM` interactively.\n Non-interactive shells refuse to broadcast without `--yes` / `POWERLOOM_SIGNUP_PAY_CONFIRM=yes` β€” this is intentional broadcast protection.\n `signup-pay.mjs` uses `quote.payment_kind`: `native_value` β†’ `sendTransaction({ value })`; `erc20` β†’ `token.transfer()`.\n3. After signup, set the `sk_live_...` API key and all six env vars in OpenClaw under\n `skills.entries.powerloom-bds-univ3.env.*`:\n `POWERLOOM_EVM_PRIVATE_KEY` (from input a), `POWERLOOM_EVM_RPC_URL`, `POWERLOOM_EVM_CHAIN_ID`, `POWERLOOM_PLAN_ID`, `POWERLOOM_TOKEN_SYMBOL`, `POWERLOOM_API_KEY` (from `signup-pay.mjs` claim output).\n Plus, if input (b) yielded values: `POWERLOOM_TELEGRAM_BOT_TOKEN`, `POWERLOOM_TELEGRAM_CHAT_ID`.\n If the schema expects strings, pass `POWERLOOM_EVM_CHAIN_ID` as a quoted string (e.g. `\"7869\"`).\n4. `scripts/whale-cron.mjs` should:\n - Use `lib/mcp.mjs` `callTool()` for all MCP calls (SSE handshake, not raw HTTP).\n - Use `lib/trade-utils.mjs` `flattenAllTradesFromSnapshot()` to parse the snapshot.\n - Response shape: `result.data.tradeData` = `{ poolAddr: { trades: [...] } }`.\n - Resolve pool token names with `bds_mpp_pool_pool_address_metadata` per unknown pool;\n cache in `.powerloom/pool-metadata-cache.json` (override with `WHALE_CRON_POOL_CACHE`).\n - Verification: `result.data.verification` = `{ cid, epochId, projectId }` β€” surface in alerts (e.g. βœ…).\n - Telegram: `parse_mode: MarkdownV2` with full escaping, or plain-text fallback.\n - If the script is missing or broken, rebuild using the skill’s `lib/*` helpers only.\n5. Create an OpenClaw cron job β€” **only after** REQUIRED INPUTS (a) and (b) above are fully resolved in chat AND `signup-pay.mjs` has produced the API key:\n - Name: e.g. \"Whale Radar\"\n - Schedule: e.g. every 15s (`--every 15s` with `openclaw cron add`)\n - Timeout: 90s (`--timeout 90000`)\n - Session: isolated (`--session isolated`)\n - Flags: `--no-deliver`, `--light-context`\n - Message: a shell command that `cd`s to the skill dir, sets env inline, then runs `node scripts/whale-cron.mjs`. Required env in the cron message:\n - `POWERLOOM_API_KEY=`\n - `POWERLOOM_BDS_MCP_CALL_TIMEOUT_MS=120000`\n - `WHALE_CRON_THRESHOLD=10000` (default; only override if I asked for a different threshold)\n - Telegram env in the cron message β€” **only** if input (b) yielded both values:\n - `POWERLOOM_TELEGRAM_BOT_TOKEN=`\n - `POWERLOOM_TELEGRAM_CHAT_ID=`\n - Do NOT consult OpenClaw `channels.telegram`, `openclaw.json`, or any other config source for Telegram credentials β€” only use what I pasted in chat for input (b).\n6. Before the first run: `rm -f .powerloom/whale-cron-state.json` if you need a clean epoch cursor.\n Keep `.powerloom/pool-metadata-cache.json` across reinstalls unless debugging metadata.\n7. Set WHALE_CRON_STATE_FILE and WHALE_CRON_POOL_CACHE to paths outside the skill directory (e.g. in the workspace root) so they survive openclaw skills install --force.\n\nConstraints:\n- **Pay-signup broadcast:** run `node scripts/signup-pay.mjs --dry-run` first unless I explicitly waive dry-run in chat; paste stderr quote summary into chat for my review; then run **`node scripts/signup-pay.mjs --yes` once** as an ephemeral shell invocation (not saved in OpenClaw skill env). CI may use `POWERLOOM_SIGNUP_PAY_CONFIRM=yes` for a single job β€” do not leave confirmation bypass variables persisted alongside wallet keys. TTY sessions type `CONFIRM` instead.\n- **Telegram credentials must be gathered from me in chat (or explicit opt-out received) BEFORE the cron job is created.** Asking me for `POWERLOOM_TELEGRAM_BOT_TOKEN` / `POWERLOOM_TELEGRAM_CHAT_ID` after running `openclaw cron add` and seeing the cron tick (with stdout-only alerts) is a known failure mode β€” fail the run and re-ask before cron creation.\n- Do NOT use OpenClaw config (`channels.telegram`, `openclaw.json`, etc.) as a fallback Telegram source β€” chat input only.\n- Use `bds_mpp_snapshot_allTrades` only (bounded batches). Do not add streaming trade tools.\n- Do NOT run the tracker as a background process β€” use OpenClaw cron only.\n- Do NOT show \"???\" for unknown tokens β€” resolve via the metadata tool or show the address.\n````\n\n---\n\n## Verification provenance (cron script + one-shot)\n\n**In `scripts/whale-cron.mjs` (already implemented):** each `bds_mpp_snapshot_allTrades` result carries `data.verification` (`cid`, `epochId`, `projectId`). The script reads that object once per poll and appends a **β€œVerified on-chain”** block (CID, epoch, project) to each formatted alert in `formatAlert` β€” it is not optional glue you add in the OpenClaw message; the one-shot above assumes this behavior.\n\n**Independent check:** the MCP tool `verify_data_provenance` can confirm commitments using the same `cid` / `epoch_id` / `project_id` β€” see **`references/03-verification.md`** and the **Verify** row in `SKILL.md` (data table).\n\n---\n\n## Related files in this skill\n\n| Item | Location |\n|------|----------|\n| Cron entrypoint (incl. verification in alerts) | `scripts/whale-cron.mjs` |\n| Pay-signup | `scripts/signup-pay.mjs` |\n| MCP + trade helpers | `lib/mcp.mjs`, `lib/trade-utils.mjs`, `lib/state.mjs` |\n| On-chain verification details | `references/03-verification.md` |\n| Integrator rules | `SKILL.md` β†’ **Hosts & integrators** |\n\nSee also `references/01-quickstart.md` and `references/06-troubleshooting.md`.\n\nFile v0.2.6:references/09-openclaw-one-shot-free-key.md\n\n# OpenClaw: free-key whale cron (one-shot prompt)\n\nUse this as a **single agent message** after running `bds-agent signup` to get a free `sk_live_...` API key (browser device flow, 2 free credits, no wallet). The skill itself only needs **`POWERLOOM_API_KEY`** at runtime β€” `whale-cron.mjs` dispatches alerts via the hosted MCP server using that key alone.\n\nFor the wallet-funded variant (autonomous on-chain pay-signup for a 10-credit plan in the same prompt), see [`references/08-openclaw-one-shot.md`](./08-openclaw-one-shot.md).\n\n---\n\n## Copy-paste prompt\n\n````\nInstall the skill \"πŸ¦„ Powerloom Uniswap V3 timeseries data\" (powerloom-bds-univ3) from ClawHub.\nAfter install, run npm install in the skill directory.\n\nI already have a Powerloom API key (sk_live_...) from `bds-agent signup` β€” 2 free credits, no wallet needed. Use that key directly. Do NOT run `scripts/signup-pay.mjs`. Do NOT ask for a private key, RPC URL, plan id, chain id, or token symbol.\n\n**REQUIRED INPUTS β€” gather BOTH from me in chat BEFORE you install the skill, wire any env, or create any cron job. STOP and ask if either is missing. Do NOT proceed to step 1 below until both are resolved. Asking me for any of these AFTER creating the cron is a failure mode β€” re-ask BEFORE cron creation.**\n\na. **Powerloom API key** β€” paste your `sk_live_...` from `bds-agent signup`. If you don't have one yet, run `bds-agent signup` first (free, 2 credits, browser device flow) and come back. Do not invent or guess a key.\n\nb. **Telegram alerts** β€” ask explicitly: \"Do you want Telegram alerts for whale swaps? If yes, paste your `POWERLOOM_TELEGRAM_BOT_TOKEN` and `POWERLOOM_TELEGRAM_CHAT_ID`. If no, type 'skip' and alerts will print to stdout only.\"\n - If I give you both tokens β†’ use them in the cron env (steps 1 and 4 below).\n - If I explicitly say \"skip\" / \"no Telegram\" / \"stdout only\" β†’ proceed without TG envs and tell me clearly in the final cron summary that alerts will only print to stdout (the cron `--no-deliver` flag means OpenClaw's chat won't see them either).\n - Do NOT silently default to \"stdout is fine.\" Either both TG values, or an explicit opt-out.\n - Do NOT look up TG credentials from any OpenClaw config source (`channels.telegram`, `openclaw.json`, etc.) β€” only use what I paste in this conversation.\n\nOnce (a) and (b) are resolved in chat, proceed with the steps below.\n\nSet up a whale radar cron with the existing key. Details:\n\n1. Set the gathered envs in OpenClaw under `skills.entries.powerloom-bds-univ3.env.*`:\n - `POWERLOOM_API_KEY` β€” required, from input (a).\n - `POWERLOOM_TELEGRAM_BOT_TOKEN`, `POWERLOOM_TELEGRAM_CHAT_ID` β€” set both **only** if I gave you values in input (b). If I opted out, leave both unset; `whale-cron.mjs` prints alerts to stdout in that case (still includes the verification block).\n\n2. Pre-flight: `node scripts/ensure-credits.mjs` to confirm the key is valid and balance is non-zero (free signup grants 2 credits).\n\n3. `scripts/whale-cron.mjs` should:\n - Use `lib/mcp.mjs` `callTool()` for all MCP calls (SSE handshake, not raw HTTP).\n - Use `lib/trade-utils.mjs` `flattenAllTradesFromSnapshot()` to parse the snapshot.\n - Response shape: `result.data.tradeData` = `{ poolAddr: { trades: [...] } }`.\n - Resolve pool token names with `bds_mpp_pool_pool_address_metadata` per unknown pool;\n cache in `.powerloom/pool-metadata-cache.json` (override with `WHALE_CRON_POOL_CACHE`).\n - Verification: `result.data.verification` = `{ cid, epochId, projectId }` β€” surface in alerts (e.g. βœ…).\n - Telegram: `parse_mode: MarkdownV2` with full escaping, or plain-text fallback.\n - If the script is missing or broken, rebuild using the skill’s `lib/*` helpers only.\n\n4. Create an OpenClaw cron job β€” **only after** REQUIRED INPUTS (a) and (b) above are fully resolved in chat:\n - Name: e.g. \"Whale Radar\"\n - Schedule: e.g. every 15s (`--every 15s` with `openclaw cron add`)\n - Timeout: 90s (`--timeout 90000`)\n - Session: isolated (`--session isolated`)\n - Flags: `--no-deliver`, `--light-context`\n - Message: a shell command that `cd`s to the skill dir, sets env inline, then runs `node scripts/whale-cron.mjs`. Required env in the cron message:\n - `POWERLOOM_API_KEY=`\n - `POWERLOOM_BDS_MCP_CALL_TIMEOUT_MS=120000`\n - `WHALE_CRON_THRESHOLD=10000` (default; only override if I asked for a different threshold)\n - Telegram env in the cron message β€” **only** if input (b) yielded both values:\n - `POWERLOOM_TELEGRAM_BOT_TOKEN=`\n - `POWERLOOM_TELEGRAM_CHAT_ID=`\n - Do NOT consult OpenClaw `channels.telegram`, `openclaw.json`, or any other config source for Telegram credentials β€” only use what I pasted in chat for input (b).\n\n5. Before the first run: `rm -f .powerloom/whale-cron-state.json` if you need a clean epoch cursor.\n Keep `.powerloom/pool-metadata-cache.json` across reinstalls unless debugging metadata.\n\n6. Set WHALE_CRON_STATE_FILE and WHALE_CRON_POOL_CACHE to paths outside the skill directory (e.g. in the workspace root) so they survive `openclaw skills install --force`.\n\nConstraints:\n- This flow uses an **existing** `sk_live_...` key only. Do NOT initiate any on-chain payment, and do NOT prompt for wallet credentials.\n- **Telegram credentials must be gathered from me in chat (or explicit opt-out received) BEFORE the cron job is created.** Asking me for `POWERLOOM_TELEGRAM_BOT_TOKEN` / `POWERLOOM_TELEGRAM_CHAT_ID` after running `openclaw cron add` and seeing the cron tick (with stdout-only alerts) is a known failure mode β€” fail the run and re-ask before cron creation.\n- Do NOT use OpenClaw config (`channels.telegram`, `openclaw.json`, etc.) as a fallback Telegram source β€” chat input only.\n- If the user later wants more credits, point them at `references/08-openclaw-one-shot.md` (wallet-funded pay-signup variant) or `node scripts/credits-topup.mjs` against the same key.\n- Use `bds_mpp_snapshot_allTrades` only (bounded batches). Do not add streaming trade tools.\n- Do NOT run the tracker as a background process β€” use OpenClaw cron only.\n- Do NOT show \"???\" for unknown tokens β€” resolve via the metadata tool or show the address.\n````\n\n---\n\n## Why this works without a wallet\n\n`scripts/whale-cron.mjs` only consumes `POWERLOOM_API_KEY` (via `lib/mcp.mjs`) plus the optional Telegram envs (`lib/powerloom-env.mjs` `telegramBotToken()` / `telegramChatId()`). The wallet/plan env getters in `lib/powerloom-env.mjs` are **only** read by `scripts/signup-pay.mjs` and `scripts/credits-topup.mjs` β€” both of which this prompt explicitly skips. The skill's `metadata.openclaw.requires.env` schema in `SKILL.md` lists wallet vars as **optional** (`optional_env`) for this exact reason.\n\nWhen the 2 free credits run out (~7200 epochs of data per credit on metered routes), upgrade in either of two ways without re-onboarding:\n\n- **Wallet-funded plan, in the agent**: paste the [wallet-funded one-shot](./08-openclaw-one-shot.md) β€” runs `signup-pay.mjs` and refreshes the API key.\n- **Top-up the existing key**: `node scripts/credits-topup.mjs` with `POWERLOOM_PLAN_ID`, `POWERLOOM_EVM_CHAIN_ID`, `POWERLOOM_TOKEN_SYMBOL`, and a funded wallet β€” adds credits to the same `sk_live_...`.\n\n---\n\n## Verification provenance (cron script + one-shot)\n\n**In `scripts/whale-cron.mjs` (already implemented):** each `bds_mpp_snapshot_allTrades` result carries `data.verification` (`cid`, `epochId`, `projectId`). The script reads that object once per poll and appends a **\"Verified on-chain\"** block (CID, epoch, project) to each formatted alert in `formatAlert` β€” it is not optional glue you add in the OpenClaw message; the one-shot above assumes this behavior. Free-key alerts carry the same verification block as wallet-funded alerts.\n\n**Independent check:** the MCP tool `verify_data_provenance` can confirm commitments using the same `cid` / `epoch_id` / `project_id` β€” see [`references/03-verification.md`](./03-verification.md) and the **Verify** row in `SKILL.md` (data table).\n\n---\n\n## Related files in this skill\n\n| Item | Location |\n|------|----------|\n| Cron entrypoint (incl. verification in alerts) | `scripts/whale-cron.mjs` |\n| Pre-flight credit check | `scripts/ensure-credits.mjs` |\n| Pay-signup (wallet-funded variant) | `scripts/signup-pay.mjs` |\n| Top-up (more credits, existing key) | `scripts/credits-topup.mjs` |\n| MCP + trade helpers | `lib/mcp.mjs`, `lib/trade-utils.mjs`, `lib/state.mjs` |\n| On-chain verification details | `references/03-verification.md` |\n| Wallet-funded one-shot variant | `references/08-openclaw-one-shot.md` |\n| Integrator rules | `SKILL.md` β†’ **Hosts & integrators** |\n\nSee also [`references/01-quickstart.md`](./01-quickstart.md) and [`references/06-troubleshooting.md`](./06-troubleshooting.md).\n\nArchive v0.2.5: 33 files, 52275 bytes\n\nFiles: package-lock.json (4617b), package.json (305b), README.md (6476b), recipes/defi-analyst.yaml (813b), recipes/token-flow.yaml (412b), recipes/whale-radar.yaml (751b), references/01-quickstart.md (1419b), references/02-tool-catalog.md (935b), references/03-verification.md (1037b), references/04-credit-budget.md (500b), references/05-data-market-scope.md (814b), references/06-troubleshooting.md (3592b), references/07-prompt-patterns.md (675b), references/08-openclaw-one-shot.md (8455b), references/09-openclaw-one-shot-free-key.md (8866b), scripts/credits-topup.mjs (6546b), scripts/defi-analyst.mjs (8252b), scripts/ensure-credits.mjs (1300b), scripts/lib/confirm-spend.mjs (2016b), scripts/lib/dispatch.mjs (1400b), scripts/lib/mcp.mjs (11542b), scripts/lib/powerloom-env.mjs (1667b), scripts/lib/recipe-config.mjs (690b), scripts/lib/state.mjs (1519b), scripts/lib/trade-utils.mjs (2134b), scripts/list-mcp-tools.mjs (488b), scripts/powerloom-mcp-client.mjs (644b), scripts/signup-pay.mjs (6462b), scripts/token-flow.mjs (4915b), scripts/whale-cron.mjs (9815b), scripts/whale-radar.mjs (4599b), SKILL.md (12658b), _meta.json (138b)\n\nFile v0.2.5:SKILL.md\n\n---\nname: powerloom-bds-univ3\ndescription: |\n Autonomous Uniswap V3 monitoring on consensus-backed data with onchain provenance.\n Every data point is finalized on-chain by Powerloom's DSV network and independently\n verifiable. Ships with Whale Radar, Token-Flow, and DeFi Analyst recipes.\n Free API key at bds-metering.powerloom.io/metering (2 credits, no wallet).\n Triggers on \"whale alert\", \"track trades\", \"all trades for\", \"by token\",\n \"Powerloom\", \"verify on-chain\", \"verified data\".\nversion: 0.2.5\nhomepage: https://bds-metering.powerloom.io\nrepository: https://github.com/powerloom/powerloom-bds-univ3\ntags:\n - defi\n - uniswap\n - ethereum\n - on-chain\n - verifiable\n - consensus\n - agent\nmetadata:\n openclaw:\n emoji: \"πŸ¦„\"\n requires:\n bins: [\"node\"]\n env:\n # Only POWERLOOM_API_KEY is mandatory at install time. The free-key path\n # (references/09-openclaw-one-shot-free-key.md) needs nothing else from\n # this skill's perspective. Wallet/plan envs below are optional and only\n # consumed by scripts/signup-pay.mjs and scripts/credits-topup.mjs.\n - POWERLOOM_API_KEY\n optional_env:\n # Wallet-funded variants (signup-pay or credits-topup) β€” only required\n # if the user invokes those scripts. See references/08-openclaw-one-shot.md.\n - POWERLOOM_EVM_PRIVATE_KEY\n - POWERLOOM_EVM_RPC_URL\n - POWERLOOM_EVM_CHAIN_ID\n - POWERLOOM_PLAN_ID\n - POWERLOOM_TOKEN_SYMBOL\n # Dispatch + transport overrides β€” never required.\n - POWERLOOM_MCP_URL\n - POWERLOOM_TELEGRAM_BOT_TOKEN\n - POWERLOOM_TELEGRAM_CHAT_ID\n - POWERLOOM_DISCORD_WEBHOOK_URL\n - POWERLOOM_BDS_MCP_CALL_TIMEOUT_MS\n - POWERLOOM_BDS_MCP_DEBUG\n - POWERLOOM_METERING_BASE_URL\n - POWERLOOM_AGENT_NAME\n - POWERLOOM_EMAIL\n---\n\n# Powerloom BDS β€” Uniswap V3\n\n## Install\n\n> **Two onboarding paths.**\n>\n> **Free** β€” sign up at [`bds-metering.powerloom.io/metering`](https://bds-metering.powerloom.io/metering) (enter email + agent name, complete Turnstile, get `sk_live_...` immediately β€” no CLI, no wallet, 2 free credits). Alternatively, `bds-agent signup` runs the same flow from the terminal. Then paste [`references/09-openclaw-one-shot-free-key.md`](references/09-openclaw-one-shot-free-key.md) into OpenClaw. Sets `POWERLOOM_API_KEY` and a Whale Radar cron. Nothing else needed.\n>\n> **Wallet-funded** β€” paste [`references/08-openclaw-one-shot.md`](references/08-openclaw-one-shot.md) and `scripts/signup-pay.mjs` runs an autonomous on-chain payment for a 10-credit plan in the same prompt.\n>\n> **⚠️ WARNING β€” wallet-funded path only:** `signup-pay.mjs` and `credits-topup.mjs` need an EVM private key to broadcast on-chain payments. Use a **burner wallet** with limited funds dedicated to this purpose. Never use a wallet holding significant assets or with extensive transaction history for agentic setups. The free-key path **does not** require any wallet credentials.\n\n**Contract:** [bds-agenthub-billing-metering](https://github.com/powerloom/bds-agenthub-billing-metering). **ClawHub** users only need a **single origin** (default [bds-metering.powerloom.io](https://bds-metering.powerloom.io))β€” **`bds-agent` commands are optional**; they are a reference CLI for the same JSON bodies you can send with `curl` + a wallet or `ethers`.\n\n### Metering HTTP (authoritative)\n\n| What | How |\n|------|-----|\n| List SKUs | `GET {BASE}/credits/plans` β€” no auth. Choose a plan row: `id`, `chain_id`, `token_symbol` (and note `payment_kind`: ERC-20 vs native / CGT). **`chains[].rpc_url`** is a **public** JSON-RPC hint only when the metering deployment sets it; it may be **empty** β€” use **`POWERLOOM_EVM_RPC_URL`** for wallet / script calls in that case. |\n| New key, wallet-only | **Pay-signup:** `POST {BASE}/signup/pay/quote` β†’ pay on chain β†’ `POST {BASE}/signup/pay/claim` with `signup_nonce` + `tx_hash`. Returns `api_key`. |\n| New key, browser | Human device flow on [`{BASE}/metering`](https://bds-metering.powerloom.io/metering) (same service). Enter email + agent name, complete Turnstile, get `sk_live_...` immediately. |\n| More credits, existing key | `POST {BASE}/credits/topup` with `Authorization: Bearer sk_live_…` and tx / plan (not the pay-signup endpoints). |\n| Check balance | `GET {BASE}/credits/balance` with `Authorization: Bearer …` |\n\n`{BASE}` is **`POWERLOOM_METERING_BASE_URL`**, e.g. `https://bds-metering.powerloom.io`. Set **`POWERLOOM_API_KEY`** to the `sk_live_...` you get after pay-signup, device signup, or copy from the dashboard.\n\n### OpenClaw env vars (mandatory vs optional)\n\n| Field | When required | Role |\n|-------|---------------|------|\n| `POWERLOOM_API_KEY` | **Always** β€” only mandatory env at install time | `sk_live_...` from [`bds-metering.powerloom.io/metering`](https://bds-metering.powerloom.io/metering) or `bds-agent signup` (free path) or `signup-pay.mjs` claim (wallet path) |\n| `POWERLOOM_EVM_PRIVATE_KEY` | Wallet-funded path only | Payer wallet β€” **use a burner wallet** |\n| `POWERLOOM_EVM_RPC_URL` | Wallet-funded path only | JSON-RPC for that chain |\n| `POWERLOOM_EVM_CHAIN_ID` | Wallet-funded path only | Must match the plan's `chain_id` |\n| `POWERLOOM_PLAN_ID` | Wallet-funded path only | e.g. `launch_10_pl_power_cgt` from `GET /credits/plans` |\n| `POWERLOOM_TOKEN_SYMBOL` | Wallet-funded path only | e.g. `POWER` (must match that row) |\n\nThe schema in `metadata.openclaw.requires.env` lists only `POWERLOOM_API_KEY` as required; the wallet/plan envs above sit in `optional_env` and are read only by `scripts/signup-pay.mjs` (new key, pay-signup) and `scripts/credits-topup.mjs` (more credits on an existing key). Free-key flows pass straight through.\n\n### Reference client: `bds-agent` (optional)\n\n[docs/USER_GUIDE.md](https://github.com/powerloom/bds-agent-py/blob/main/docs/USER_GUIDE.md) in **bds-agent-py** has the end-to-end order: **Metering service API** table β†’ pay-signup β†’ device β†’ top-up. One-liner sequence:\n\n1. `bds-agent credits plans` β€” same as `GET /credits/plans`\n2. `bds-agent credits setup-evm` β€” writes `~/.config/bds-agent/profiles/.evm.env`\n3. `bds-agent signup-pay --plan-id … --chain-id … --token-symbol …` β€” implements quote / broadcast / claim (including **native** `payment_kind` plans)\n\n### This repo: Node scripts (no Python, no `bds-agent` required)\n\n| Script | What it does |\n|--------|----------------|\n| `node scripts/signup-pay.mjs` | **New** key: pay-signup (quote β†’ on-chain pay β†’ claim). Uses **`quote.payment_kind`**: `native_value` = send **native/CGT** (`tx.value` to `recipient`); `erc20` = token **`transfer`**. For **POWER (7869) CGT** plans, metering uses **`native_value`** β€” do not force ERC-20. **Broadcast protection:** interactive shells prompt `CONFIRM`; non-interactive shells require **`--yes`** (preferred for OpenClaw β€” ephemeral argv, do not persist in skill env) **or** `POWERLOOM_SIGNUP_PAY_CONFIRM=yes` (CI one-shot only). **`--dry-run`** prints quote summary and exits without sending a tx. |\n| `node scripts/credits-topup.mjs` | **More** credits: uses existing **`POWERLOOM_API_KEY`**, fetches `GET /credits/plans`, matches **`POWERLOOM_PLAN_ID` + `POWERLOOM_EVM_CHAIN_ID` + `POWERLOOM_TOKEN_SYMBOL`**, sends **ERC-20** or **native** per `payment_kind`, then **`POST /credits/topup`**. Same confirmation gate as signup-pay (**`--yes`** preferred; **`POWERLOOM_CREDITS_TOPUP_CONFIRM=yes`** for CI one-shot only; TTY `CONFIRM`). **`--dry-run`** prints summary only. Set **`POWERLOOM_EVM_RPC_URL`** when **`chains[].rpc_url`** is empty or you need a specific node (the API never exposes the server's private RPC). |\n| `node scripts/ensure-credits.mjs` | **Balance** only (`GET /credits/balance`); no purchase. |\n\n`npm install` once (adds `ethers`).\n\n**Optional env (signup script):** `POWERLOOM_METERING_BASE_URL`, `POWERLOOM_AGENT_NAME`, `POWERLOOM_EMAIL` (see [metering README](https://github.com/powerloom/bds-agenthub-billing-metering#readme)).\n\n### After you have a key β€” more credits (top-up)\n\n**Spec:** `POST {BASE}/credits/topup` with `Authorization: Bearer` and JSON `{ \"plan_id\", \"chain_id\", \"tx_hash\" }` after an on-chain payment that matches the plan. **In this repo:** `node scripts/credits-topup.mjs`. **Reference CLI:** [USER_GUIDE](https://github.com/powerloom/bds-agent-py/blob/main/docs/USER_GUIDE.md) (EVM `credits topup` / Tempo per deployment). **Check balance:** `node scripts/ensure-credits.mjs`.\n\n**Default MCP endpoint:** `https://bds-mcp.powerloom.io/sse` β€” override with `POWERLOOM_MCP_URL` if needed.\n\nGeneric tool runner: `node scripts/powerloom-mcp-client.mjs '{}'`\n\n## Common tasks β†’ which tool\n\n| Task phrase | Tool(s) |\n|-------------|---------|\n| Track **all swaps for token X** (multi-pool) | **Token-Flow** recipe (`bds_mpp_snapshot_trades_pool_address` per pool) or `bds_mpp_snapshot_allTrades` via **`whale-cron.mjs`** |\n| **Whale** / USD threshold | **`whale-cron.mjs`** (all pools, bounded) or **`whale-radar.mjs`** (fixed pool list, per-pool snapshots) |\n| **One pool only** | `bds_mpp_snapshot_trades_pool_address` after `bds_mpp_token_token_address_pools` or `bds_mpp_dailyActivePools` |\n| **Verify** on-chain | `verify_data_provenance` with `cid`, `epoch_id`, `project_id` from API β€” never substitute block for epoch |\n\n**Timeouts:** default `POWERLOOM_BDS_MCP_CALL_TIMEOUT_MS=60000`. Raise it (e.g. **120000**) if `bds_mpp_snapshot_allTrades` times out under backlog.\n\n## Recipes (supported surface)\n\nPre-built scripts + `recipes/*.yaml` defaults β€” prefer these over ad-hoc scripts on weaker models. **This skill does not call streaming catalog tools** (`bds_mpp_stream_*`); every recipe uses **bounded snapshot** MCP calls so runs fit cron and agent sandboxes.\n\n**Cron default:** `whale-radar.mjs`, `token-flow.mjs`, and `defi-analyst.mjs` each run **one bounded round** and **exit** (safe for OpenClaw cron). Pass **`--daemon`** to repeat with `heartbeat.interval_seconds` between rounds (local / long-running only).\n\n| Recipe / entrypoint | Script |\n|---------------------|--------|\n| Whale Radar (fixed pools) | `node scripts/whale-radar.mjs` β€” one round over `poll_fallback_pools`; **`--daemon`** for repeat |\n| Whale alerts (cron, all pools) | `node scripts/whale-cron.mjs` β€” **bounded** one-shot: `bds_mpp_snapshot_allTrades` + pool metadata; alerts include **snapshot** `cid` / epoch / project from `data.verification` β€” see **Verification provenance** in `references/08-openclaw-one-shot.md` |\n| Token-Flow | `node scripts/token-flow.mjs` (`--token 0x...`) β€” one round per pool for that token; **`--daemon`** for repeat |\n| DeFi Analyst | `node scripts/defi-analyst.mjs` β€” one round: **multi-pool** (`bds_mpp_snapshot_allTrades` + all-pools volume) or `filters.scope: single_pool`; **`--daemon`** for repeat |\n\n## Model guidance\n\nRecipes produce the same stdout/Telegram output regardless of model. Ad-hoc \"compose your own\" prompts work best on GPT-4–class or GLM-5+; weaker local models may collapse multi-pool prompts onto one pool β€” **use the Token-Flow recipe** instead.\n\n## Hosts & integrators (OpenClaw, cron, heartbeats)\n\n**OpenClaw \"one shot\" setups** β€” pick the variant that matches the user's onboarding state:\n\n| Variant | Use when | Reference |\n|---------|----------|-----------|\n| Free-key cron | The user already has `sk_live_...` from [`bds-metering.powerloom.io/metering`](https://bds-metering.powerloom.io/metering) or `bds-agent signup` (2 free credits, no wallet) | [`references/09-openclaw-one-shot-free-key.md`](references/09-openclaw-one-shot-free-key.md) |\n| Pay-signup + cron | The user wants autonomous wallet-funded onboarding for a 10-credit plan in the same prompt | [`references/08-openclaw-one-shot.md`](references/08-openclaw-one-shot.md) |\n\nBoth prompts produce the same `Whale Radar` cron firing `node scripts/whale-cron.mjs` every 15s with onchain verification surfaced in every alert. Agents should default to the free-key variant unless the user explicitly asks for autonomous on-chain payment.\n\n**Scheduled / cron-style runs:** Prefer **`whale-cron.mjs`**, **`whale-radar.mjs`**, **`token-flow.mjs`**, or **`defi-analyst.mjs`** with **no** `--daemon` so each invocation **exits**. **Streaming trade tools** (`bds_mpp_stream_*`) are **not** used by this skill.\n\n## References\n\nSee `references/` for quickstart, full tool table, verification, credit budget, scope, troubleshooting, prompt patterns, **`08-openclaw-one-shot.md`** (copy-paste OpenClaw runbook), and cron notes in quickstart + tool catalog.\n\nFile v0.2.5:README.md\n\n# Powerloom BDS β€” Uniswap V3 (ClawHub skill)\n\n## Autonomous Uniswap V3 monitoring + onchain provenance verification, in minutes. Decentralized data, not trust-me data.\n\nEvery data point this skill fetches is finalized onchain by Powerloom's decentralized sequencer-validator network. The `verify_data_provenance` tool compares API CIDs to onchain commitments so alerts can carry a cryptographic receipt, not a vendor's word.\n\n## Recipes\n\n- **Whale Radar** β€” USD-threshold alerts: **`bds_mpp_snapshot_trades_pool_address`** for each pool in `poll_fallback_pools`. For **cron / OpenClaw heartbeats** over **all** pools in one bounded batch, use **`node scripts/whale-cron.mjs`** (`bds_mpp_snapshot_allTrades` + pool metadata).\n- **Token-Flow** β€” all swaps touching a configured token (default USDC) across pools derived at runtime.\n- **Autonomous DeFi Analyst** β€” default **multi-pool** `bds_mpp_snapshot_allTrades` + all-pools token volume; set **`filters.scope: single_pool`** in `recipes/defi-analyst.yaml` for single-pool snapshots only.\n\n## Integrators (OpenClaw, cron)\n\n**End-to-end one-shot prompts** β€” pick by onboarding state:\n\n| Variant | Use when | Reference |\n|---------|----------|-----------|\n| Free-key cron | You already have `sk_live_...` from `bds-agent signup` (2 free credits, no wallet) | **`references/09-openclaw-one-shot-free-key.md`** |\n| Pay-signup + cron | You want autonomous wallet-funded onboarding for a 10-credit plan in the same prompt | **`references/08-openclaw-one-shot.md`** |\n\n**Default behavior:** `whale-radar.mjs`, `token-flow.mjs`, and `defi-analyst.mjs` each run **one bounded round** and **exit** (safe for cron). Use **`--daemon`** only if you want a local repeat loop (`heartbeat.interval_seconds` between rounds).\n\nFor **scheduled heartbeats**, prefer **`whale-cron.mjs`** (exits) or the recipe scripts **without** `--daemon`. This repo does not ship streaming trade consumption.\n\n## Setup\n\n```bash\ncd powerloom-bds-univ3\nnpm install\nexport POWERLOOM_API_KEY=sk_live_...\nnode scripts/ensure-credits.mjs\n```\n\n**Where to get `POWERLOOM_API_KEY`:**\n\n- **Free** (no wallet, 2 credits): `bds-agent signup` β€” browser device flow on the metering service. Same `sk_live_...` works against this skill, the hosted MCP server, and any pay-signup top-up later.\n- **Wallet-funded** (10-credit plan): `node scripts/signup-pay.mjs --dry-run` (quote summary only), then **`node scripts/signup-pay.mjs --yes`** once after verifying stderr output β€” prefer argv over env so confirmation bypass is **not** persisted in OpenClaw skill config. CI may use `POWERLOOM_SIGNUP_PAY_CONFIRM=yes` for a single invocation only. **Native or ERC-20** per `quote.payment_kind` (POWER CGT on 7869 = native).\n- **More credits, existing key**: `node scripts/credits-topup.mjs` β€” same `--dry-run` β†’ **`--yes`** pattern (or one-shot env for CI only). See **`SKILL.md`**.\n\nOptional: `POWERLOOM_TELEGRAM_BOT_TOKEN`, `POWERLOOM_TELEGRAM_CHAT_ID`, and `dispatch.channel: telegram` in `recipes/*.yaml`.\n\n## Links (metering service)\n\nOne deploy (`npm run build` + `npm start` on **`bds-agenthub-billing-metering`**) serves both:\n\n- **Agent signup (CLI / API)** β€” origin only: [bds-metering.powerloom.io](https://bds-metering.powerloom.io) (`BDS_AGENT_SIGNUP_URL` / `bds-agent signup --base-url …`).\n- **Browser signup + billing UI** β€” [bds-metering.powerloom.io/metering](https://bds-metering.powerloom.io/metering)\n\n- Hosted MCP SSE: `https://bds-mcp.powerloom.io/sse`\n\n## Naming (ClawHub skill vs MCP tools)\n\n| What | Name |\n|------|------|\n| ClawHub / OpenClaw skill folder & slug | **`powerloom-bds-univ3`** |\n| MCP tools on the hosted server | **`bds_mpp_*`**, **`get_credit_balance`**, **`verify_data_provenance`** β€” there is **no** tool named `bds_univ3`. |\n\nTo print the live tool list from the API (same handshake as `callTool`):\n\n```bash\nexport POWERLOOM_API_KEY=sk_live_...\nnode scripts/list-mcp-tools.mjs\n```\n\n## Test locally (without publishing to ClawHub)\n\nPublishing is optional for trying the **scripts** and **SKILL.md** instructions:\n\n1. **Scripts only** β€” From this directory, with `POWERLOOM_API_KEY` set, run `node scripts/ensure-credits.mjs`, `node scripts/list-mcp-tools.mjs` (proves tool names), `node scripts/powerloom-mcp-client.mjs get_credit_balance '{}'`, or a recipe (`whale-radar.mjs`, etc.). That validates MCP wiring end-to-end against the hosted server.\n\n2. **OpenClaw / ClawHub** β€” If **`skills list`** and the **dashboard** show **`powerloom-bds-univ3`** as **ready**, the skill is **on disk and registered**. That is not the same as β€œthe main chat always loads **`SKILL.md`** into the model on every turn.” If chat still acts blind, check your OpenClaw **agent** actually **uses** that skill (per-agent skill selection / defaults), then **new session** after changes. The reliable execution path is still **`node scripts/…`** with **`POWERLOOM_API_KEY`**; chat is best-effort unless you also wire **BDS MCP** for tools in the tool list.\n\n - **Registry:** `clawhub install powerloom-bds-univ3` only pulls **published** builds. **Local dev:** copy this repo’s root into **`…/workspace/skills/powerloom-bds-univ3/`** with **`SKILL.md`** at the folder root, set **`POWERLOOM_API_KEY`** in `openclaw.json` skill `entries`, restart the gateway.\n - **Compose / `OPENCLAW_WORKSPACE_DIR`:** The stack usually reads a **`.env` file next to `docker-compose.yml`**. [Docker Compose](https://docs.docker.com/compose/how-tos/environment-variables/variable-interpolation/) substitutes **`${OPENCLAW_WORKSPACE_DIR}`** from: that `.env` file, or **exported** variables in the shell you run `docker compose` from, or a **`.env` override** your vendor documents. It is not magic β€” if unset, the mount line can be wrong or empty. Set it to the **host** path that should map to `…/workspace` in the container (often your user’s `…/.openclaw/workspace` as an **absolute** path). Check `docker compose config` to see the resolved value.\n\n Docker bind mounts, **`ENOENT`**, symlinks, UI quirks: **`references/06-troubleshooting.md`**.\n\n3. **After publish** β€” `clawhub install powerloom-bds-univ3` (or the slug you published).\n\n## Publish (maintainers)\n\n```bash\nnpx clawhub login\nnpx clawhub publish . --slug powerloom-bds-univ3 --version 0.1.0\n```\n\n## Repository\n\nSource: [github.com/powerloom/powerloom-bds-univ3](https://github.com/powerloom/powerloom-bds-univ3) (mirror this folder into that org repo).\n\nFile v0.2.5:_meta.json\n\n{\n \"ownerId\": \"kn7a3wb3bny97qvtprbgh9cxe185fms0\",\n \"slug\": \"powerloom-bds-univ3\",\n \"version\": \"0.2.5\",\n \"publishedAt\": 1778556263263\n}\n\nFile v0.2.5:references/01-quickstart.md\n\n# Quickstart (~10 minutes)\n\n1. **Get an API key** β€” **CLI / API:** metering origin [bds-metering.powerloom.io](https://bds-metering.powerloom.io) (`bds-agent signup`; see [agent guide](https://github.com/powerloom/bds-agent-py/blob/main/docs/USER_GUIDE.md)). **Browser:** signup and top-ups at [bds-metering.powerloom.io/metering](https://bds-metering.powerloom.io/metering).\n2. **Export** `POWERLOOM_API_KEY=sk_live_...` in the environment OpenClaw uses (or your shell profile).\n3. **Optional** β€” default MCP URL is `https://bds-mcp.powerloom.io/sse`. Override with `POWERLOOM_MCP_URL` if directed.\n4. **Check credits**: `node scripts/ensure-credits.mjs` β€” should print balance JSON and exit 0.\n5. **OpenClaw / cron** β€” for **one-shot schedulers** (recommended), use **`node scripts/whale-cron.mjs`** and the full copy-paste flow in **`references/08-openclaw-one-shot.md`**. For a **fixed pool list** and local poll loop, use **`whale-radar.mjs`** (per-pool snapshots only).\n6. **Run a recipe** (stdout first):\n - Whale cron (bounded, all pools): `node scripts/whale-cron.mjs`\n - Whale Radar (fixed pools, poll): `node scripts/whale-radar.mjs`\n - Token-Flow: `node scripts/token-flow.mjs`\n - DeFi Analyst (one round, cron): `node scripts/defi-analyst.mjs`\n7. **Telegram** β€” set `POWERLOOM_TELEGRAM_BOT_TOKEN` and `POWERLOOM_TELEGRAM_CHAT_ID`, set `dispatch.channel` to `telegram` in the recipe yaml.\n\nFile v0.2.5:references/02-tool-catalog.md\n\n# BDS MCP tool catalog (representative)\n\nAll calls are metered unless noted. **Defaults:** `POWERLOOM_BDS_MCP_CALL_TIMEOUT_MS=60000` (raise for large `bds_mpp_snapshot_allTrades` responses under backlog, e.g. `120000`).\n\n**Skill note:** `powerloom-bds-univ3` recipes use **snapshot** tools only (`bds_mpp_snapshot_*`). Streaming catalog tools exist on the hosted MCP server for direct/advanced use but are **not** invoked by shipped scripts.\n\n| Tool | What | Typical latency | Skill usage |\n|------|------|-----------------|-------------|\n| `bds_mpp_snapshot_allTrades` | One-shot all pools (bounded batch) | 8–45s | `whale-cron.mjs`, DeFi Analyst multi |\n| `bds_mpp_snapshot_trades_pool_address` | One pool snapshot | 2–15s | `whale-radar.mjs`, `token-flow.mjs` |\n| `bds_mpp_stream_allTrades` | Streaming batches (long-lived upstream) | varies | **Not used by skill** |\n\nSee the live server’s `tools/list` for the full catalog.\n\nFile v0.2.5:references/03-verification.md\n\n# `verify_data_provenance`\n\nCompares a snapshot **CID** to on-chain `maxSnapshotsCid` for `(data_market, project_id, epoch_id)` via the Powerloom protocol state contract.\n\n**Inputs:** `cid` (string), `epoch_id` (integer), `project_id` (string). Optional `data_market` override.\n\n**Hosted MCP** runs the `eth_call` on the server (configured RPC is **not** included in the tool response). If the server’s RPC is unset, the tool returns a clear configuration error β€” not a silent pass. For a **local** second check, use the same `cid` / `epoch_id` / `project_id` with your own provider **`POWERLOOM_EVM_RPC_URL`** (e.g. public Powerloom JSON-RPC) and the documented ProtocolState / DataMarket addresses β€” do not expect MCP to echo an RPC URL.\n\n**Metering** `GET /credits/plans` exposes **`chains[].rpc_url`** only as an optional **public** hint; it can be empty.\n\n**In alerts:** only print verification lines when `cid`, `epoch_id`, and `project_id` are all known from the API response. Do not substitute block numbers for epoch IDs.\n\nFile v0.2.5:references/04-credit-budget.md\n\n# Credit budget (targets β€” validate in dry run)\n\n| Recipe | Mode | Steady credits/hour (target) | Free tier (~100 cr) |\n|--------|------|------------------------------|---------------------|\n| Whale Radar (poll) | per-pool snapshots | TBD | TBD |\n| Token-Flow | per-pool snapshots | TBD | TBD |\n| Whale cron | bounded `snapshot_allTrades` | TBD | TBD |\n| DeFi Analyst | 5m + p=0.2 verify | ~40 | ~2.5 h |\n\nUpdate this table after measured burn from `get_credit_balance` deltas during a 1-hour run.\n\nFile v0.2.5:references/05-data-market-scope.md\n\n# Data market scope (ETH mainnet Uniswap V3)\n\n## Canonical worked example (single pool)\n\n| Pool | Address | Fee tier |\n|------|---------|----------|\n| WETH/USDC | `0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640` | 0.05% |\n\nSome fee tiers (e.g. 0.3% WETH/USDC) may **not** be indexed in this data market β€” check `bds_mpp_pool_pool_address_metadata` / `bds_mpp_dailyActivePools` before assuming coverage.\n\n## Multi-pool / token-first\n\n- **All pools / all trades (bounded):** `bds_mpp_snapshot_allTrades` (skill + cron). Streaming variants may exist on MCP for direct use outside the skill.\n- **Token-scoped:** `bds_mpp_token_token_address_pools`, `bds_mpp_tradeVolumeAllPools_token_address_time_interval`.\n- **Single pool:** `bds_mpp_snapshot_trades_pool_address` β€” use only when the user explicitly wants one pool.\n\nFile v0.2.5:references/06-troubleshooting.md\n\n# Troubleshooting\n\n| Symptom | Cause | Fix |\n|---------|--------|-----|\n| Pay-signup \"recipient did not match\" / wrong first tx (POWER 7869) | **`signup-pay.mjs` used ERC-20** while plan is **`payment_kind: native_value`** (CGT) | **Update** the script from the current skill repo, or use a flow that checks **`quote.payment_kind`**: native = `sendTransaction({ to, value })` only, not `token.transfer`. `credits-topup.mjs` already branches on `payment_kind`. |\n| HTTP 401 | Bad or missing API key | Re-copy key from the metering dashboard ([bds-metering.powerloom.io/metering](https://bds-metering.powerloom.io/metering)) or your CLI profile; fix `POWERLOOM_API_KEY`. |\n| HTTP 402 | Credits exhausted | Top up; reduce recipe cadence; run `ensure-credits.mjs` before crons. |\n| HTTP 429 | Rate limit | Increase heartbeat interval; for **cron** schedules prefer **poll** (fewer parallel calls) instead of many snapshot fan-outs. |\n| Tool timeout | Backlog / slow finalization | Raise `POWERLOOM_BDS_MCP_CALL_TIMEOUT_MS`; reduce snapshot scope (`max_events` / fewer pools). |\n| Empty snapshot | Idle chain / catch-up | Wait; check `from_epoch` in state file (cron / DeFi Analyst). |\n| Wrong verify | Confused epoch vs block | Use `epoch_id` from snapshot / `verification` payload, not `blockNumber`. |\n| Odd outputs after model swap | OpenClaw context mismatch | Restart OpenClaw; recipes are script-driven β€” state files live under `.powerloom/`. |\n| Skill β€œready” in `skills list` / dashboard but main chat ignores it | **Install β‰  injection.** The chat agent may not attach every skill to every session; per-agent config, a **new** session after enabling the skill, or product limits on which skills the model sees. | Enable the skill for **that** agent; start a new chat; add **BDS MCP** in config if you need tools in the tool list. For deterministic behavior, run **`node scripts/…`**. |\n| `OPENCLAW_WORKSPACE_DIR` seems wrong in Docker | Compose interpolates `${VAR}` from a **`.env` next to `docker-compose.yml`**, the shell **environment**, or an `env_file` the compose file references β€” whatever OpenClaw’s install template ships. | Set **`OPENCLAW_WORKSPACE_DIR=`** in that `.env` to the **host** absolute path for workspace (e.g. `/Users/you/.openclaw/workspace`). Run **`docker compose config`** to verify substitution; **recreate** containers after changing `.env` (`up -d` / `up --force-recreate` as needed). |\n| `NO_SESSION` / β€œsession_id never arrived” | SSE bootstrap did not expose a parseable `session_id` (UUID vs hex, proxy, or stale client) | Confirm `POWERLOOM_MCP_URL` ends with `/sse` reachable from the runtime (e.g. Docker). Set **`POWERLOOM_BDS_MCP_DEBUG=1`** once to log the first bytes of the SSE stream in the error. |\n| `ENOENT` on `.../skills/.../SKILL.md` (OpenClaw in Docker) | The **container** does not have that file at the path the process checks. Common: wrong **host** tree for **`OPENCLAW_WORKSPACE_DIR`** (compose often mounts `${OPENCLAW_WORKSPACE_DIR}:/home/node/.openclaw/workspace` β€” skills belong under that dir’s `skills/` on the host, not a second guess at `~` if the env points elsewhere), nested slug folder, or symlink outside the mount. | **In the failing container:** `ls -la /home/node/.openclaw/workspace/skills/powerloom-bds-univ3/SKILL.md` (official compose) **or** `ls` under `/app/skills/...` if your error path uses `/app`. Copy/rsync the skill to the **host path** that maps to the shown prefix, with **`SKILL.md` at the slug root**; restart the gateway. `EACCES` (rare): `chmod -R a+rX` on the skill tree. |\n\nFile v0.2.5:references/07-prompt-patterns.md\n\n# Prompt patterns β†’ tools\n\n| User intent | Primary path |\n|-------------|--------------|\n| β€œAll USDC swaps”, β€œevery trade for token X” | **Token-Flow** (`token-flow.yaml`) β€” per-pool snapshots; or `bds_mpp_snapshot_allTrades` via **`whale-cron.mjs`** for all pools in one batch. |\n| β€œWhale”, β€œabove $X” | **`whale-cron.mjs`** (all pools, bounded) or **`whale-radar.mjs`** (fixed pool list). |\n| β€œOne pool” | `bds_mpp_snapshot_trades_pool_address` after resolving the pool. |\n| β€œIs this CID real?” | `verify_data_provenance` with `cid`, `epoch_id`, `project_id`. |\n\nThe skill does **not** ship streaming trade consumption; use snapshot tools only.\n\nFile v0.2.5:references/08-openclaw-one-shot.md\n\n# OpenClaw: pay-signup + whale cron (one-shot prompt)\n\nUse this as a **single agent message** after installing the skill from ClawHub. It matches how the skill is meant to run: **bounded** `bds_mpp_snapshot_allTrades` via `scripts/whale-cron.mjs`. The skill does **not** use streaming trade tools.\n\n---\n\n## Copy-paste prompt\n\n````\nInstall the skill \"πŸ¦„ Powerloom Uniswap V3 timeseries data\" (powerloom-bds-univ3) from ClawHub.\nAfter install, run npm install in the skill directory.\n\n**REQUIRED INPUTS β€” gather BOTH from me in chat BEFORE running `signup-pay.mjs` or creating any cron job. STOP and ask if either is missing. Do NOT proceed past this section with values unresolved. Asking me for any of these AFTER the cron job is created is a failure mode β€” re-ask BEFORE cron creation.**\n\na. **Payer wallet private key** β€” paste your EVM private key for the funded wallet that will pay 50 $POWER for the credit plan. **Use a burner wallet only** β€” never a wallet holding significant assets or with extensive transaction history. This key is consumed by `node scripts/signup-pay.mjs` and stored in OpenClaw env as `POWERLOOM_EVM_PRIVATE_KEY`.\n\nb. **Telegram alerts** β€” ask explicitly: \"Do you want Telegram alerts for whale swaps? If yes, paste your `POWERLOOM_TELEGRAM_BOT_TOKEN` and `POWERLOOM_TELEGRAM_CHAT_ID`. If no, type 'skip' and alerts will print to stdout only.\"\n - If I give you both tokens β†’ use them in the cron env (step 5 below).\n - If I explicitly say \"skip\" / \"no Telegram\" / \"stdout only\" β†’ proceed without TG envs and tell me clearly in the final cron summary that alerts will only print to stdout (the cron `--no-deliver` flag means OpenClaw's chat won't see them either).\n - Do NOT silently default to \"stdout is fine.\" Either both TG values, or an explicit opt-out.\n - Do NOT look up TG credentials from any OpenClaw config source (`channels.telegram`, `openclaw.json`, etc.) β€” only use what I paste in this conversation.\n\nOnce (a) and (b) are resolved in chat, proceed with the steps below.\n\nThen set up pay-signup and a whale radar cron. Details:\n\n1. PLAN: launch_10_pl_power_cgt (POWER native on chain 7869, rpc-v2.powerloom.network)\n2. Pay-signup using `scripts/signup-pay.mjs` with the private key from input (a):\n - **Recommended:** run `node scripts/signup-pay.mjs --dry-run` first β€” prints quote summary (recipient, amount_atomic, chain, payment_kind) to stderr; paste into chat so I can confirm values against metering UI / `/credits/plans`.\n - **Broadcast (non-interactive):** run `node scripts/signup-pay.mjs --yes` as a **one-off shell command** after review β€” **do not** persist `--yes` or any confirmation bypass inside OpenClaw long-lived skill env (`skills.entries.*.env`). CI operators may instead use `POWERLOOM_SIGNUP_PAY_CONFIRM=yes` for a single invocation; avoid leaving that variable set in autonomous sessions.\n - **TTY:** omit `--yes`; the script prompts `CONFIRM` interactively.\n Non-interactive shells refuse to broadcast without `--yes` / `POWERLOOM_SIGNUP_PAY_CONFIRM=yes` β€” this is intentional broadcast protection.\n `signup-pay.mjs` uses `quote.payment_kind`: `native_value` β†’ `sendTransaction({ value })`; `erc20` β†’ `token.transfer()`.\n3. After signup, set the `sk_live_...` API key and all six env vars in OpenClaw under\n `skills.entries.powerloom-bds-univ3.env.*`:\n `POWERLOOM_EVM_PRIVATE_KEY` (from input a), `POWERLOOM_EVM_RPC_URL`, `POWERLOOM_EVM_CHAIN_ID`, `POWERLOOM_PLAN_ID`, `POWERLOOM_TOKEN_SYMBOL`, `POWERLOOM_API_KEY` (from `signup-pay.mjs` claim output).\n Plus, if input (b) yielded values: `POWERLOOM_TELEGRAM_BOT_TOKEN`, `POWERLOOM_TELEGRAM_CHAT_ID`.\n If the schema expects strings, pass `POWERLOOM_EVM_CHAIN_ID` as a quoted string (e.g. `\"7869\"`).\n4. `scripts/whale-cron.mjs` should:\n - Use `lib/mcp.mjs` `callTool()` for all MCP calls (SSE handshake, not raw HTTP).\n - Use `lib/trade-utils.mjs` `flattenAllTradesFromSnapshot()` to parse the snapshot.\n - Response shape: `result.data.tradeData` = `{ poolAddr: { trades: [...] } }`.\n - Resolve pool token names with `bds_mpp_pool_pool_address_metadata` per unknown pool;\n cache in `.powerloom/pool-metadata-cache.json` (override with `WHALE_CRON_POOL_CACHE`).\n - Verification: `result.data.verification` = `{ cid, epochId, projectId }` β€” surface in alerts (e.g. βœ…).\n - Telegram: `parse_mode: MarkdownV2` with full escaping, or plain-text fallback.\n - If the script is missing or broken, rebuild using the skill’s `lib/*` helpers only.\n5. Create an OpenClaw cron job β€” **only after** REQUIRED INPUTS (a) and (b) above are fully resolved in chat AND `signup-pay.mjs` has produced the API key:\n - Name: e.g. \"Whale Radar\"\n - Schedule: e.g. every 15s (`--every 15s` with `openclaw cron add`)\n - Timeout: 90s (`--timeout 90000`)\n - Session: isolated (`--session isolated`)\n - Flags: `--no-deliver`, `--light-context`\n - Message: a shell command that `cd`s to the skill dir, sets env inline, then runs `node scripts/whale-cron.mjs`. Required env in the cron message:\n - `POWERLOOM_API_KEY=`\n - `POWERLOOM_BDS_MCP_CALL_TIMEOUT_MS=120000`\n - `WHALE_CRON_THRESHOLD=10000` (default; only override if I asked for a different threshold)\n - Telegram env in the cron message β€” **only** if input (b) yielded both values:\n - `POWERLOOM_TELEGRAM_BOT_TOKEN=`\n - `POWERLOOM_TELEGRAM_CHAT_ID=`\n - Do NOT consult OpenClaw `channels.telegram`, `openclaw.json`, or any other config source for Telegram credentials β€” only use what I pasted in chat for input (b).\n6. Before the first run: `rm -f .powerloom/whale-cron-state.json` if you need a clean epoch cursor.\n Keep `.powerloom/pool-metadata-cache.json` across reinstalls unless debugging metadata.\n7. Set WHALE_CRON_STATE_FILE and WHALE_CRON_POOL_CACHE to paths outside the skill directory (e.g. in the workspace root) so they survive openclaw skills install --force.\n\nConstraints:\n- **Pay-signup broadcast:** run `node scripts/signup-pay.mjs --dry-run` first unless I explicitly waive dry-run in chat; paste stderr quote summary into chat for my review; then run **`node scripts/signup-pay.mjs --yes` once** as an ephemeral shell invocation (not saved in OpenClaw skill env). CI may use `POWERLOOM_SIGNUP_PAY_CONFIRM=yes` for a single job β€” do not leave confirmation bypass variables persisted alongside wallet keys. TTY sessions type `CONFIRM` instead.\n- **Telegram credentials must be gathered from me in chat (or explicit opt-out received) BEFORE the cron job is created.** Asking me for `POWERLOOM_TELEGRAM_BOT_TOKEN` / `POWERLOOM_TELEGRAM_CHAT_ID` after running `openclaw cron add` and seeing the cron tick (with stdout-only alerts) is a known failure mode β€” fail the run and re-ask before cron creation.\n- Do NOT use OpenClaw config (`channels.telegram`, `openclaw.json`, etc.) as a fallback Telegram source β€” chat input only.\n- Use `bds_mpp_snapshot_allTrades` only (bounded batches). Do not add streaming trade tools.\n- Do NOT run the tracker as a background process β€” use OpenClaw cron only.\n- Do NOT show \"???\" for unknown tokens β€” resolve via the metadata tool or show the address.\n````\n\n---\n\n## Verification provenance (cron script + one-shot)\n\n**In `scripts/whale-cron.mjs` (already implemented):** each `bds_mpp_snapshot_allTrades` result carries `data.verification` (`cid`, `epochId`, `projectId`). The script reads that object once per poll and appends a **β€œVerified on-chain”** block (CID, epoch, project) to each formatted alert in `formatAlert` β€” it is not optional glue you add in the OpenClaw message; the one-shot above assumes this behavior.\n\n**Independent check:** the MCP tool `verify_data_provenance` can confirm commitments using the same `cid` / `epoch_id` / `project_id` β€” see **`references/03-verification.md`** and the **Verify** row in `SKILL.md` (data table).\n\n---\n\n## Related files in this skill\n\n| Item | Location |\n|------|----------|\n| Cron entrypoint (incl. verification in alerts) | `scripts/whale-cron.mjs` |\n| Pay-signup | `scripts/signup-pay.mjs` |\n| MCP + trade helpers | `lib/mcp.mjs`, `lib/trade-utils.mjs`, `lib/state.mjs` |\n| On-chain verification details | `references/03-verification.md` |\n| Integrator rules | `SKILL.md` β†’ **Hosts & integrators** |\n\nSee also `references/01-quickstart.md` and `references/06-troubleshooting.md`.\n\nFile v0.2.5:references/09-openclaw-one-shot-free-key.md\n\n# OpenClaw: free-key whale cron (one-shot prompt)\n\nUse this as a **single agent message** after running `bds-agent signup` to get a free `sk_live_...` API key (browser device flow, 2 free credits, no wallet). The skill itself only needs **`POWERLOOM_API_KEY`** at runtime β€” `whale-cron.mjs` dispatches alerts via the hosted MCP server using that key alone.\n\nFor the wallet-funded variant (autonomous on-chain pay-signup for a 10-credit plan in the same prompt), see [`references/08-openclaw-one-shot.md`](./08-openclaw-one-shot.md).\n\n---\n\n## Copy-paste prompt\n\n````\nInstall the skill \"πŸ¦„ Powerloom Uniswap V3 timeseries data\" (powerloom-bds-univ3) from ClawHub.\nAfter install, run npm install in the skill directory.\n\nI already have a Powerloom API key (sk_live_...) from `bds-agent signup` β€” 2 free credits, no wallet needed. Use that key directly. Do NOT run `scripts/signup-pay.mjs`. Do NOT ask for a private key, RPC URL, plan id, chain id, or token symbol.\n\n**REQUIRED INPUTS β€” gather BOTH from me in chat BEFORE you install the skill, wire any env, or create any cron job. STOP and ask if either is missing. Do NOT proceed to step 1 below until both are resolved. Asking me for any of these AFTER creating the cron is a failure mode β€” re-ask BEFORE cron creation.**\n\na. **Powerloom API key** β€” paste your `sk_live_...` from `bds-agent signup`. If you don't have one yet, run `bds-agent signup` first (free, 2 credits, browser device flow) and come back. Do not invent or guess a key.\n\nb. **Telegram alerts** β€” ask explicitly: \"Do you want Telegram alerts for whale swaps? If yes, paste your `POWERLOOM_TELEGRAM_BOT_TOKEN` and `POWERLOOM_TELEGRAM_CHAT_ID`. If no, type 'skip' and alerts will print to stdout only.\"\n - If I give you both tokens β†’ use them in the cron env (steps 1 and 4 below).\n - If I explicitly say \"skip\" / \"no Telegram\" / \"stdout only\" β†’ proceed without TG envs and tell me clearly in the final cron summary that alerts will only print to stdout (the cron `--no-deliver` flag means OpenClaw's chat won't see them either).\n - Do NOT silently default to \"stdout is fine.\" Either both TG values, or an explicit opt-out.\n - Do NOT look up TG credentials from any OpenClaw config source (`channels.telegram`, `openclaw.json`, etc.) β€” only use what I paste in this conversation.\n\nOnce (a) and (b) are resolved in chat, proceed with the steps below.\n\nSet up a whale radar cron with the existing key. Details:\n\n1. Set the gathered envs in OpenClaw under `skills.entries.powerloom-bds-univ3.env.*`:\n - `POWERLOOM_API_KEY` β€” required, from input (a).\n - `POWERLOOM_TELEGRAM_BOT_TOKEN`, `POWERLOOM_TELEGRAM_CHAT_ID` β€” set both **only** if I gave you values in input (b). If I opted out, leave both unset; `whale-cron.mjs` prints alerts to stdout in that case (still includes the verification block).\n\n2. Pre-flight: `node scripts/ensure-credits.mjs` to confirm the key is valid and balance is non-zero (free signup grants 2 credits).\n\n3. `scripts/whale-cron.mjs` should:\n - Use `lib/mcp.mjs` `callTool()` for all MCP calls (SSE handshake, not raw HTTP).\n - Use `lib/trade-utils.mjs` `flattenAllTradesFromSnapshot()` to parse the snapshot.\n - Response shape: `result.data.tradeData` = `{ poolAddr: { trades: [...] } }`.\n - Resolve pool token names with `bds_mpp_pool_pool_address_metadata` per unknown pool;\n cache in `.powerloom/pool-metadata-cache.json` (override with `WHALE_CRON_POOL_CACHE`).\n - Verification: `result.data.verification` = `{ cid, epochId, projectId }` β€” surface in alerts (e.g. βœ…).\n - Telegram: `parse_mode: MarkdownV2` with full escaping, or plain-text fallback.\n - If the script is missing or broken, rebuild using the skill’s `lib/*` helpers only.\n\n4. Create an OpenClaw cron job β€” **only after** REQUIRED INPUTS (a) and (b) above are fully resolved in chat:\n - Name: e.g. \"Whale Radar\"\n - Schedule: e.g. every 15s (`--every 15s` with `openclaw cron add`)\n - Timeout: 90s (`--timeout 90000`)\n - Session: isolated (`--session isolated`)\n - Flags: `--no-deliver`, `--light-context`\n - Message: a shell command that `cd`s to the skill dir, sets env inline, then runs `node scripts/whale-cron.mjs`. Required env in the cron message:\n - `POWERLOOM_API_KEY=`\n - `POWERLOOM_BDS_MCP_CALL_TIMEOUT_MS=120000`\n - `WHALE_CRON_THRESHOLD=10000` (default; only override if I asked for a different threshold)\n - Telegram env in the cron message β€” **only** if input (b) yielded both values:\n - `POWERLOOM_TELEGRAM_BOT_TOKEN=`\n - `POWERLOOM_TELEGRAM_CHAT_ID=`\n - Do NOT consult OpenClaw `channels.telegram`, `openclaw.json`, or any other config source for Telegram credentials β€” only use what I pasted in chat for input (b).\n\n5. Before the first run: `rm -f .powerloom/whale-cron-state.json` if you need a clean epoch cursor.\n Keep `.powerloom/pool-metadata-cache.json` across reinstalls unless debugging metadata.\n\n6. Set WHALE_CRON_STATE_FILE and WHALE_CRON_POOL_CACHE to paths outside the skill directory (e.g. in the workspace root) so they survive `openclaw skills install --force`.\n\nConstraints:\n- This flow uses an **existing** `sk_live_...` key only. Do NOT initiate any on-chain payment, and do NOT prompt for wallet credentials.\n- **Telegram credentials must be gathered from me in chat (or explicit opt-out received) BEFORE the cron job is created.** Asking me for `POWERLOOM_TELEGRAM_BOT_TOKEN` / `POWERLOOM_TELEGRAM_CHAT_ID` after running `openclaw cron add` and seeing the cron tick (with stdout-only alerts) is a known failure mode β€” fail the run and re-ask before cron creation.\n- Do NOT use OpenClaw config (`channels.telegram`, `openclaw.json`, etc.) as a fallback Telegram source β€” chat input only.\n- If the user later wants more credits, point them at `references/08-openclaw-one-shot.md` (wallet-funded pay-signup variant) or `node scripts/credits-topup.mjs` against the same key.\n- Use `bds_mpp_snapshot_allTrades` only (bounded batches). Do not add streaming trade tools.\n- Do NOT run the tracker as a background process β€” use OpenClaw cron only.\n- Do NOT show \"???\" for unknown tokens β€” resolve via the metadata tool or show the address.\n````\n\n---\n\n## Why this works without a wallet\n\n`scripts/whale-cron.mjs` only consumes `POWERLOOM_API_KEY` (via `lib/mcp.mjs`) plus the optional Telegram envs (`lib/powerloom-env.mjs` `telegramBotToken()` / `telegramChatId()`). The wallet/plan env getters in `lib/powerloom-env.mjs` are **only** read by `scripts/signup-pay.mjs` and `scripts/credits-topup.mjs` β€” both of which this prompt explicitly skips. The skill's `metadata.openclaw.requires.env` schema in `SKILL.md` lists wallet vars as **optional** (`optional_env`) for this exact reason.\n\nWhen the 2 free credits run out (~1440 epochs of data per credit on metered routes), upgrade in either of two ways without re-onboarding:\n\n- **Wallet-funded plan, in the agent**: paste the [wallet-funded one-shot](./08-openclaw-one-shot.md) β€” runs `signup-pay.mjs` and refreshes the API key.\n- **Top-up the existing key**: `node scripts/credits-topup.mjs` with `POWERLOOM_PLAN_ID`, `POWERLOOM_EVM_CHAIN_ID`, `POWERLOOM_TOKEN_SYMBOL`, and a funded wallet β€” adds credits to the same `sk_live_...`.\n\n---\n\n## Verification provenance (cron script + one-shot)\n\n**In `scripts/whale-cron.mjs` (already implemented):** each `bds_mpp_snapshot_allTrades` result carries `data.verification` (`cid`, `epochId`, `projectId`). The script reads that object once per poll and appends a **\"Verified on-chain\"** block (CID, epoch, project) to each formatted alert in `formatAlert` β€” it is not optional glue you add in the OpenClaw message; the one-shot above assumes this behavior. Free-key alerts carry the same verification block as wallet-funded alerts.\n\n**Independent check:** the MCP tool `verify_data_provenance` can confirm commitments using the same `cid` / `epoch_id` / `project_id` β€” see [`references/03-verification.md`](./03-verification.md) and the **Verify** row in `SKILL.md` (data table).\n\n---\n\n## Related files in this skill\n\n| Item | Location |\n|------|----------|\n| Cron entrypoint (incl. verification in alerts) | `scripts/whale-cron.mjs` |\n| Pre-flight credit check | `scripts/ensure-credits.mjs` |\n| Pay-signup (wallet-funded variant) | `scripts/signup-pay.mjs` |\n| Top-up (more credits, existing key) | `scripts/credits-topup.mjs` |\n| MCP + trade helpers | `lib/mcp.mjs`, `lib/trade-utils.mjs`, `lib/state.mjs` |\n| On-chain verification details | `references/03-verification.md` |\n| Wallet-funded one-shot variant | `references/08-openclaw-one-shot.md` |\n| Integrator rules | `SKILL.md` β†’ **Hosts & integrators** |\n\nSee also [`references/01-quickstart.md`](./01-quickstart.md) and [`references/06-troubleshooting.md`](./06-troubleshooting.md).\n\nArchive v0.2.4: 33 files, 52342 bytes\n\nFiles: package-lock.json (4617b), package.json (305b), README.md (6476b), recipes/defi-analyst.yaml (813b), recipes/token-flow.yaml (412b), recipes/whale-radar.yaml (751b), references/01-quickstart.md (1419b), references/02-tool-catalog.md (935b), references/03-verification.md (1037b), references/04-credit-budget.md (500b), references/05-data-market-scope.md (814b), references/06-troubleshooting.md (3592b), references/07-prompt-patterns.md (675b), references/08-openclaw-one-shot.md (8455b), references/09-openclaw-one-shot-free-key.md (8866b), scripts/credits-topup.mjs (6546b), scripts/defi-analyst.mjs (8252b), scripts/ensure-credits.mjs (1300b), scripts/lib/confirm-spend.mjs (2016b), scripts/lib/dispatch.mjs (1400b), scripts/lib/mcp.mjs (11542b), scripts/lib/powerloom-env.mjs (1667b), scripts/lib/recipe-config.mjs (690b), scripts/lib/state.mjs (1519b), scripts/lib/trade-utils.mjs (2134b), scripts/list-mcp-tools.mjs (488b), scripts/powerloom-mcp-client.mjs (644b), scripts/signup-pay.mjs (6462b), scripts/token-flow.mjs (4915b), scripts/whale-cron.mjs (9815b), scripts/whale-radar.mjs (4599b), SKILL.md (12794b), _meta.json (138b)\n\nFile v0.2.4:SKILL.md\n\n---\nname: powerloom-bds-univ3\ndescription: |\n Autonomous Uniswap V3 monitoring on consensus-backed data with onchain provenance.\n Every data point is finalized on-chain by Powerloom's decentralized sequencer-validator network (DSV)\n and independently verifiable via verify_data_provenance. Ships with Whale Radar,\n Token-Flow, and Autonomous DeFi Analyst recipes.\n **Two onboarding paths**: (1) **free** β€” drop in an existing `sk_live_...` from `bds-agent signup`\n (browser device flow, 2 free credits, no wallet) and run cron immediately\n (see `references/09-openclaw-one-shot-free-key.md`); (2) **wallet-funded** β€” autonomous\n on-chain pay-signup via `scripts/signup-pay.mjs` for a 10-credit plan in the same prompt\n (see `references/08-openclaw-one-shot.md`). The runtime data path needs only `POWERLOOM_API_KEY`;\n wallet env vars are required only by the pay-signup and top-up scripts.\n Billing: metering service HTTP APIs; optional bds-agent CLI.\n Triggers on phrases like \"whale alert\", \"track trades\", \"all trades for\", \"by token\",\n \"ERC20\", \"ERC20 token swaps\", \"Powerloom\", \"verify on-chain\", \"verified data\".\nversion: 0.2.4\nhomepage: https://bds-metering.powerloom.io\nrepository: https://github.com/powerloom/powerloom-bds-univ3\ntags:\n - defi\n - uniswap\n - ethereum\n - on-chain\n - verifiable\n - consensus\n - agent\nmetadata:\n openclaw:\n emoji: \"πŸ¦„\"\n requires:\n bins: [\"node\"]\n env:\n # Only POWERLOOM_API_KEY is mandatory at install time. The free-key path\n # (references/09-openclaw-one-shot-free-key.md) needs nothing else from\n # this skill's perspective. Wallet/plan envs below are optional and only\n # consumed by scripts/signup-pay.mjs and scripts/credits-topup.mjs.\n - POWERLOOM_API_KEY\n optional_env:\n # Wallet-funded variants (signup-pay or credits-topup) β€” only required\n # if the user invokes those scripts. See references/08-openclaw-one-shot.md.\n - POWERLOOM_EVM_PRIVATE_KEY\n - POWERLOOM_EVM_RPC_URL\n - POWERLOOM_EVM_CHAIN_ID\n - POWERLOOM_PLAN_ID\n - POWERLOOM_TOKEN_SYMBOL\n # Dispatch + transport overrides β€” never required.\n - POWERLOOM_MCP_URL\n - POWERLOOM_TELEGRAM_BOT_TOKEN\n - POWERLOOM_TELEGRAM_CHAT_ID\n - POWERLOOM_DISCORD_WEBHOOK_URL\n - POWERLOOM_BDS_MCP_CALL_TIMEOUT_MS\n - POWERLOOM_BDS_MCP_DEBUG\n - POWERLOOM_METERING_BASE_URL\n - POWERLOOM_AGENT_NAME\n - POWERLOOM_EMAIL\n---\n\n# Powerloom BDS β€” Uniswap V3\n\n## Install\n\n> **Two onboarding paths.**\n>\n> **Free** β€” run `bds-agent signup` (browser device flow, no wallet, 2 free credits), then paste [`references/09-openclaw-one-shot-free-key.md`](references/09-openclaw-one-shot-free-key.md) into OpenClaw. Sets `POWERLOOM_API_KEY` and a Whale Radar cron. Nothing else needed.\n>\n> **Wallet-funded** β€” paste [`references/08-openclaw-one-shot.md`](references/08-openclaw-one-shot.md) and `scripts/signup-pay.mjs` runs an autonomous on-chain payment for a 10-credit plan in the same prompt.\n>\n> **⚠️ WARNING β€” wallet-funded path only:** `signup-pay.mjs` and `credits-topup.mjs` need an EVM private key to broadcast on-chain payments. Use a **burner wallet** with limited funds dedicated to this purpose. Never use a wallet holding significant assets or with extensive transaction history for agentic setups. The free-key path **does not** require any wallet credentials.\n\n**Contract:** [bds-agenthub-billing-metering](https://github.com/powerloom/bds-agenthub-billing-metering). **ClawHub** users only need a **single origin** (default [bds-metering.powerloom.io](https://bds-metering.powerloom.io))β€” **`bds-agent` commands are optional**; they are a reference CLI for the same JSON bodies you can send with `curl` + a wallet or `ethers`.\n\n### Metering HTTP (authoritative)\n\n| What | How |\n|------|-----|\n| List SKUs | `GET {BASE}/credits/plans` β€” no auth. Choose a plan row: `id`, `chain_id`, `token_symbol` (and note `payment_kind`: ERC-20 vs native / CGT). **`chains[].rpc_url`** is a **public** JSON-RPC hint only when the metering deployment sets it; it may be **empty** β€” use **`POWERLOOM_EVM_RPC_URL`** for wallet / script calls in that case. |\n| New key, wallet-only | **Pay-signup:** `POST {BASE}/signup/pay/quote` β†’ pay on chain β†’ `POST {BASE}/signup/pay/claim` with `signup_nonce` + `tx_hash`. Returns `api_key`. |\n| New key, browser | Human device flow on `{BASE}/metering` (same service). |\n| More credits, existing key | `POST {BASE}/credits/topup` with `Authorization: Bearer sk_live_…` and tx / plan (not the pay-signup endpoints). |\n| Check balance | `GET {BASE}/credits/balance` with `Authorization: Bearer …` |\n\n`{BASE}` is **`POWERLOOM_METERING_BASE_URL`**, e.g. `https://bds-metering.powerloom.io`. Set **`POWERLOOM_API_KEY`** to the `sk_live_...` you get after pay-signup, device signup, or copy from the dashboard.\n\n### OpenClaw env vars (mandatory vs optional)\n\n| Field | When required | Role |\n|-------|---------------|------|\n| `POWERLOOM_API_KEY` | **Always** β€” only mandatory env at install time | `sk_live_...` from `bds-agent signup` (free path) or `signup-pay.mjs` claim (wallet path) |\n| `POWERLOOM_EVM_PRIVATE_KEY` | Wallet-funded path only | Payer wallet β€” **use a burner wallet** |\n| `POWERLOOM_EVM_RPC_URL` | Wallet-funded path only | JSON-RPC for that chain |\n| `POWERLOOM_EVM_CHAIN_ID` | Wallet-funded path only | Must match the plan's `chain_id` |\n| `POWERLOOM_PLAN_ID` | Wallet-funded path only | e.g. `launch_10_pl_power_cgt` from `GET /credits/plans` |\n| `POWERLOOM_TOKEN_SYMBOL` | Wallet-funded path only | e.g. `POWER` (must match that row) |\n\nThe schema in `metadata.openclaw.requires.env` lists only `POWERLOOM_API_KEY` as required; the wallet/plan envs above sit in `optional_env` and are read only by `scripts/signup-pay.mjs` (new key, pay-signup) and `scripts/credits-topup.mjs` (more credits on an existing key). Free-key flows pass straight through.\n\n### Reference client: `bds-agent` (optional)\n\n[docs/USER_GUIDE.md](https://github.com/powerloom/bds-agent-py/blob/main/docs/USER_GUIDE.md) in **bds-agent-py** has the end-to-end order: **Metering service API** table β†’ pay-signup β†’ device β†’ top-up. One-liner sequence:\n\n1. `bds-agent credits plans` β€” same as `GET /credits/plans`\n2. `bds-agent credits setup-evm` β€” writes `~/.config/bds-agent/profiles/.evm.env`\n3. `bds-agent signup-pay --plan-id … --chain-id … --token-symbol …` β€” implements quote / broadcast / claim (including **native** `payment_kind` plans)\n\n### This repo: Node scripts (no Python, no `bds-agent` required)\n\n| Script | What it does |\n|--------|----------------|\n| `node scripts/signup-pay.mjs` | **New** key: pay-signup (quote β†’ on-chain pay β†’ claim). Uses **`quote.payment_kind`**: `native_value` = send **native/CGT** (`tx.value` to `recipient`); `erc20` = token **`transfer`**. For **POWER (7869) CGT** plans, metering uses **`native_value`** β€” do not force ERC-20. **Broadcast protection:** interactive shells prompt `CONFIRM`; non-interactive shells require **`--yes`** (preferred for OpenClaw β€” ephemeral argv, do not persist in skill env) **or** `POWERLOOM_SIGNUP_PAY_CONFIRM=yes` (CI one-shot only). **`--dry-run`** prints quote summary and exits without sending a tx. |\n| `node scripts/credits-topup.mjs` | **More** credits: uses existing **`POWERLOOM_API_KEY`**, fetches `GET /credits/plans`, matches **`POWERLOOM_PLAN_ID` + `POWERLOOM_EVM_CHAIN_ID` + `POWERLOOM_TOKEN_SYMBOL`**, sends **ERC-20** or **native** per `payment_kind`, then **`POST /credits/topup`**. Same confirmation gate as signup-pay (**`--yes`** preferred; **`POWERLOOM_CREDITS_TOPUP_CONFIRM=yes`** for CI one-shot only; TTY `CONFIRM`). **`--dry-run`** prints summary only. Set **`POWERLOOM_EVM_RPC_URL`** when **`chains[].rpc_url`** is empty or you need a specific node (the API never exposes the server's private RPC). |\n| `node scripts/ensure-credits.mjs` | **Balance** only (`GET /credits/balance`); no purchase. |\n\n`npm install` once (adds `ethers`).\n\n**Optional env (signup script):** `POWERLOOM_METERING_BASE_URL`, `POWERLOOM_AGENT_NAME`, `POWERLOOM_EMAIL` (see [metering README](https://github.com/powerloom/bds-agenthub-billing-metering#readme)).\n\n### After you have a key β€” more credits (top-up)\n\n**Spec:** `POST {BASE}/credits/topup` with `Authorization: Bearer` and JSON `{ \"plan_id\", \"chain_id\", \"tx_hash\" }` after an on-chain payment that matches the plan. **In this repo:** `node scripts/credits-topup.mjs`. **Reference CLI:** [USER_GUIDE](https://github.com/powerloom/bds-agent-py/blob/main/docs/USER_GUIDE.md) (EVM `credits topup` / Tempo per deployment). **Check balance:** `node scripts/ensure-credits.mjs`.\n\n**Default MCP endpoint:** `https://bds-mcp.powerloom.io/sse` β€” override with `POWERLOOM_MCP_URL` if needed.\n\nGeneric tool runner: `node scripts/powerloom-mcp-client.mjs '{}'`\n\n## Common tasks β†’ which tool\n\n| Task phrase | Tool(s) |\n|-------------|---------|\n| Track **all swaps for token X** (multi-pool) | **Token-Flow** recipe (`bds_mpp_snapshot_trades_pool_address` per pool) or `bds_mpp_snapshot_allTrades` via **`whale-cron.mjs`** |\n| **Whale** / USD threshold | **`whale-cron.mjs`** (all pools, bounded) or **`whale-radar.mjs`** (fixed pool list, per-pool snapshots) |\n| **One pool only** | `bds_mpp_snapshot_trades_pool_address` after `bds_mpp_token_token_address_pools` or `bds_mpp_dailyActivePools` |\n| **Verify** on-chain | `verify_data_provenance` with `cid`, `epoch_id`, `project_id` from API β€” never substitute block for epoch |\n\n**Timeouts:** default `POWERLOOM_BDS_MCP_CALL_TIMEOUT_MS=60000`. Raise it (e.g. **120000**) if `bds_mpp_snapshot_allTrades` times out under backlog.\n\n## Recipes (supported surface)\n\nPre-built scripts + `recipes/*.yaml` defaults β€” prefer these over ad-hoc scripts on weaker models. **This skill does not call streaming catalog tools** (`bds_mpp_stream_*`); every recipe uses **bounded snapshot** MCP calls so runs fit cron and agent sandboxes.\n\n**Cron default:** `whale-radar.mjs`, `token-flow.mjs`, and `defi-analyst.mjs` each run **one bounded round** and **exit** (safe for OpenClaw cron). Pass **`--daemon`** to repeat with `heartbeat.interval_seconds` between rounds (local / long-running only).\n\n| Recipe / entrypoint | Script |\n|---------------------|--------|\n| Whale Radar (fixed pools) | `node scripts/whale-radar.mjs` β€” one round over `poll_fallback_pools`; **`--daemon`** for repeat |\n| Whale alerts (cron, all pools) | `node scripts/whale-cron.mjs` β€” **bounded** one-shot: `bds_mpp_snapshot_allTrades` + pool metadata; alerts include **snapshot** `cid` / epoch / project from `data.verification` β€” see **Verification provenance** in `references/08-openclaw-one-shot.md` |\n| Token-Flow | `node scripts/token-flow.mjs` (`--token 0x...`) β€” one round per pool for that token; **`--daemon`** for repeat |\n| DeFi Analyst | `node scripts/defi-analyst.mjs` β€” one round: **multi-pool** (`bds_mpp_snapshot_allTrades` + all-pools volume) or `filters.scope: single_pool`; **`--daemon`** for repeat |\n\n## Model guidance\n\nRecipes produce the same stdout/Telegram output regardless of model. Ad-hoc \"compose your own\" prompts work best on GPT-4–class or GLM-5+; weaker local models may collapse multi-pool prompts onto one pool β€” **use the Token-Flow recipe** instead.\n\n## Hosts & integrators (OpenClaw, cron, heartbeats)\n\n**OpenClaw \"one shot\" setups** β€” pick the variant that matches the user's onboarding state:\n\n| Variant | Use when | Reference |\n|---------|----------|-----------|\n| Free-key cron | The user already has `sk_live_...` from `bds-agent signup` (2 free credits, no wallet) | [`references/09-openclaw-one-shot-free-key.md`](references/09-openclaw-one-shot-free-key.md) |\n| Pay-signup + cron | The user wants autonomous wallet-funded onboarding for a 10-credit plan in the same prompt | [`references/08-openclaw-one-shot.md`](references/08-openclaw-one-shot.md) |\n\nBoth prompts produce the same `Whale Radar` cron firing `node scripts/whale-cron.mjs` every 15s with onchain verification surfaced in every alert. Agents should default to the free-key variant unless the user explicitly asks for autonomous on-chain payment.\n\n**Scheduled / cron-style runs:** Prefer **`whale-cron.mjs`**, **`whale-radar.mjs`**, **`token-flow.mjs`**, or **`defi-analyst.mjs`** with **no** `--daemon` so each invocation **exits**. **Streaming trade tools** (`bds_mpp_stream_*`) are **not** used by this skill.\n\n## References\n\nSee `references/` for quickstart, full tool table, verification, credit budget, scope, troubleshooting, prompt patterns, **`08-openclaw-one-shot.md`** (copy-paste OpenClaw runbook), and cron notes in quickstart + tool catalog.\n\nFile v0.2.4:README.md\n\n# Powerloom BDS β€” Uniswap V3 (ClawHub skill)\n\n## Autonomous Uniswap V3 monitoring + onchain provenance verification, in minutes. Decentralized data, not trust-me data.\n\nEvery data point this skill fetches is finalized onchain by Powerloom's decentralized sequencer-validator network. The `verify_data_provenance` tool compares API CIDs to onchain commitments so alerts can carry a cryptographic receipt, not a vendor's word.\n\n## Recipes\n\n- **Whale Radar** β€” USD-threshold alerts: **`bds_mpp_snapshot_trades_pool_address`** for each pool in `poll_fallback_pools`. For **cron / OpenClaw heartbeats** over **all** pools in one bounded batch, use **`node scripts/whale-cron.mjs`** (`bds_mpp_snapshot_allTrades` + pool metadata).\n- **Token-Flow** β€” all swaps touching a configured token (default USDC) across pools derived at runtime.\n- **Autonomous DeFi Analyst** β€” default **multi-pool** `bds_mpp_snapshot_allTrades` + all-pools token volume; set **`filters.scope: single_pool`** in `recipes/defi-analyst.yaml` for single-pool snapshots only.\n\n## Integrators (OpenClaw, cron)\n\n**End-to-end one-shot prompts** β€” pick by onboarding state:\n\n| Variant | Use when | Reference |\n|---------|----------|-----------|\n| Free-key cron | You already have `sk_live_...` from `bds-agent signup` (2 free credits, no wallet) | **`references/09-openclaw-one-shot-free-key.md`** |\n| Pay-signup + cron | You want autonomous wallet-funded onboarding for a 10-credit plan in the same prompt | **`references/08-openclaw-one-shot.md`** |\n\n**Default behavior:** `whale-radar.mjs`, `token-flow.mjs`, and `defi-analyst.mjs` each run **one bounded round** and **exit** (safe for cron). Use **`--daemon`** only if you want a local repeat loop (`heartbeat.interval_seconds` between rounds).\n\nFor **scheduled heartbeats**, prefer **`whale-cron.mjs`** (exits) or the recipe scripts **without** `--daemon`. This repo does not ship streaming trade consumption.\n\n## Setup\n\n```bash\ncd powerloom-bds-univ3\nnpm install\nexport POWERLOOM_API_KEY=sk_live_...\nnode scripts/ensure-credits.mjs\n```\n\n**Where to get `POWERLOOM_API_KEY`:**\n\n- **Free** (no wallet, 2 credits): `bds-agent signup` β€” browser device flow on the metering service. Same `sk_live_...` works against this skill, the hosted MCP server, and any pay-signup top-up later.\n- **Wallet-funded** (10-credit plan): `node scripts/signup-pay.mjs --dry-run` (quote summary only), then **`node scripts/signup-pay.mjs --yes`** once after verifying stderr output β€” prefer argv over env so confirmation bypass is **not** persisted in OpenClaw skill config. CI may use `POWERLOOM_SIGNUP_PAY_CONFIRM=yes` for a single invocation only. **Native or ERC-20** per `quote.payment_kind` (POWER CGT on 7869 = native).\n- **More credits, existing key**: `node scripts/credits-topup.mjs` β€” same `--dry-run` β†’ **`--yes`** pattern (or one-shot env for CI only). See **`SKILL.md`**.\n\nOptional: `POWERLOOM_TELEGRAM_BOT_TOKEN`, `POWERLOOM_TELEGRAM_CHAT_ID`, and `dispatch.channel: telegram` in `recipes/*.yaml`.\n\n## Links (metering service)\n\nOne deploy (`npm run build` + `npm start` on **`bds-agenthub-billing-metering`**) serves both:\n\n- **Agent signup (CLI / API)** β€” origin only: [bds-metering.powerloom.io](https://bds-metering.powerloom.io) (`BDS_AGENT_SIGNUP_URL` / `bds-agent signup --base-url …`).\n- **Browser signup + billing UI** β€” [bds-metering.powerloom.io/metering](https://bds-metering.powerloom.io/metering)\n\n- Hosted MCP SSE: `https://bds-mcp.powerloom.io/sse`\n\n## Naming (ClawHub skill vs MCP tools)\n\n| What | Name |\n|------|------|\n| ClawHub / OpenClaw skill folder & slug | **`powerloom-bds-univ3`** |\n| MCP tools on the hosted server | **`bds_mpp_*`**, **`get_credit_balance`**, **`verify_data_provenance`** β€” there is **no** tool named `bds_univ3`. |\n\nTo print the live tool list from the API (same handshake as `callTool`):\n\n```bash\nexport POWERLOOM_API_KEY=sk_live_...\nnode scripts/list-mcp-tools.mjs\n```\n\n## Test locally (without publishing to ClawHub)\n\nPublishing is optional for trying the **scripts** and **SKILL.md** instructions:\n\n1. **Scripts only** β€” From this directory, with `POWERLOOM_API_KEY` set, run `node scripts/ensure-credits.mjs`, `node scripts/list-mcp-tools.mjs` (proves tool names), `node scripts/powerloom-mcp-client.mjs get_credit_balance '{}'`, or a recipe (`whale-radar.mjs`, etc.). That validates MCP wiring end-to-end against the hosted server.\n\n2. **OpenClaw / ClawHub** β€” If **`skills list`** and the **dashboard** show **`powerloom-bds-univ3`** as **ready**, the skill is **on disk and registered**. That is not the same as β€œthe main chat always loads **`SKILL.md`** into the model on every turn.” If chat still acts blind, check your OpenClaw **agent** actually **uses** that skill (per-agent skill selection / defaults), then **new session** after changes. The reliable execution path is still **`node scripts/…`** with **`POWERLOOM_API_KEY`**; chat is best-effort unless you also wire **BDS MCP** for tools in the tool list.\n\n - **Registry:** `clawhub install powerloom-bds-univ3` only pulls **published** builds. **Local dev:** copy this repo’s root into **`…/workspace/skills/powerloom-bds-univ3/`** with **`SKILL.md`** at the folder root, set **`POWERLOOM_API_KEY`** in `openclaw.json` skill `entries`, restart the gateway.\n - **Compose / `OPENCLAW_WORKSPACE_DIR`:** The stack usually reads a **`.env` file next to `docker-compose.yml`**. [Docker Compose](https://docs.docker.com/compose/how-tos/environment-variables/variable-interpolation/) substitutes **`${OPENCLAW_WORKSPACE_DIR}`** from: that `.env` file, or **exported** variables in the shell you run `docker compose` from, or a **`.env` override** your vendor documents. It is not magic β€” if unset, the mount line can be wrong or empty. Set it to the **host** path that should map to `…/workspace` in the container (often your user’s `…/.openclaw/workspace` as an **absolute** path). Check `docker compose config` to see the resolved value.\n\n Docker bind mounts, **`ENOENT`**, symlinks, UI quirks: **`references/06-troubleshooting.md`**.\n\n3. **After publish** β€” `clawhub install powerloom-bds-univ3` (or the slug you published).\n\n## Publish (maintainers)\n\n```bash\nnpx clawhub login\nnpx clawhub publish . --slug powerloom-bds-univ3 --version 0.1.0\n```\n\n## Repository\n\nSource: [github.com/powerloom/powerloom-bds-univ3](https://github.com/powerloom/powerloom-bds-univ3) (mirror this folder into that org repo).\n\nFile v0.2.4:_meta.json\n\n{\n \"ownerId\": \"kn7a3wb3bny97qvtprbgh9cxe185fms0\",\n \"slug\": \"powerloom-bds-univ3\",\n \"version\": \"0.2.4\",\n \"publishedAt\": 1778401497915\n}\n\nFile v0.2.4:references/01-quickstart.md\n\n# Quickstart (~10 minutes)\n\n1. **Get an API key** β€” **CLI / API:** metering origin [bds-metering.powerloom.io](https://bds-metering.powerloom.io) (`bds-agent signup`; see [agent guide](https://github.com/powerloom/bds-agent-py/blob/main/docs/USER_GUIDE.md)). **Browser:** signup and top-ups at [bds-metering.powerloom.io/metering](https://bds-metering.powerloom.io/metering).\n2. **Export** `POWERLOOM_API_KEY=sk_live_...` in the environment OpenClaw uses (or your shell profile).\n3. **Optional** β€” default MCP URL is `https://bds-mcp.powerloom.io/sse`. Override with `POWERLOOM_MCP_URL` if directed.\n4. **Check credits**: `node scripts/ensure-credits.mjs` β€” should print balance JSON and exit 0.\n5. **OpenClaw / cron** β€” for **one-shot schedulers** (recommended), use **`node scripts/whale-cron.mjs`** and the full copy-paste flow in **`references/08-openclaw-one-shot.md`**. For a **fixed pool list** and local poll loop, use **`whale-radar.mjs`** (per-pool snapshots only).\n6. **Run a recipe** (stdout first):\n - Whale cron (bounded, all pools): `node scripts/whale-cron.mjs`\n - Whale Radar (fixed pools, poll): `node scripts/whale-radar.mjs`\n - Token-Flow: `node scripts/token-flow.mjs`\n - DeFi Analyst (one round, cron): `node scripts/defi-analyst.mjs`\n7. **Telegram** β€” set `POWERLOOM_TELEGRAM_BOT_TOKEN` and `POWERLOOM_TELEGRAM_CHAT_ID`, set `dispatch.channel` to `telegram` in the recipe yaml.\n\nFile v0.2.4:references/02-tool-catalog.md\n\n# BDS MCP tool catalog (representative)\n\nAll calls are metered unless noted. **Defaults:** `POWERLOOM_BDS_MCP_CALL_TIMEOUT_MS=60000` (raise for large `bds_mpp_snapshot_allTrades` responses under backlog, e.g. `120000`).\n\n**Skill note:** `powerloom-bds-univ3` recipes use **snapshot** tools only (`bds_mpp_snapshot_*`). Streaming catalog tools exist on the hosted MCP server for direct/advanced use but are **not** invoked by shipped scripts.\n\n| Tool | What | Typical latency | Skill usage |\n|------|------|-----------------|-------------|\n| `bds_mpp_snapshot_allTrades` | One-shot all pools (bounded batch) | 8–45s | `whale-cron.mjs`, DeFi Analyst multi |\n| `bds_mpp_snapshot_trades_pool_address` | One pool snapshot | 2–15s | `whale-radar.mjs`, `token-flow.mjs` |\n| `bds_mpp_stream_allTrades` | Streaming batches (long-lived upstream) | varies | **Not used by skill** |\n\nSee the live server’s `tools/list` for the full catalog.\n\nFile v0.2.4:references/03-verification.md\n\n# `verify_data_provenance`\n\nCompares a snapshot **CID** to on-chain `maxSnapshotsCid` for `(data_market, project_id, epoch_id)` via the Powerloom protocol state contract.\n\n**Inputs:** `cid` (string), `epoch_id` (integer), `project_id` (string). Optional `data_market` override.\n\n**Hosted MCP** runs the `eth_call` on the server (configured RPC is **not** included in the tool response). If the server’s RPC is unset, the tool returns a clear configuration error β€” not a silent pass. For a **local** second check, use the same `cid` / `epoch_id` / `project_id` with your own provider **`POWERLOOM_EVM_RPC_URL`** (e.g. public Powerloom JSON-RPC) and the documented ProtocolState / DataMarket addresses β€” do not expect MCP to echo an RPC URL.\n\n**Metering** `GET /credits/plans` exposes **`chains[].rpc_url`** only as an optional **public** hint; it can be empty.\n\n**In alerts:** only print verification lines when `cid`, `epoch_id`, and `project_id` are all known from the API response. Do not substitute block numbers for epoch IDs.\n\nFile v0.2.4:references/04-credit-budget.md\n\n# Credit budget (targets β€” validate in dry run)\n\n| Recipe | Mode | Steady credits/hour (target) | Free tier (~100 cr) |\n|--------|------|------------------------------|---------------------|\n| Whale Radar (poll) | per-pool snapshots | TBD | TBD |\n| Token-Flow | per-pool snapshots | TBD | TBD |\n| Whale cron | bounded `snapshot_allTrades` | TBD | TBD |\n| DeFi Analyst | 5m + p=0.2 verify | ~40 | ~2.5 h |\n\nUpdate this table after measured burn from `get_credit_balance` deltas during a 1-hour run.\n\nFile v0.2.4:references/05-data-market-scope.md\n\n# Data market scope (ETH mainnet Uniswap V3)\n\n## Canonical worked example (single pool)\n\n| Pool | Address | Fee tier |\n|------|---------|----------|\n| WETH/USDC | `0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640` | 0.05% |\n\nSome fee tiers (e.g. 0.3% WETH/USDC) may **not** be indexed in this data market β€” check `bds_mpp_pool_pool_address_metadata` / `bds_mpp_dailyActivePools` before assuming coverage.\n\n## Multi-pool / token-first\n\n- **All pools / all trades (bounded):** `bds_mpp_snapshot_allTrades` (skill + cron). Streaming variants may exist on MCP for direct use outside the skill.\n- **Token-scoped:** `bds_mpp_token_token_address_pools`, `bds_mpp_tradeVolumeAllPools_token_address_time_interval`.\n- **Single pool:** `bds_mpp_snapshot_trades_pool_address` β€” use only when the user explicitly wants one pool.\n\nFile v0.2.4:references/06-troubleshooting.md\n\n# Troubleshooting\n\n| Symptom | Cause | Fix |\n|---------|--------|-----|\n| Pay-signup \"recipient did not match\" / wrong first tx (POWER 7869) | **`signup-pay.mjs` used ERC-20** while plan is **`payment_kind: native_value`** (CGT) | **Update** the script from the current skill repo, or use a flow that checks **`quote.payment_kind`**: native = `sendTransaction({ to, value })` only, not `token.transfer`. `credits-topup.mjs` already branches on `payment_kind`. |\n| HTTP 401 | Bad or missing API key | Re-copy key from the metering dashboard ([bds-metering.powerloom.io/metering](https://bds-metering.powerloom.io/metering)) or your CLI profile; fix `POWERLOOM_API_KEY`. |\n| HTTP 402 | Credits exhausted | Top up; reduce recipe cadence; run `ensure-credits.mjs` before crons. |\n| HTTP 429 | Rate limit | Increase heartbeat interval; for **cron** schedules prefer **poll** (fewer parallel calls) instead of many snapshot fan-outs. |\n| Tool timeout | Backlog / slow finalization | Raise `POWERLOOM_BDS_MCP_CALL_TIMEOUT_MS`; reduce snapshot scope (`max_events` / fewer pools). |\n| Empty snapshot | Idle chain / catch-up | Wait; check `from_epoch` in state file (cron / DeFi Analyst). |\n| Wrong verify | Confused epoch vs block | Use `epoch_id` from snapshot / `verification` payload, not `blockNumber`. |\n| Odd outputs after model swap | OpenClaw context mismatch | Restart OpenClaw; recipes are script-driven β€” state files live under `.powerloom/`. |\n| Skill β€œready” in `skills list` / dashboard but main chat ignores it | **Install β‰  injection.** The chat agent may not attach every skill to every session; per-agent config, a **new** session after enabling the skill, or product limits on which skills the model sees. | Enable the skill for **that** agent; start a new chat; add **BDS MCP** in config if you need tools in the tool list. For deterministic behavior, run **`node scripts/…`**. |\n| `OPENCLAW_WORKSPACE_DIR` seems wrong in Docker | Compose interpolates `${VAR}` from a **`.env` next to `docker-compose.yml`**, the shell **environment**, or an `env_file` the compose file references β€” whatever OpenClaw’s install template ships. | Set **`OPENCLAW_WORKSPACE_DIR=`** in that `.env` to the **host** absolute path for workspace (e.g. `/Users/you/.openclaw/workspace`). Run **`docker compose config`** to verify substitution; **recreate** containers after changing `.env` (`up -d` / `up --force-recreate` as needed). |\n| `NO_SESSION` / β€œsession_id never arrived” | SSE bootstrap did not expose a parseable `session_id` (UUID vs hex, proxy, or stale client) | Confirm `POWERLOOM_MCP_URL` ends with `/sse` reachable from the runtime (e.g. Docker). Set **`POWERLOOM_BDS_MCP_DEBUG=1`** once to log the first bytes of the SSE stream in the error. |\n| `ENOENT` on `.../skills/.../SKILL.md` (OpenClaw in Docker) | The **container** does not have that file at the path the process checks. Common: wrong **host** tree for **`OPENCLAW_WORKSPACE_DIR`** (compose often mounts `${OPENCLAW_WORKSPACE_DIR}:/home/node/.openclaw/workspace` β€” skills belong under that dir’s `skills/` on the host, not a second guess at `~` if the env points elsewhere), nested slug folder, or symlink outside the mount. | **In the failing container:** `ls -la /home/node/.openclaw/workspace/skills/powerloom-bds-univ3/SKILL.md` (official compose) **or** `ls` under `/app/skills/...` if your error path uses `/app`. Copy/rsync the skill to the **host path** that maps to the shown prefix, with **`SKILL.md` at the slug root**; restart the gateway. `EACCES` (rare): `chmod -R a+rX` on the skill tree. |\n\nFile v0.2.4:references/07-prompt-patterns.md\n\n# Prompt patterns β†’ tools\n\n| User intent | Primary path |\n|-------------|--------------|\n| β€œAll USDC swaps”, β€œevery trade for token X” | **Token-Flow** (`token-flow.yaml`) β€” per-pool snapshots; or `bds_mpp_snapshot_allTrades` via **`whale-cron.mjs`** for all pools in one batch. |\n| β€œWhale”, β€œabove $X” | **`whale-cron.mjs`** (all pools, bounded) or **`whale-radar.mjs`** (fixed pool list). |\n| β€œOne pool” | `bds_mpp_snapshot_trades_pool_address` after resolving the pool. |\n| β€œIs this CID real?” | `verify_data_provenance` with `cid`, `epoch_id`, `project_id`. |\n\nThe skill does **not** ship streaming trade consumption; use snapshot tools only.\n\nFile v0.2.4:references/08-openclaw-one-shot.md\n\n# OpenClaw: pay-signup + whale cron (one-shot prompt)\n\nUse this as a **single agent message** after installing the skill from ClawHub. It matches how the skill is meant to run: **bounded** `bds_mpp_snapshot_allTrades` via `scripts/whale-cron.mjs`. The skill does **not** use streaming trade tools.\n\n---\n\n## Copy-paste prompt\n\n````\nInstall the skill \"πŸ¦„ Powerloom Uniswap V3 timeseries data\" (powerloom-bds-univ3) from ClawHub.\nAfter install, run npm install in the skill directory.\n\n**REQUIRED INPUTS β€” gather BOTH from me in chat BEFORE running `signup-pay.mjs` or creating any cron job. STOP and ask if either is missing. Do NOT proceed past this section with values unresolved. Asking me for any of these AFTER the cron job is created is a failure mode β€” re-ask BEFORE cron creation.**\n\na. **Payer wallet private key** β€” paste your EVM private key for the funded wallet that will pay 50 $POWER for the credit plan. **Use a burner wallet only** β€” never a wallet holding significant assets or with extensive transaction history. This key is consumed by `node scripts/signup-pay.mjs` and stored in OpenClaw env as `POWERLOOM_EVM_PRIVATE_KEY`.\n\nb. **Telegram alerts** β€” ask explicitly: \"Do you want Telegram alerts for whale swaps? If yes, paste your `POWERLOOM_TELEGRAM_BOT_TOKEN` and `POWERLOOM_TELEGRAM_CHAT_ID`. If no, type 'skip' and alerts will print to stdout only.\"\n - If I give you both tokens β†’ use them in the cron env (step 5 below).\n - If I explicitly say \"skip\" / \"no Telegram\" / \"stdout only\" β†’ proceed without TG envs and tell me clearly in the final cron summary that alerts will only print to stdout (the cron `--no-deliver` flag means OpenClaw's chat won't see them either).\n - Do NOT silently default to \"stdout is fine.\" Either both TG values, or an explicit opt-out.\n - Do NOT look up TG credentials from any OpenClaw config source (`channels.telegram`, `openclaw.json`, etc.) β€” only use what I paste in this conversation.\n\nOnce (a) and (b) are resolved in chat, proceed with the steps below.\n\nThen set up pay-signup and a whale radar cron. Details:\n\n1. PLAN: launch_10_pl_power_cgt (POWER native on chain 7869, rpc-v2.powerloom.network)\n2. Pay-signup using `scripts/signup-pay.mjs` with the private key from input (a):\n - **Recommended:** run `node scripts/signup-pay.mjs --dry-run` first β€” prints quote summary (recipient, amount_atomic, chain, payment_kind) to stderr; paste into chat so I can confirm values against metering UI / `/credits/plans`.\n - **Broadcast (non-interactive):** run `node scripts/signup-pay.mjs --yes` as a **one-off shell command** after review β€” **do not** persist `--yes` or any confirmation bypass inside OpenClaw long-lived skill env (`skills.entries.*.env`). CI operators may instead use `POWERLOOM_SIGNUP_PAY_CONFIRM=yes` for a single invocation; avoid leaving that variable set in autonomous sessions.\n - **TTY:** omit `--yes`; the script prompts `CONFIRM` interactively.\n Non-interactive shells refuse to broadcast without `--yes` / `POWERLOOM_SIGNUP_PAY_CONFIRM=yes` β€” this is intentional broadcast protection.\n `signup-pay.mjs` uses `quote.payment_kind`: `native_value` β†’ `sendTransaction({ value })`; `erc20` β†’ `token.transfer()`.\n3. After signup, set the `sk_live_...` API key and all six env vars in OpenClaw under\n `skills.entries.powerloom-bds-univ3.env.*`:\n `POWERLOOM_EVM_PRIVATE_KEY` (from input a), `POWERLOOM_EVM_RPC_URL`, `POWERLOOM_EVM_CHAIN_ID`, `POWERLOOM_PLAN_ID`, `POWERLOOM_TOKEN_SYMBOL`, `POWERLOOM_API_KEY` (from `signup-pay.mjs` claim output).\n Plus, if input (b) yielded values: `POWERLOOM_TELEGRAM_BOT_TOKEN`, `POWERLOOM_TELEGRAM_CHAT_ID`.\n If the schema expects strings, pass `POWERLOOM_EVM_CHAIN_ID` as a quoted string (e.g. `\"7869\"`).\n4. `scripts/whale-cron.mjs` should:\n - Use `lib/mcp.mjs` `callTool()` for all MCP calls (SSE handshake, not raw HTTP).\n - Use `lib/trade-utils.mjs` `flattenAllTradesFromSnapshot()` to parse the snapshot.\n - Response shape: `result.data.tradeData` = `{ poolAddr: { trades: [...] } }`.\n - Resolve pool token names with `bds_mpp_pool_pool_address_metadata` per unknown pool;\n cache in `.powerloom/pool-metadata-cache.json` (override with `WHALE_CRON_POOL_CACHE`).\n - Verification: `result.data.verification` = `{ cid, epochId, projectId }` β€” surface in alerts (e.g. βœ…).\n - Telegram: `parse_mode: MarkdownV2` with full escaping, or plain-text fallback.\n - If the script is missing or broken, rebuild using the skill’s `lib/*` helpers only.\n5. Create an OpenClaw cron job β€” **only after** REQUIRED INPUTS (a) and (b) above are fully resolved in chat AND `signup-pay.mjs` has produced the API key:\n - Name: e.g. \"Whale Radar\"\n - Schedule: e.g. every 15s (`--every 15s` with `openclaw cron add`)\n - Timeout: 90s (`--timeout 90000`)\n - Session: isolated (`--session isolated`)\n - Flags: `--no-deliver`, `--light-context`\n - Message: a shell command that `cd`s to the skill dir, sets env inline, then runs `node scripts/whale-cron.mjs`. Required env in the cron message:\n - `POWERLOOM_API_KEY=`\n - `POWERLOOM_BDS_MCP_CALL_TIMEOUT_MS=120000`\n - `WHALE_CRON_THRESHOLD=10000` (default; only override if I asked for a different threshold)\n - Telegram env in the cron message β€” **only** if input (b) yielded both values:\n - `POWERLOOM_TELEGRAM_BOT_TOKEN=`\n - `POWERLOOM_TELEGRAM_CHAT_ID=`\n - Do NOT consult OpenClaw `channels.telegram`, `openclaw.json`, or any other config source for Telegram credentials β€” only use what I pasted in chat for input (b).\n6. Before the first run: `rm -f .powerloom/whale-cron-state.json` if you need a clean epoch cursor.\n Keep `.powerloom/pool-metadata-cache.json` across reinstalls unless debugging metadata.\n7. Set WHALE_CRON_STATE_FILE and WHALE_CRON_POOL_CACHE to paths outside the skill directory (e.g. in the workspace root) so they survive openclaw skills install --force.\n\nConstraints:\n- **Pay-signup broadcast:** run `node scripts/signup-pay.mjs --dry-run` first unless I explicitly waive dry-run in chat; paste stderr quote summary into chat for my review; then run **`node scripts/signup-pay.mjs --yes` once** as an ephemeral shell invocation (not saved in OpenClaw skill env). CI may use `POWERLOOM_SIGNUP_PAY_CONFIRM=yes` for a single job β€” do not leave confirmation bypass variables persisted alongside wallet keys. TTY sessions type `CONFIRM` instead.\n- **Telegram credentials must be gathered from me in chat (or explicit opt-out received) BEFORE the cron job is created.** Asking me for `POWERLOOM_TELEGRAM_BOT_TOKEN` / `POWERLOOM_TELEGRAM_CHAT_ID` after running `openclaw cron add` and seeing the cron tick (with stdout-only alerts) is a known failure mode β€” fail the run and re-ask before cron creation.\n- Do NOT use OpenClaw config (`channels.telegram`, `openclaw.json`, etc.) as a fallback Telegram source β€” chat input only.\n- Use `bds_mpp_snapshot_allTrades` only (bounded batches). Do not add streaming trade tools.\n- Do NOT run the tracker as a background process β€” use OpenClaw cron only.\n- Do NOT show \"???\" for unknown tokens β€” resolve via the metadata tool or show the address.\n````\n\n---\n\n## Verification provenance (cron script + one-shot)\n\n**In `scripts/whale-cron.mjs` (already implemented):** each `bds_mpp_snapshot_allTrades` result carries `data.verification` (`cid`, `epochId`, `projectId`). The script reads that object once per poll and appends a **β€œVerified on-chain”** block (CID, epoch, project) to each formatted alert in `formatAlert` β€” it is not optional glue you add in the OpenClaw message; the one-shot above assumes this behavior.\n\n**Independent check:** the MCP tool `verify_data_provenance` can confirm commitments using the same `cid` / `epoch_id` / `project_id` β€” see **`references/03-verification.md`** and the **Verify** row in `SKILL.md` (data table).\n\n---\n\n## Related files in this skill\n\n| Item | Location |\n|------|----------|\n| Cron entrypoint (incl. verification in alerts) | `scripts/whale-cron.mjs` |\n| Pay-signup | `scripts/signup-pay.mjs` |\n| MCP + trade helpers | `lib/mcp.mjs`, `lib/trade-utils.mjs`, `lib/state.mjs` |\n| On-chain verification details | `references/03-verification.md` |\n| Integrator rules | `SKILL.md` β†’ **Hosts & integrators** |\n\nSee also `references/01-quickstart.md` and `references/06-troubleshooting.md`.\n\nFile v0.2.4:references/09-openclaw-one-shot-free-key.md\n\n# OpenClaw: free-key whale cron (one-shot prompt)\n\nUse this as a **single agent message** after running `bds-agent signup` to get a free `sk_live_...` API key (browser device flow, 2 free credits, no wallet). The skill itself only needs **`POWERLOOM_API_KEY`** at runtime β€” `whale-cron.mjs` dispatches alerts via the hosted MCP server using that key alone.\n\nFor the wallet-funded variant (autonomous on-chain pay-signup for a 10-credit plan in the same prompt), see [`references/08-openclaw-one-shot.md`](./08-openclaw-one-shot.md).\n\n---\n\n## Copy-paste prompt\n\n````\nInstall the skill \"πŸ¦„ Powerloom Uniswap V3 timeseries data\" (powerloom-bds-univ3) from ClawHub.\nAfter install, run npm install in the skill directory.\n\nI already have a Powerloom API key (sk_live_...) from `bds-agent signup` β€” 2 free credits, no wallet needed. Use that key directly. Do NOT run `scripts/signup-pay.mjs`. Do NOT ask for a private key, RPC URL, plan id, chain id, or token symbol.\n\n**REQUIRED INPUTS β€” gather BOTH from me in chat BEFORE you install the skill, wire any env, or create any cron job. STOP and ask if either is missing. Do NOT proceed to step 1 below until both are resolved. Asking me for any of these AFTER creating the cron is a failure mode β€” re-ask BEFORE cron creation.**\n\na. **Powerloom API key** β€” paste your `sk_live_...` from `bds-agent signup`. If you don't have one yet, run `bds-agent signup` first (free, 2 credits, browser device flow) and come back. Do not invent or guess a key.\n\nb. **Telegram alerts** β€” ask explicitly: \"Do you want Telegram alerts for whale swaps? If yes, paste your `POWERLOOM_TELEGRAM_BOT_TOKEN` and `POWERLOOM_TELEGRAM_CHAT_ID`. If no, type 'skip' and alerts will print to stdout only.\"\n - If I give you both tokens β†’ use them in the cron env (steps 1 and 4 below).\n - If I explicitly say \"skip\" / \"no Telegram\" / \"stdout only\" β†’ proceed without TG envs and tell me clearly in the final cron summary that alerts will only print to stdout (the cron `--no-deliver` flag means OpenClaw's chat won't see them either).\n - Do NOT silently default to \"stdout is fine.\" Either both TG values, or an explicit opt-out.\n - Do NOT look up TG credentials from any OpenClaw config source (`channels.telegram`, `openclaw.json`, etc.) β€” only use what I paste in this conversation.\n\nOnce (a) and (b) are resolved in chat, proceed with the steps below.\n\nSet up a whale radar cron with the existing key. Details:\n\n1. Set the gathered envs in OpenClaw under `skills.entries.powerloom-bds-univ3.env.*`:\n - `POWERLOOM_API_KEY` β€” required, from input (a).\n - `POWERLOOM_TELEGRAM_BOT_TOKEN`, `POWERLOOM_TELEGRAM_CHAT_ID` β€” set both **only** if I gave you values in input (b). If I opted out, leave both unset; `whale-cron.mjs` prints alerts to stdout in that case (still includes the verification block).\n\n2. Pre-flight: `node scripts/ensure-credits.mjs` to confirm the key is valid and balance is non-zero (free signup grants 2 credits).\n\n3. `scripts/whale-cron.mjs` should:\n - Use `lib/mcp.mjs` `callTool()` for all MCP calls (SSE handshake, not raw HTTP).\n - Use `lib/trade-utils.mjs` `flattenAllTradesFromSnapshot()` to parse the snapshot.\n - Response shape: `result.data.tradeData` = `{ poolAddr: { trades: [...] } }`.\n - Resolve pool token names with `bds_mpp_pool_pool_address_metadata` per unknown pool;\n cache in `.powerloom/pool-metadata-cache.json` (override with `WHALE_CRON_POOL_CACHE`).\n - Verification: `result.data.verification` = `{ cid, epochId, projectId }` β€” surface in alerts (e.g. βœ…).\n - Telegram: `parse_mode: MarkdownV2` with full escaping, or plain-text fallback.\n - If the script is missing or broken, rebuild using the skill’s `lib/*` helpers only.\n\n4. Create an OpenClaw cron job β€” **only after** REQUIRED INPUTS (a) and (b) above are fully resolved in chat:\n - Name: e.g. \"Whale Radar\"\n - Schedule: e.g. every 15s (`--every 15s` with `openclaw cron add`)\n - Timeout: 90s (`--timeout 90000`)\n - Session: isolated (`--session isolated`)\n - Flags: `--no-deliver`, `--light-context`\n - Message: a shell command that `cd`s to the skill dir, sets env inline, then runs `node scripts/whale-cron.mjs`. Required env in the cron message:\n - `POWERLOOM_API_KEY=`\n - `POWERLOOM_BDS_MCP_CALL_TIMEOUT_MS=120000`\n - `WHALE_CRON_THRESHOLD=10000` (default; only override if I asked for a different threshold)\n - Telegram env in the cron message β€” **only** if input (b) yielded both values:\n - `POWERLOOM_TELEGRAM_BOT_TOKEN=`\n - `POWERLOOM_TELEGRAM_CHAT_ID=`\n - Do NOT consult OpenClaw `channels.telegram`, `openclaw.json`, or any other config source for Telegram credentials β€” only use what I pasted in chat for input (b).\n\n5. Before the first run: `rm -f .powerloom/whale-cron-state.json` if you need a clean epoch cursor.\n Keep `.powerloom/pool-metadata-cache.json` across reinstalls unless debugging metadata.\n\n6. Set WHALE_CRON_STATE_FILE and WHALE_CRON_POOL_CACHE to paths outside the skill directory (e.g. in the workspace root) so they survive `openclaw skills install --force`.\n\nConstraints:\n- This flow uses an **existing** `sk_live_...` key only. Do NOT initiate any on-chain payment, and do NOT prompt for wallet credentials.\n- **Telegram credentials must be gathered from me in chat (or explicit opt-out received) BEFORE the cron job is created.** Asking me for `POWERLOOM_TELEGRAM_BOT_TOKEN` / `POWERLOOM_TELEGRAM_CHAT_ID` after running `openclaw cron add` and seeing the cron tick (with stdout-only alerts) is a known failure mode β€” fail the run and re-ask before cron creation.\n- Do NOT use OpenClaw config (`channels.telegram`, `openclaw.json`, etc.) as a fallback Telegram source β€” chat input only.\n- If the user later wants more credits, point them at `references/08-openclaw-one-shot.md` (wallet-funded pay-signup variant) or `node scripts/credits-topup.mjs` against the same key.\n- Use `bds_mpp_snapshot_allTrades` only (bounded batches). Do not add streaming trade tools.\n- Do NOT run the tracker as a background process β€” use OpenClaw cron only.\n- Do NOT show \"???\" for unknown tokens β€” resolve via the metadata tool or show the address.\n````\n\n---\n\n## Why this works without a wallet\n\n`scripts/whale-cron.mjs` only consumes `POWERLOOM_API_KEY` (via `lib/mcp.mjs`) plus the optional Telegram envs (`lib/powerloom-env.mjs` `telegramBotToken()` / `telegramChatId()`). The wallet/plan env getters in `lib/powerloom-env.mjs` are **only** read by `scripts/signup-pay.mjs` and `scripts/credits-topup.mjs` β€” both of which this prompt explicitly skips. The skill's `metadata.openclaw.requires.env` schema in `SKILL.md` lists wallet vars as **optional** (`optional_env`) for this exact reason.\n\nWhen the 2 free credits run out (~1440 epochs of data per credit on metered routes), upgrade in either of two ways without re-onboarding:\n\n- **Wallet-funded plan, in the agent**: paste the [wallet-funded one-shot](./08-openclaw-one-shot.md) β€” runs `signup-pay.mjs` and refreshes the API key.\n- **Top-up the existing key**: `node scripts/credits-topup.mjs` with `POWERLOOM_PLAN_ID`, `POWERLOOM_EVM_CHAIN_ID`, `POWERLOOM_TOKEN_SYMBOL`, and a funded wallet β€” adds credits to the same `sk_live_...`.\n\n---\n\n## Verification provenance (cron script + one-shot)\n\n**In `scripts/whale-cron.mjs` (already implemented):** each `bds_mpp_snapshot_allTrades` result carries `data.verification` (`cid`, `epochId`, `projectId`). The script reads that object once per poll and appends a **\"Verified on-chain\"** block (CID, epoch, project) to each formatted alert in `formatAlert` β€” it is not optional glue you add in the OpenClaw message; the one-shot above assumes this behavior. Free-key alerts carry the same verification block as wallet-funded alerts.\n\n**Independent check:** the MCP tool `verify_data_provenance` can confirm commitments using the same `cid` / `epoch_id` / `project_id` β€” see [`references/03-verification.md`](./03-verification.md) and the **Verify** row in `SKILL.md` (data table).\n\n---\n\n## Related files in this skill\n\n| Item | Location |\n|------|----------|\n| Cron entrypoint (incl. verification in alerts) | `scripts/whale-cron.mjs` |\n| Pre-flight credit check | `scripts/ensure-credits.mjs` |\n| Pay-signup (wallet-funded variant) | `scripts/signup-pay.mjs` |\n| Top-up (more credits, existing key) | `scripts/credits-topup.mjs` |\n| MCP + trade helpers | `lib/mcp.mjs`, `lib/trade-utils.mjs`, `lib/state.mjs` |\n| On-chain verification details | `references/03-verification.md` |\n| Wallet-funded one-shot variant | `references/08-openclaw-one-shot.md` |\n| Integrator rules | `SKILL.md` β†’ **Hosts & integrators** |\n\nSee also [`references/01-quickstart.md`](./01-quickstart.md) and [`references/06-troubleshooting.md`](./06-troubleshooting.md).\n\nArchive v0.2.3: 33 files, 51980 bytes\n\nFiles: package-lock.json (4617b), package.json (305b), README.md (6397b), recipes/defi-analyst.yaml (813b), recipes/token-flow.yaml (412b), recipes/whale-radar.yaml (751b), references/01-quickstart.md (1419b), references/02-tool-catalog.md (935b), references/03-verification.md (1037b), references/04-credit-budget.md (500b), references/05-data-market-scope.md (814b), references/06-troubleshooting.md (3592b), references/07-prompt-patterns.md (675b), references/08-openclaw-one-shot.md (8077b), references/09-openclaw-one-shot-free-key.md (8866b), scripts/credits-topup.mjs (6546b), scripts/defi-analyst.mjs (8252b), scripts/ensure-credits.mjs (1300b), scripts/lib/confirm-spend.mjs (1914b), scripts/lib/dispatch.mjs (1400b), scripts/lib/mcp.mjs (11542b), scripts/lib/powerloom-env.mjs (1667b), scripts/lib/recipe-config.mjs (690b), scripts/lib/state.mjs (1519b), scripts/lib/trade-utils.mjs (2134b), scripts/list-mcp-tools.mjs (488b), scripts/powerloom-mcp-client.mjs (644b), scripts/signup-pay.mjs (6462b), scripts/token-flow.mjs (4915b), scripts/whale-cron.mjs (9815b), scripts/whale-radar.mjs (4599b), SKILL.md (12658b), _meta.json (138b)\n\nFile v0.2.3:SKILL.md\n\n---\nname: powerloom-bds-univ3\ndescription: |\n Autonomous Uniswap V3 monitoring on consensus-backed data with onchain provenance.\n Every data point is finalized on-chain by Powerloom's decentralized sequencer-validator network (DSV)\n and independently verifiable via verify_data_provenance. Ships with Whale Radar,\n Token-Flow, and Autonomous DeFi Analyst recipes.\n **Two onboarding paths**: (1) **free** β€” drop in an existing `sk_live_...` from `bds-agent signup`\n (browser device flow, 2 free credits, no wallet) and run cron immediately\n (see `references/09-openclaw-one-shot-free-key.md`); (2) **wallet-funded** β€” autonomous\n on-chain pay-signup via `scripts/signup-pay.mjs` for a 10-credit plan in the same prompt\n (see `references/08-openclaw-one-shot.md`). The runtime data path needs only `POWERLOOM_API_KEY`;\n wallet env vars are required only by the pay-signup and top-up scripts.\n Billing: metering service HTTP APIs; optional bds-agent CLI.\n Triggers on phrases like \"whale alert\", \"track trades\", \"all trades for\", \"by token\",\n \"ERC20\", \"ERC20 token swaps\", \"Powerloom\", \"verify on-chain\", \"verified data\".\nversion: 0.2.3\nhomepage: https://bds-metering.powerloom.io\nrepository: https://github.com/powerloom/powerloom-bds-univ3\ntags:\n - defi\n - uniswap\n - ethereum\n - on-chain\n - verifiable\n - consensus\n - agent\nmetadata:\n openclaw:\n emoji: \"πŸ¦„\"\n requires:\n bins: [\"node\"]\n env:\n # Only POWERLOOM_API_KEY is mandatory at install time. The free-key path\n # (references/09-openclaw-one-shot-free-key.md) needs nothing else from\n # this skill's perspective. Wallet/plan envs below are optional and only\n # consumed by scripts/signup-pay.mjs and scripts/credits-topup.mjs.\n - POWERLOOM_API_KEY\n optional_env:\n # Wallet-funded variants (signup-pay or credits-topup) β€” only required\n # if the user invokes those scripts. See references/08-openclaw-one-shot.md.\n - POWERLOOM_EVM_PRIVATE_KEY\n - POWERLOOM_EVM_RPC_URL\n - POWERLOOM_EVM_CHAIN_ID\n - POWERLOOM_PLAN_ID\n - POWERLOOM_TOKEN_SYMBOL\n # Dispatch + transport overrides β€” never required.\n - POWERLOOM_MCP_URL\n - POWERLOOM_TELEGRAM_BOT_TOKEN\n - POWERLOOM_TELEGRAM_CHAT_ID\n - POWERLOOM_DISCORD_WEBHOOK_URL\n - POWERLOOM_BDS_MCP_CALL_TIMEOUT_MS\n - POWERLOOM_BDS_MCP_DEBUG\n - POWERLOOM_METERING_BASE_URL\n - POWERLOOM_AGENT_NAME\n - POWERLOOM_EMAIL\n---\n\n# Powerloom BDS β€” Uniswap V3\n\n## Install\n\n> **Two onboarding paths.**\n>\n> **Free** β€” run `bds-agent signup` (browser device flow, no wallet, 2 free credits), then paste [`references/09-openclaw-one-shot-free-key.md`](references/09-openclaw-one-shot-free-key.md) into OpenClaw. Sets `POWERLOOM_API_KEY` and a Whale Radar cron. Nothing else needed.\n>\n> **Wallet-funded** β€” paste [`references/08-openclaw-one-shot.md`](references/08-openclaw-one-shot.md) and `scripts/signup-pay.mjs` runs an autonomous on-chain payment for a 10-credit plan in the same prompt.\n>\n> **⚠️ WARNING β€” wallet-funded path only:** `signup-pay.mjs` and `credits-topup.mjs` need an EVM private key to broadcast on-chain payments. Use a **burner wallet** with limited funds dedicated to this purpose. Never use a wallet holding significant assets or with extensive transaction history for agentic setups. The free-key path **does not** require any wallet credentials.\n\n**Contract:** [bds-agenthub-billing-metering](https://github.com/powerloom/bds-agenthub-billing-metering). **ClawHub** users only need a **single origin** (default [bds-metering.powerloom.io](https://bds-metering.powerloom.io))β€” **`bds-agent` commands are optional**; they are a reference CLI for the same JSON bodies you can send with `curl` + a wallet or `ethers`.\n\n### Metering HTTP (authoritative)\n\n| What | How |\n|------|-----|\n| List SKUs | `GET {BASE}/credits/plans` β€” no auth. Choose a plan row: `id`, `chain_id`, `token_symbol` (and note `payment_kind`: ERC-20 vs native / CGT). **`chains[].rpc_url`** is a **public** JSON-RPC hint only when the metering deployment sets it; it may be **empty** β€” use **`POWERLOOM_EVM_RPC_URL`** for wallet / script calls in\n\nArchive v0.2.2: 32 files, 49387 bytes\n\nFiles: package-lock.json (4617b), package.json (305b), README.md (6126b), recipes/defi-analyst.yaml (813b), recipes/token-flow.yaml (412b), recipes/whale-radar.yaml (751b), references/01-quickstart.md (1419b), references/02-tool-catalog.md (935b), references/03-verification.md (1037b), references/04-credit-budget.md (500b), references/05-data-market-scope.md (814b), references/06-troubleshooting.md (3592b), references/07-prompt-patterns.md (675b), references/08-openclaw-one-shot.md (7147b), references/09-openclaw-one-shot-free-key.md (8866b), scripts/credits-topup.mjs (5213b), scripts/defi-analyst.mjs (8252b), scripts/ensure-credits.mjs (1300b), scripts/lib/dispatch.mjs (1400b), scripts/lib/mcp.mjs (11542b), scripts/lib/powerloom-env.mjs (1667b), scripts/lib/recipe-config.mjs (690b), scripts/lib/state.mjs (1519b), scripts/lib/trade-utils.mjs (2134b), scripts/list-mcp-tools.mjs (488b), scripts/powerloom-mcp-client.mjs (644b), scripts/signup-pay.mjs (4991b), scripts/token-flow.mjs (4915b), scripts/whale-cron.mjs (9815b), scripts/whale-radar.mjs (4599b), SKILL.md (12304b), _meta.json (138b)\n\nArchive v0.2.1: 32 files, 48389 bytes\n\nFiles: package-lock.json (4617b), package.json (305b), README.md (6126b), recipes/defi-analyst.yaml (813b), recipes/token-flow.yaml (412b), recipes/whale-radar.yaml (751b), references/01-quickstart.md (1419b), references/02-tool-catalog.md (935b), references/03-verification.md (1037b), references/04-credit-budget.md (500b), references/05-data-market-scope.md (814b), references/06-troubleshooting.md (3592b), references/07-prompt-patterns.md (675b), references/08-openclaw-one-shot.md (4498b), references/09-openclaw-one-shot-free-key.md (8866b), scripts/credits-topup.mjs (5213b), scripts/defi-analyst.mjs (8252b), scripts/ensure-credits.mjs (1300b), scripts/lib/dispatch.mjs (1400b), scripts/lib/mcp.mjs (11542b), scripts/lib/powerloom-env.mjs (1667b), scripts/lib/recipe-config.mjs (690b), scripts/lib/state.mjs (1519b), scripts/lib/trade-utils.mjs (2134b), scripts/list-mcp-tools.mjs (488b), scripts/powerloom-mcp-client.mjs (644b), scripts/signup-pay.mjs (4991b), scripts/token-flow.mjs (4915b), scripts/whale-cron.mjs (9815b), scripts/whale-radar.mjs (4599b), SKILL.md (12304b), _meta.json (138b)\n\nArchive v0.1.1: 32 files, 47520 bytes\n\nFiles: package-lock.json (4617b), package.json (305b), README.md (6126b), recipes/defi-analyst.yaml (813b), recipes/token-flow.yaml (412b), recipes/whale-radar.yaml (751b), references/01-quickstart.md (1419b), references/02-tool-catalog.md (935b), references/03-verification.md (1037b), references/04-credit-budget.md (500b), references/05-data-market-scope.md (814b), references/06-troubleshooting.md (3592b), references/07-prompt-patterns.md (675b), references/08-openclaw-one-shot.md (4498b), references/09-openclaw-one-shot-free-key.md (6530b), scripts/credits-topup.mjs (5213b), scripts/defi-analyst.mjs (8252b), scripts/ensure-credits.mjs (1300b), scripts/lib/dispatch.mjs (1400b), scripts/lib/mcp.mjs (11542b), scripts/lib/powerloom-env.mjs (1667b), scripts/lib/recipe-config.mjs (690b), scripts/lib/state.mjs (1519b), scripts/lib/trade-utils.mjs (2134b), scripts/list-mcp-tools.mjs (488b), scripts/powerloom-mcp-client.mjs (644b), scripts/signup-pay.mjs (4991b), scripts/token-flow.mjs (4915b), scripts/whale-cron.mjs (9815b), scripts/whale-radar.mjs (4599b), SKILL.md (12302b), _meta.json (138b)\n\nArchive v0.1.0: 31 files, 43629 bytes\n\nFiles: package-lock.json (4617b), package.json (305b), README.md (5555b), recipes/defi-analyst.yaml (813b), recipes/token-flow.yaml (412b), recipes/whale-radar.yaml (751b), references/01-quickstart.md (1419b), references/02-tool-catalog.md (935b), references/03-verification.md (1037b), references/04-credit-budget.md (500b), references/05-data-market-scope.md (814b), references/06-troubleshooting.md (3592b), references/07-prompt-patterns.md (675b), references/08-openclaw-one-shot.md (4498b), scripts/credits-topup.mjs (5213b), scripts/defi-analyst.mjs (8252b), scripts/ensure-credits.mjs (1300b), scripts/lib/dispatch.mjs (1400b), scripts/lib/mcp.mjs (11542b), scripts/lib/powerloom-env.mjs (1667b), scripts/lib/recipe-config.mjs (690b), scripts/lib/state.mjs (1519b), scripts/lib/trade-utils.mjs (2134b), scripts/list-mcp-tools.mjs (488b), scripts/powerloom-mcp-client.mjs (644b), scripts/signup-pay.mjs (4991b), scripts/token-flow.mjs (4915b), scripts/whale-cron.mjs (9815b), scripts/whale-radar.mjs (4599b), SKILL.md (9940b), _meta.json (138b)\n\nArchive v0.0.9: 31 files, 44936 bytes\n\nFiles: package-lock.json (4617b), package.json (305b), README.md (5348b), recipes/defi-analyst.yaml (1206b), recipes/token-flow.yaml (415b), recipes/whale-radar.yaml (1157b), references/01-quickstart.md (1432b), references/02-tool-catalog.md (1319b), references/03-verification.md (1037b), references/04-credit-budget.md (446b), references/05-data-market-scope.md (747b), references/06-troubleshooting.md (3590b), references/07-prompt-patterns.md (787b), references/08-openclaw-one-shot.md (4506b), scripts/credits-topup.mjs (5213b), scripts/defi-analyst.mjs (7983b), scripts/ensure-credits.mjs (1300b), scripts/lib/dispatch.mjs (1400b), scripts/lib/mcp.mjs (11527b), scripts/lib/powerloom-env.mjs (1667b), scripts/lib/recipe-config.mjs (690b), scripts/lib/state.mjs (1519b), scripts/lib/trade-utils.mjs (2134b), scripts/list-mcp-tools.mjs (488b), scripts/powerloom-mcp-client.mjs (644b), scripts/signup-pay.mjs (4991b), scripts/token-flow.mjs (6701b), scripts/whale-cron.mjs (9815b), scripts/whale-radar.mjs (6190b), SKILL.md (10275b), _meta.json (138b)\n\nArchive v0.0.8: 30 files, 43941 bytes\n\nFiles: package-lock.json (4617b), package.json (305b),...","readmeExcerpt":"Skill: πŸ¦„ Powerloom Uniswap V3 timeseries data Owner: powerloom-bot Summary: Autonomous Uniswap V3 monitoring on consensus-backed data with onchain provenance. Every data point is finalized on-chain by Powerloom's DSV network and inde... Tags: latest:0.2.6 Version history: v0.2.6 | 2026-05-14T17:55:55.949Z | user powerloom-bds-univ3 v0.2.6 - Version bump to 0.2.6; no file changes detected. - Clarify and correct 1 cre","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"cd powerloom-bds-univ3\nnpm install\nexport POWERLOOM_API_KEY=sk_live_...\nnode scripts/ensure-credits.mjs"},{"language":"bash","snippet":"export POWERLOOM_API_KEY=sk_live_...\nnode scripts/list-mcp-tools.mjs"},{"language":"bash","snippet":"npx clawhub login\nnpx clawhub publish . --slug powerloom-bds-univ3 --version 0.1.0"},{"language":"text","snippet":"Install the skill \"πŸ¦„ Powerloom Uniswap V3 timeseries data\" (powerloom-bds-univ3) from ClawHub.\nAfter install, run npm install in the skill directory.\n\n**REQUIRED INPUTS β€” gather BOTH from me in chat BEFORE running `signup-pay.mjs` or creating any cron job. STOP and ask if either is missing. Do NOT proceed past this section with values unresolved. Asking me for any of these AFTER the cron job is created is a failure mode β€” re-ask BEFORE cron creation.**\n\na. **Payer wallet private key** β€” paste your EVM private key for the funded wallet that will pay 50 $POWER for the credit plan. **Use a burner wallet only** β€” never a wallet holding significant assets or with extensive transaction history. This key is consumed by `node scripts/signup-pay.mjs` and stored in OpenClaw env as `POWERLOOM_EVM_PRIVATE_KEY`.\n\nb. **Telegram alerts** β€” ask explicitly: \"Do you want Telegram alerts for whale swaps? If yes, paste your `POWERLOOM_TELEGRAM_BOT_TOKEN` and `POWERLOOM_TELEGRAM_CHAT_ID`. If no, type 'skip' and alerts will print to stdout only.\"\n - If I give you both tokens β†’ use them in the cron env (step 5 below).\n - If I explicitly say \"skip\" / \"no Telegram\" / \"stdout only\" β†’ proceed without TG envs and tell me clearly in the final cron summary that alerts will only print to stdout (the cron `--no-deliver` flag means OpenClaw's chat won't see them either).\n - Do NOT silently default to \"stdout is fine.\" Either both TG values, or an explicit opt-out.\n - Do NOT look up TG credentials from any OpenClaw config source (`channels.telegram`, `openclaw.json`, etc.) β€” only use what I paste in this conversation.\n\nOnce (a) and (b) are resolved in chat, proceed with the steps below.\n\nThen set up pay-signup and a whale radar cron. Details:\n\n1. PLAN: launch_10_pl_power_cgt (POWER native on chain 7869, rpc-v2.powerloom.network)\n2. Pay-signup using `scripts/signup-pay.mjs` with the private key from input (a):\n - **Recommended:** run `node scripts/signup-pay.mjs --dry-run` first β€” prints q"},{"language":"text","snippet":"Install the skill \"πŸ¦„ Powerloom Uniswap V3 timeseries data\" (powerloom-bds-univ3) from ClawHub.\nAfter install, run npm install in the skill directory.\n\nI already have a Powerloom API key (sk_live_...) from `bds-agent signup` β€” 2 free credits, no wallet needed. Use that key directly. Do NOT run `scripts/signup-pay.mjs`. Do NOT ask for a private key, RPC URL, plan id, chain id, or token symbol.\n\n**REQUIRED INPUTS β€” gather BOTH from me in chat BEFORE you install the skill, wire any env, or create any cron job. STOP and ask if either is missing. Do NOT proceed to step 1 below until both are resolved. Asking me for any of these AFTER creating the cron is a failure mode β€” re-ask BEFORE cron creation.**\n\na. **Powerloom API key** β€” paste your `sk_live_...` from `bds-agent signup`. If you don't have one yet, run `bds-agent signup` first (free, 2 credits, browser device flow) and come back. Do not invent or guess a key.\n\nb. **Telegram alerts** β€” ask explicitly: \"Do you want Telegram alerts for whale swaps? If yes, paste your `POWERLOOM_TELEGRAM_BOT_TOKEN` and `POWERLOOM_TELEGRAM_CHAT_ID`. If no, type 'skip' and alerts will print to stdout only.\"\n - If I give you both tokens β†’ use them in the cron env (steps 1 and 4 below).\n - If I explicitly say \"skip\" / \"no Telegram\" / \"stdout only\" β†’ proceed without TG envs and tell me clearly in the final cron summary that alerts will only print to stdout (the cron `--no-deliver` flag means OpenClaw's chat won't see them either).\n - Do NOT silently default to \"stdout is fine.\" Either both TG values, or an explicit opt-out.\n - Do NOT look up TG credentials from any OpenClaw config source (`channels.telegram`, `openclaw.json`, etc.) β€” only use what I paste in this conversation.\n\nOnce (a) and (b) are resolved in chat, proceed with the steps below.\n\nSet up a whale radar cron with the existing key. Details:\n\n1. Set the gathered envs in OpenClaw under `skills.entries.powerloom-bds-univ3.env.*`:\n - `POWERLOOM_API_KEY` β€” required, from i"},{"language":"bash","snippet":"cd powerloom-bds-univ3\nnpm install\nexport POWERLOOM_API_KEY=sk_live_...\nnode scripts/ensure-credits.mjs"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: powerloom-bds-univ3\ndescription: |\n Autonomous Uniswap V3 monitoring on consensus-backed data with onchain provenance.\n Every data point is finalized on-chain by Powerloom's DSV network and independently\n verifiable. Ships with Whale Radar, Token-Flow, and DeFi Analyst recipes.\n Free API key at bds-metering.powerloom.io/metering (2 credits, no wallet).\n Triggers on \"whale alert\", \"track trades\", \"all trades for\", \"by token\",\n \"Powerloom\", \"verify on-chain\", \"verified data\".\nversion: 0.2.6\nhomepage: https://bds-metering.powerloom.io\nrepository: https://github.com/powerloom/powerloom-bds-univ3\ntags:\n - defi\n - uniswap\n - ethereum\n - on-chain\n - verifiable\n - consensus\n - agent\nmetadata:\n openclaw:\n emoji: \"πŸ¦„\"\n requires:\n bins: [\"node\"]\n env:\n # Only POWERLOOM_API_KEY is mandatory at install time. The free-key path\n # (references/09-openclaw-one-shot-free-key.md) needs nothing else from\n # this skill's perspective. Wallet/plan envs below are optional and only\n # consumed by scripts/signup-pay.mjs and scripts/credits-topup.mjs.\n - POWERLOOM_API_KEY\n optional_env:\n # Wallet-funded variants (signup-pay or credits-topup) β€” only required\n # if the user invokes those scripts. See references/08-openclaw-one-shot.md.\n - POWERLOOM_EVM_PRIVATE_KEY\n - POWERLOOM_EVM_RPC_URL\n - POWERLOOM_EVM_CHAIN_ID\n - POWERLOOM_PLAN_ID\n - POWERLOOM_TOKEN_SYMBOL\n # Dispatch + transport overrides β€” never required.\n - POWERLOOM_MCP_URL\n - POWERLOOM_TELEGRAM_BOT_TOKEN\n - POWERLOOM_TELEGRAM_CHAT_ID\n - POWERLOOM_DISCORD_WEBHOOK_URL\n - POWERLOOM_BDS_MCP_CALL_TIMEOUT_MS\n - POWERLOOM_BDS_MCP_DEBUG\n - POWERLOOM_METERING_BASE_URL\n - POWERLOOM_AGENT_NAME\n - POWERLOOM_EMAIL\n---\n\n# Powerloom BDS β€” Uniswap V3\n\n## Install\n\n> **Two onboarding paths.**\n>\n> **Free** β€” sign up at [`bds-metering.powerloom.io/metering`](https://bds-metering.powerloom.io/metering) (enter email + agent name, complete Turnstile, get `sk_live_...` immediately β€” no CLI, no wallet, 2 free credits). Alternatively, `bds-agent signup` runs the same flow from the terminal. Then paste [`references/09-openclaw-one-shot-free-key.md`](references/09-openclaw-one-shot-free-key.md) into OpenClaw. Sets `POWERLOOM_API_KEY` and a Whale Radar cron. Nothing else needed.\n>\n> **Wallet-funded** β€” paste [`references/08-openclaw-one-shot.md`](references/08-openclaw-one-shot.md) and `scripts/signup-pay.mjs` runs an autonomous on-chain payment for a 10-credit plan in the same prompt.\n>\n> **⚠️ WARNING β€” wallet-funded path only:** `signup-pay.mjs` and `credits-topup.mjs` need an EVM private key to broadcast on-chain payments. Use a **burner wallet** with limited funds dedicated to this purpose. Never use a wallet holding significant assets or with extensive transaction history for agentic setups. The free-key path **does not** require any wallet cre"},{"path":"README.md","content":"# Powerloom BDS β€” Uniswap V3 (ClawHub skill)\n\n## Autonomous Uniswap V3 monitoring + onchain provenance verification, in minutes. Decentralized data, not trust-me data.\n\nEvery data point this skill fetches is finalized onchain by Powerloom's decentralized sequencer-validator network. The `verify_data_provenance` tool compares API CIDs to onchain commitments so alerts can carry a cryptographic receipt, not a vendor's word.\n\n## Recipes\n\n- **Whale Radar** β€” USD-threshold alerts: **`bds_mpp_snapshot_trades_pool_address`** for each pool in `poll_fallback_pools`. For **cron / OpenClaw heartbeats** over **all** pools in one bounded batch, use **`node scripts/whale-cron.mjs`** (`bds_mpp_snapshot_allTrades` + pool metadata).\n- **Token-Flow** β€” all swaps touching a configured token (default USDC) across pools derived at runtime.\n- **Autonomous DeFi Analyst** β€” default **multi-pool** `bds_mpp_snapshot_allTrades` + all-pools token volume; set **`filters.scope: single_pool`** in `recipes/defi-analyst.yaml` for single-pool snapshots only.\n\n## Integrators (OpenClaw, cron)\n\n**End-to-end one-shot prompts** β€” pick by onboarding state:\n\n| Variant | Use when | Reference |\n|---------|----------|-----------|\n| Free-key cron | You already have `sk_live_...` from `bds-agent signup` (2 free credits, no wallet) | **`references/09-openclaw-one-shot-free-key.md`** |\n| Pay-signup + cron | You want autonomous wallet-funded onboarding for a 10-credit plan in the same prompt | **`references/08-openclaw-one-shot.md`** |\n\n**Default behavior:** `whale-radar.mjs`, `token-flow.mjs`, and `defi-analyst.mjs` each run **one bounded round** and **exit** (safe for cron). Use **`--daemon`** only if you want a local repeat loop (`heartbeat.interval_seconds` between rounds).\n\nFor **scheduled heartbeats**, prefer **`whale-cron.mjs`** (exits) or the recipe scripts **without** `--daemon`. This repo does not ship streaming trade consumption.\n\n## Setup\n\n```bash\ncd powerloom-bds-univ3\nnpm install\nexport POWERLOOM_API_KEY=sk_live_...\nnode scripts/ensure-credits.mjs\n```\n\n**Where to get `POWERLOOM_API_KEY`:**\n\n- **Free** (no wallet, 2 credits): `bds-agent signup` β€” browser device flow on the metering service. Same `sk_live_...` works against this skill, the hosted MCP server, and any pay-signup top-up later.\n- **Wallet-funded** (10-credit plan): `node scripts/signup-pay.mjs --dry-run` (quote summary only), then **`node scripts/signup-pay.mjs --yes`** once after verifying stderr output β€” prefer argv over env so confirmation bypass is **not** persisted in OpenClaw skill config. CI may use `POWERLOOM_SIGNUP_PAY_CONFIRM=yes` for a single invocation only. **Native or ERC-20** per `quote.payment_kind` (POWER CGT on 7869 = native).\n- **More credits, existing key**: `node scripts/credits-topup.mjs` β€” same `--dry-run` β†’ **`--yes`** pattern (or one-shot env for CI only). See **`SKILL.md`**.\n\nOptional: `POWERLOOM_TELEGRAM_BOT_TOKEN`, `POWERLOOM_TELEGRAM_CHAT_ID`, and `dispatch.channel: telegram` in `recipes/*.ya"},{"path":"_meta.json","content":"{\n \"ownerId\": \"kn7a3wb3bny97qvtprbgh9cxe185fms0\",\n \"slug\": \"powerloom-bds-univ3\",\n \"version\": \"0.2.6\",\n \"publishedAt\": 1778781355949\n}"},{"path":"references/01-quickstart.md","content":"# Quickstart (~10 minutes)\n\n1. **Get an API key** β€” **CLI / API:** metering origin [bds-metering.powerloom.io](https://bds-metering.powerloom.io) (`bds-agent signup`; see [agent guide](https://github.com/powerloom/bds-agent-py/blob/main/docs/USER_GUIDE.md)). **Browser:** signup and top-ups at [bds-metering.powerloom.io/metering](https://bds-metering.powerloom.io/metering).\n2. **Export** `POWERLOOM_API_KEY=sk_live_...` in the environment OpenClaw uses (or your shell profile).\n3. **Optional** β€” default MCP URL is `https://bds-mcp.powerloom.io/sse`. Override with `POWERLOOM_MCP_URL` if directed.\n4. **Check credits**: `node scripts/ensure-credits.mjs` β€” should print balance JSON and exit 0.\n5. **OpenClaw / cron** β€” for **one-shot schedulers** (recommended), use **`node scripts/whale-cron.mjs`** and the full copy-paste flow in **`references/08-openclaw-one-shot.md`**. For a **fixed pool list** and local poll loop, use **`whale-radar.mjs`** (per-pool snapshots only).\n6. **Run a recipe** (stdout first):\n - Whale cron (bounded, all pools): `node scripts/whale-cron.mjs`\n - Whale Radar (fixed pools, poll): `node scripts/whale-radar.mjs`\n - Token-Flow: `node scripts/token-flow.mjs`\n - DeFi Analyst (one round, cron): `node scripts/defi-analyst.mjs`\n7. **Telegram** β€” set `POWERLOOM_TELEGRAM_BOT_TOKEN` and `POWERLOOM_TELEGRAM_CHAT_ID`, set `dispatch.channel` to `telegram` in the recipe yaml."},{"path":"references/02-tool-catalog.md","content":"# BDS MCP tool catalog (representative)\n\nAll calls are metered unless noted. **Defaults:** `POWERLOOM_BDS_MCP_CALL_TIMEOUT_MS=60000` (raise for large `bds_mpp_snapshot_allTrades` responses under backlog, e.g. `120000`).\n\n**Skill note:** `powerloom-bds-univ3` recipes use **snapshot** tools only (`bds_mpp_snapshot_*`). Streaming catalog tools exist on the hosted MCP server for direct/advanced use but are **not** invoked by shipped scripts.\n\n| Tool | What | Typical latency | Skill usage |\n|------|------|-----------------|-------------|\n| `bds_mpp_snapshot_allTrades` | One-shot all pools (bounded batch) | 8–45s | `whale-cron.mjs`, DeFi Analyst multi |\n| `bds_mpp_snapshot_trades_pool_address` | One pool snapshot | 2–15s | `whale-radar.mjs`, `token-flow.mjs` |\n| `bds_mpp_stream_allTrades` | Streaming batches (long-lived upstream) | varies | **Not used by skill** |\n\nSee the live server’s `tools/list` for the full catalog."}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":null,"editorialQuality":{"score":100,"threshold":65,"status":"thin","wordCount":1987,"uniquenessScore":37,"reasons":["uniqueness-below-45"]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-11T08:17:55.695Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-11T08:17:55.695Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-11T10:52:26.416Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation β€’ (~400 MCP servers for AI agents) β€’ AI Automation / AI Agent with MCPs β€’ AI Workflows & AI Agents β€’ MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}