feat(lunarcrush): document live /social-velocity endpoint + scanner companion

[JoeVezzani]

Summary

• Promotes social-velocity from the "planned" list to a live, documented x402 endpoint. The route has been deployed on lunarcrush-x402-poc-prod.lunarcrush.workers.dev/social-velocity/:symbol and prices at $0.005 USD in STX, matching the existing `score` tier.
• Adds a `velocity` CLI subcommand mirroring the `score` pattern (typed args, free header path, decoded payment receipt).
• Fixes the `meta` subcommand to call /meta rather than / (root is not served by the deployed Worker).
• Adds a Companion section pointing to the new bitflow-sentiment-scanner Worker (live at bitflow-sentiment-scanner.lunarcrush.workers.dev), which ranks Stacks-ecosystem tokens by composite LC signal × Bitflow tradability and exposes /scan as a $0.01 paid agent endpoint backed by the same pay-to wallet.

Test plan

• CLI typecheck (no new TS errors)
• Live probe: curl /social-velocity/btc returns 402 with the expected payment-required header (mainnet)
• Live probe: curl /meta returns the endpoint catalog and current microSTX prices
• Reviewer: confirm wording / pricing positioning is consistent with the rest of the skills directory

🤖 Generated with Claude Code

[arc0btc]

Adds the lunarcrush skill — live /social-velocity endpoint documented, velocity and oracle subcommands added, meta route fix included, and the Bitflow × LunarCrush scanner companion surfaced.

What looks good:

• Solid input validation in normalizeSymbol (/^[a-z0-9]+$/, max 16 chars) — stops malformed symbols before they hit the wire
• resolveHost gives a clear error on invalid --network values instead of silently falling through
• AGENT.md cost guardrails are thorough: wallet-balance pre-check, 60s dedup window, budget-bounded flow pattern, and a break-even analysis pointing heavy users toward the subscription tier
• Consistent with the skills directory pattern — SKILL.md + AGENT.md + shared createApiClient / printJson / handleError utilities

[suggestion] Extract a shared paid-command helper (lunarcrush/lunarcrush.ts)
The oracle, score, and velocity actions are structurally identical — create client, call endpoint, merge receipt, print. A small helper reduces future drift:

async function runPaidCommand(baseUrl: string, network: NetworkOption, path: string): Promise<void> {
  const api = await createApiClient(baseUrl, `lunarcrush.${path.split("/")[1]}`);
  const response = await api.request({ method: "GET", url: path });
  const output: Record<string, unknown> = {
    ...((response.data as Record<string, unknown>) ?? {}),
    network,
    endpoint: `${baseUrl}${path}`,
  };
  const receipt = decodePaymentReceipt(response.headers?.["payment-response"]);
  if (receipt) output.payment_receipt = receipt;
  printJson(output);
}

[suggestion] README table entry undersells the skill
The current description mentions only Galaxy Score / AltRank fields. Since this PR ships oracle and velocity too, the description could acknowledge the full surface:

| [lunarcrush](./lunarcrush/) | `lunarcrush/lunarcrush.ts` | LunarCrush social/market intelligence via x402 on Stacks — oracle verdict, Galaxy Score, AltRank, social velocity/sentiment. USD-pegged pricing (~$0.005–$0.025/call) recomputed hourly from live STX/USD. |

[question] Is the oracle vibe field LLM-generated server-side?
The example output includes emoji and natural-language commentary. If the Worker invokes an LLM to generate vibe, that adds latency and upstream cost variability that agents should know about before calling oracle at scale. Worth noting in AGENT.md if so.

Code quality notes:

• The three paid commands copy the same 10-line action body. The helper above would consolidate this.
• decodePaymentReceipt's silent catch is correct here — malformed headers shouldn't crash a successful call.

Operational note: We run x402 calls through x402-relay.aibtc.com daily (file-signal payments). The pattern of checking wallet balance before calling and caching the prior response to skip duplicate calls within 60s matches our own sensor pre-screen pattern — solid defensive defaults for autonomous agents.

[JoeVezzani]

Thanks for the thorough review @arc0btc — all three points addressed in the latest push:

[suggestion] Shared paid-command helper — done. Extracted runPaidCommand({ symbolRaw, networkRaw, path, apiKey }) and refactored oracle, score, and velocity to call through it. Drops the structural duplication you flagged. (commit)

[suggestion] README table entry — done. Updated to reflect the full skill surface (oracle verdict + vibe, Galaxy Score, AltRank, social velocity/sentiment) with the wider $0.005-$0.025/call pricing range.

[question] Is vibe LLM-generated? — No. Both verdict and vibe on /oracle are deterministic synthesis from the composite score (Galaxy 45% / AltRank 35% / 24h momentum 20%). vibe is selected from six templated one-liners keyed by verdict tier. No GPT/Claude/Gemini call inside, so oracle latency is just the LunarCrush v4 fetch + microseconds of arithmetic. Documented that explicitly in AGENT.md so agents know calling oracle at scale carries no variable AI cost on top of the $0.025 fixed price.

Appreciate the operational note about the relay + 60s dedup pattern — that's exactly the use case the wallet-balance guardrail in AGENT.md was written for.

[secret-mars]

Substantive review — Approve with optional polish + rebase pending.

Clean doc-PR-first promotion of the social-velocity endpoint from "planned" to "live" + CLI wiring + meta path fix + companion scanner cross-link. Reads consistent with the rest of the skills directory tone.

What I verified

• README row addition matches the format used by pillar, query, x402, etc. — naming convention and tagline-length consistent.
• AGENT.md covers the four standard sections we have on agent-mode skills (prerequisites + decision logic + error handling + safety) — closest peer in the directory is the x402 skill's AGENT.md.
• SKILL.md frontmatter (name, description, arguments, entry, requires, tags: l2, read-only, requires-funds) — frontmatter looks complete; tags match precedent.
• CLI diff: velocity subcommand mirrors score's pattern exactly per the PR body claim — confirmed in the .command("velocity") block + apiKey: "lunarcrush.velocity" + path: /social-velocity/${s}.

Findings

1. AGENT.md prerequisites — balance headroom math is tight

lunarcrush/AGENT.md:

Each score call costs ~$0.005 USD worth of STX (~22,000 microSTX at $0.22 STX). Verify balance is at least 100,000 microSTX before calling to leave headroom.

100k microSTX is ~4-5 calls of headroom. If an agent is doing batch checks (e.g. validating 10 trade signals in a flow) the recommended minimum is already insufficient. Consider either:

• Document a budget envelope variable (MAX_LUNARCRUSH_SPEND_MICROSTX) and decrement-after-each-call pattern (you actually do this later under "Cost guardrails" — could promote that to the prerequisites section)
• Or restate as "100k microSTX per single call; for batch operations multiply by N + reserve headroom"

Either prevents the surprise-empty-wallet failure mode.

2. AGENT.md soft-failure: payment-consumed-on-upstream-failure

lunarcrush/AGENT.md error table:

200 with galaxy_score: null + warning | LunarCrush upstream failed but we still paid. Log the warning, treat as soft-failure, skip downstream signal generation.

The behavior is documented honestly but it's still a real UX gap — paying for null data isn't fun. Out-of-scope for this PR but worth tracking as a follow-up: relay-side conditional refund OR worker-side pre-check (HEAD upstream before issuing 402) would close the loop. Could be a great companion issue to file once this lands. I'd be happy to file it cross-referencing this PR if you'd like.

3. SKILL.md velocity — momentum_tier thresholds undocumented

lunarcrush/SKILL.md velocity section shows:

"percent_change_24h": 1.40,
"momentum_tier": "stable",

The doc lists the 3 tiers (accelerating, stable, cooling) but doesn't define the threshold cutoffs. As a reviewer/integrator I can't tell whether a +5% / +10% / +20% price move would push the tier to accelerating. The CLI .ts diff doesn't surface the threshold logic either — it lives server-side in the Worker.

For the score/oracle skill the doc explicitly defines tier bands (STRONG-BUY ≥75, BUY 60-74, etc.) — applying the same pattern to velocity.momentum_tier would make it equally inspectable. ~3 lines of doc:

momentum_tier is bucketed from percent_change_24h: accelerating ≥ X%, cooling ≤ -X%, stable otherwise.

Filling in X from the Worker's own logic.

4. Mechanical: DIRTY merge state

gh pr view 392 shows mergeStateStatus: DIRTY — needs a rebase against main before merge. Snyk is green; no CI test job visible (skills repo precedent).

Out-of-scope thought

The oracle doc claim — "deterministic synthesis (no LLM, no upstream variability, no extra latency beyond the LunarCrush API call)" — is a strong differentiator. If accurate, it's a useful selling point against LLM-wrapper alternatives. Reviewer with access to the Worker source should spot-check (this PR is doc-only, so the claim isn't verifiable from this diff alone).

Verdict

LGTM with rebase. The 3 polish items (balance math, momentum thresholds, soft-failure follow-up) are all optional. Happy to file a separate issue on the payment-consumed-on-null follow-up if useful.

— Secret Mars

[JoeVezzani]

Thanks for the substantive review @secret-mars — items 1 and 3 addressed in the latest push, items 2 and 4 noted below:

[1] Balance headroom math — fixed. AGENT.md now spells out the batch envelope: (per_call_microSTX * planned_call_count) + 100,000 microSTX safety reserve. Per-call costs also split out by tier (score/velocity ~22K µSTX, oracle ~115K µSTX at STX $0.22). Removes the surprise-empty-wallet failure mode for any batch > 4 calls.

[3] momentum_tier thresholds — documented in SKILL.md. accelerating > +5%, cooling < −5%, stable otherwise. Same deterministic-and-inspectable pattern as the oracle verdict tiers.

[2] Payment-consumed-on-upstream-null — agreed, out-of-scope for this PR but a real follow-up. Please file the companion issue cross-referencing #392 if you have a minute — the cleanest fix is probably the relay-side conditional refund path, but a worker-side HEAD pre-check at the LunarCrush v4 API is also viable.

[4] DIRTY merge state — rebased against main in this push.

[Out-of-scope] oracle deterministic synthesis claim — confirmed. The Worker source (private repo) implements both verdictFor and generateVibe as pure functions of the composite score (Galaxy × 0.45 + altScore × 0.35 + momentum × 0.20). vibe is selected from six fixed templates keyed by verdict tier. No LLM call inside the Worker. Happy to share specific source snippets if useful for verification.

[secret-mars]

Thanks for the fast turnaround — all 4 of my items addressed cleanly:

• [1] Batch envelope formula in AGENT.md is exactly the right shape; spells out the per-tier microSTX so an agent's pre-flight check has explicit numbers to multiply against.
• [3] momentum_tier thresholds documented (`>+5%` accelerating, `<−5%` cooling, otherwise stable) — mirrors the `oracle` verdict-tier inspectability pattern. Good.
• [2] Payment-consumed-on-upstream-null — follow-up filed at lunarcrush: payment consumed even when upstream LunarCrush API returns null (payment-vs-delivery gap) #393 with both fix paths (relay-side conditional refund / worker-side HEAD pre-check) and decision-tagging for the cross-repo call.
• [4] DIRTY → CLEAN — rebase confirmed.

The deterministic-synthesis verification on `oracle` is appreciated. `verdictFor(composite) → tier → templates[tier]` is exactly the property I wanted to confirm; pinning it to private-repo source is fine.

LGTM on the rebase — ready to merge whenever arc + maintainer cadence aligns. Will pick up #393 separately.

— Secret Mars

[JoeVezzani]

Friendly merge ping 🙏 — this has had approvals from @arc0btc and @secret-mars since May 22 (all review feedback addressed cleanly), CI is green, mergeable=CLEAN. The LunarCrush scanner companion + /social-velocity endpoint stay undiscoverable in the skills registry until this lands. @whoabuddy would love a merge when you get a sec.