Add StockWaves skill — China & global market data + quant signals + tokenized-stock safety gate (x402)

README.md

@@ -57,6 +57,7 @@ Bankr Skills equip builders with plug-and-play tools to build more powerful agen
 | [qrcoin](https://qrcoin.fun) | [qrcoin](qrcoin/) | QR code auction game. Scan QR codes to place bids in on-chain auctions with unique token mechanics. |
 | [Quicknode](https://www.quicknode.com) | [quicknode](quicknode/) | Blockchain RPC and data access for all supported chains. Native/token balances, gas estimation, transaction status, and onchain queries for Base, Ethereum, Polygon, Solana, and Unichain. Supports API key and x402 pay-per-request access. |
 | [Quotient](https://quotient.social) | [quotient](quotient/) | Market intelligence API with x402 micropayment and API key auth. Access onchain/social analytics, OpenAPI discovery, and pricing data via `q-api.quotient.social`. |
+| [StockWaves](https://stockwaves.net) | [stockwaves](stockwaves/) | China & global market data + quant signals + a tokenized-stock pre-trade safety gate — all x402 pay-per-call (USDC on Base + Solana, no signup, no API key). Real-time Weibo/Baidu/Douyin hot-search pulse, structured CN news/events + sector-theme momentum; quant signals across A-share/HK/US equities, crypto, and cross-asset macro; and an "is this the REAL token vs a copycat?" gate (depeg / liquidity / market-hours / freeze-authority) across Backed/Ondo/Remora/Backpack on Solana + EVM. Free preview + walk-forward track-record. |
 | [SIGNA](https://www.signaagent.xyz) | [signa](signa/) | Give your Bankr agent a brain and a wallet-signed line to every other agent on any framework, keyless. Resolve any identity to a wallet, DM agents, invoke capabilities, and run a brain that reasons on decentralized inference and acts. No API key. |
 | [Axiom](https://clawbots.org) | [signals](signals/) | Transaction-verified trading signals on Base. Register as provider, publish trades with TX hash proof, consume signals from top performers. |
 | [Builder's Garden](https://builders.garden) | [siwa](siwa/) | Sign-In With Agent (SIWA) authentication for ERC-8004 registered agents. Sign messages using Bankr wallets, verify on the server, and protect API routes with ERC-8128. |

stockwaves/catalog.json

@@ -0,0 +1,24 @@
+{
+  "schemaVersion": 1,
+  "slug": "stockwaves",
+  "provider": "StockWaves",
+  "providerUrl": "https://stockwaves.net",
+  "logo": null,
+  "demo": {
+    "title": "stockwaves-x402.ts",
+    "language": "typescript",
+    "code": "import { x402Client, x402HTTPClient } from \"@x402/core/client\";\nimport { encodePaymentSignatureHeader } from \"@x402/core/http\";\nimport { registerExactEvmScheme } from \"@x402/evm/exact/client\";\nimport { privateKeyToAccount } from \"viem/accounts\";\n\nconst signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`);\nconst client = new x402Client();\nregisterExactEvmScheme(client, { signer });\nconst http = new x402HTTPClient(client);\n\n// Standard x402: 402 -> decode PAYMENT-REQUIRED -> sign -> retry with PAYMENT-SIGNATURE.\n// (Bankr agents can use Bankr wallet signing instead -- see setup.)\nasync function pay(url: string, init: RequestInit = {}) {\n  let res = await fetch(url, init);\n  if (res.status === 402) {\n    const challenge = JSON.parse(Buffer.from(res.headers.get(\"PAYMENT-REQUIRED\")!, \"base64\").toString());\n    const sig = encodePaymentSignatureHeader(await http.createPaymentPayload(challenge));\n    res = await fetch(url, { ...init, headers: { ...init.headers, \"PAYMENT-SIGNATURE\": sig } });\n  }\n  return res.json();\n}\n\nconst BASE_URL = \"https://stockwaves.net\";\nconst pulse = await pay(`${BASE_URL}/api/cn/trending?platform=all&limit=20`); // ~$0.03 USDC -- China hot-search pulse\nconst gate  = await pay(`${BASE_URL}/api/xstock/health?symbol=AAPLx`);        // ~$0.03 -- REAL token vs copycat\nconst free  = await (await fetch(`${BASE_URL}/api/xstock/health/preview?symbol=NVDAx`)).json(); // FREE preview"
+  },
+  "setup": [
+    "No signup and no API key — every paid endpoint speaks x402 directly.",
+    "Pay with any standard x402 client: the 402 challenge offers Base (eip155:8453) AND Solana — pick either, asset is USDC.",
+    "Prefer Bankr wallet signing (`/agent/sign`) when available — set `BANKR_API_KEY` (Agent API + signing enabled).",
+    "Otherwise set `EVM_PRIVATE_KEY` (a USDC-funded Base wallet) and install `@x402/core` + `@x402/evm` + `viem`.",
+    "Discover everything zero-config: GET https://stockwaves.net/.well-known/x402 , /openapi.json , /llms.txt"
+  ],
+  "install": {
+    "type": "bankr",
+    "repoPath": "stockwaves",
+    "command": "install the stockwaves skill from https://github.com/BankrBot/skills/tree/main/stockwaves"
+  }
+}

stockwaves/references/api-reference.md

@@ -0,0 +1,40 @@
+# StockWaves API Reference
+
+Base URL `https://stockwaves.net`. All endpoints return English fields alongside originals; stocks are identified by language-neutral `symbol` (ticker). Prices are USDC per call. Canonical machine spec: `/openapi.json`.
+
+## China-market intelligence
+| Endpoint | Price | Query | Returns |
+|---|---|---|---|
+| `GET /api/cn/trending` | $0.03 | `platform=all\|weibo\|baidu\|douyin`, `limit=1-50`, `category=` | per-platform hot-search rows: `rank`, `term`, `category`, `heat` (native scale, NOT cross-platform comparable), `marker`/`is_rising` (Weibo). |
+| `GET /api/cn/news` | $0.04 | `limit=1-50`, `ticker=` | events `{ticker, event, event_en, sentiment, count, sources}`; risks `{detected_at, ticker, severity, kind, keywords}`. Derived structure only — no article text. |
+| `GET /api/cn/themes` | $0.06 | — | per industrial theme (AI compute/semis/robotics/defense/new energy): agg rotation-strength; per board: rot_score, rank, trend, lifecycle. |
+| `GET /api/cn/brief` | $0.08 | `top=1-10` | one-call synthesized China daily: social_pulse + market_events + risk_alerts + industrial_themes + sector_rotation_top. |
+
+## Quant signals
+| Endpoint | Price | Query | Returns |
+|---|---|---|---|
+| `GET /api/recommend` | $0.50 | `market=A\|US`, `limit=1-100` | Top-N picks (4-factor resonance) + take-profit / stop-loss. |
+| `GET /api/dealer` | $0.08 | `top_n=1-1000`, `limit=1-500` | dealer (smart-money) 6-signal scan across A-shares. |
+| `GET /api/rotation` | $0.05 | `limit=1-100` | sector rotation forecast: strength + momentum + catalyst. |
+| `GET /api/anomalies/insight` | $0.05 | `days=1-90` | blind-spot / anomaly setups the system keeps missing. |
+| `GET /api/btc/signal` | $0.03 | — | BTC/USDT RL signal: position lean [-1,1], direction, conviction, risk flags. |
+| `GET /api/macro/allocation` | $0.10 | `symbols=` (CSV) | cross-asset ETF allocation (QQQ/IWM/SPY/TLT/DBC/GLD): signal, position, confidence, regime. |
+| `GET /api/crypto/microstructure` | $0.01 | `symbol=BTCUSDT` ({BTC,ETH,SOL,BNB,XRP,DOGE}USDT) | live perp microstructure: funding, premium/basis, OI (+USD), taker buy/sell ratio, 24h realized vol. |
+
+## Compute
+| Endpoint | Price | Body | Returns |
+|---|---|---|---|
+| `POST /api/portfolio/optimize` | $0.05 | `{assets:[{symbol,target,confidence?,vol?,regime?}], config?}` | risk-constrained weights (inverse-vol, conviction scaling, correlation penalty, gross/net + per-symbol caps, regime haircut). |
+
+## Tokenized US stocks — pre-trade safety gate
+| Endpoint | Price | Query | Returns |
+|---|---|---|---|
+| `GET /api/xstock/health` | $0.03 | `symbol=AAPLx\|AAPLon\|TSLAr\|SPCX` OR `address=<solana mint \| 0x evm>` | `decision` (ok/review/avoid) + signals: `authenticity` (verified vs issuer registry — Backed/Ondo/Remora/Backpack; off-allowlist = COPYCAT), `depeg_bps` (DEX vs Pyth equity oracle), `market_status`, `liquidity_usd`, `trading_halted`, `freeze_authority`, `onchain_supply`. Multi-chain (Solana + EVM incl. BNB). |
+
+## Free (no payment)
+| Endpoint | Query | Returns |
+|---|---|---|
+| `GET /api/track-record` | — | walk-forward backtest (Sharpe, return, max drawdown, WF score). Proof before you buy. |
+| `GET /api/xstock/health/preview` | `symbol=` or `address=` | rate-limited: the safety `decision` + `authenticity` only (full numeric signals stay behind the paid gate). |
+
+Informational data, NOT investment advice. Terms: `https://stockwaves.net/terms`.

stockwaves/references/error-handling.md

@@ -0,0 +1,16 @@
+# Error Handling
+
+| Status | Meaning | Action |
+|---|---|---|
+| `402` | Payment required (first leg of every paid call). | Read `PAYMENT-REQUIRED`, sign, retry with `PAYMENT-SIGNATURE`. Not an error. |
+| `200` | Success. | Read the body and the `PAYMENT-RESPONSE` settle receipt. |
+| `400` | Bad params / body. | Fix the request. You were NOT charged (settlement only on status < 400) — do not retry blindly. |
+| `402` after paying | Stale/duplicate payment, or a re-challenge. | Fetch a FRESH challenge and rebuild the payment payload (one nonce settles once). |
+| `429` | Rate limited (mainly the FREE preview tiers, per-IP daily quota). | Back off; switch to the paid endpoint, or retry later. Paid calls are not quota-limited. |
+| `5xx` | Transient upstream/server error. | Bounded retry with exponential backoff (e.g. 3 tries). You were NOT charged. |
+
+## Rules
+- Settlement is server-response-based: it occurs only when the handler returns status < 400, so a `4xx` never costs USDC.
+- Do not mutate path/query/body between the challenge and the paid retry — it invalidates the signature.
+- Treat the runtime `402` challenge (price/network/payTo) as authoritative over any cached pricing.
+- Never log or echo the raw `PAYMENT-SIGNATURE` or the signer key.

stockwaves/references/x402-flow.md

@@ -0,0 +1,45 @@
+# x402 Payment Flow
+
+Two ways to pay, in order of preference.
+
+## 1. Bankr wallet signing (preferred)
+If running inside Bankr, let Bankr sign: call `/agent/sign` with a Bankr API key (`X-API-Key`, Agent API + signing enabled, not read-only). Bankr handles the 402 challenge/settle for you — you just issue the request.
+
+## 2. Vanilla x402 (any agent)
+For non-Bankr agents, do the standard challenge → sign → retry. This is the recipe verified end-to-end against these endpoints (the load-bearing detail is the `PAYMENT-SIGNATURE` request header — not `X-PAYMENT`).
+
+### Protocol
+1. Send the request (GET, or POST with a JSON body) without payment headers.
+2. If status is `402`, base64-decode the `PAYMENT-REQUIRED` response header → the challenge JSON (`accepts` offers Base `eip155:8453` AND Solana; asset USDC; scheme `exact`).
+3. Build a payment payload from the challenge and encode it as the `PAYMENT-SIGNATURE` header.
+4. Retry the SAME request (do not mutate path/query/body) with that header.
+5. On success, read the data and the `PAYMENT-RESPONSE` settle receipt.
+
+### Reference implementation (TypeScript)
+```ts
+import { x402Client, x402HTTPClient } from "@x402/core/client";
+import { encodePaymentSignatureHeader } from "@x402/core/http";
+import { registerExactEvmScheme } from "@x402/evm/exact/client";
+import { privateKeyToAccount } from "viem/accounts";
+
+const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`);
+const client = new x402Client();
+registerExactEvmScheme(client, { signer });
+const http = new x402HTTPClient(client);
+
+export async function pay(url: string, init: RequestInit = {}) {
+  let res = await fetch(url, init);
+  if (res.status === 402) {
+    const challenge = JSON.parse(Buffer.from(res.headers.get("PAYMENT-REQUIRED")!, "base64").toString());
+    const sig = encodePaymentSignatureHeader(await http.createPaymentPayload(challenge));
+    res = await fetch(url, { ...init, headers: { ...init.headers, "PAYMENT-SIGNATURE": sig } });
+  }
+  return res.json();
+}
+```
+
+### Reliability rules
+- Do NOT change path/query/body between the challenge and the paid retry.
+- One nonce settles once: a duplicate/replayed `PAYMENT-SIGNATURE` is rejected (the facilitator dedups in-flight). Build a fresh payment per logical call.
+- Settlement happens only when the handler returns status < 400 — a `4xx` (bad params) means you were NOT charged.
+- Pay on EITHER rail; pick Solana if your wallet is SPL-funded, Base if EVM-funded.

stockwaves/skill.md

@@ -0,0 +1,77 @@
+---
+name: stockwaves-api
+description: Pay-per-call China & global market data, quant signals, and a tokenized-stock pre-trade safety gate over x402. Use when an agent needs Chinese-market intelligence (Weibo/Baidu/Douyin pulse, structured CN news/events, sector momentum), cross-asset quant signals (A-share/HK/US equities, crypto, macro), or a pre-buy safety check on an on-chain tokenized US stock (real token vs copycat, depeg, liquidity, market-hours).
+---
+
+# StockWaves API Skill
+
+Use this skill when an agent needs market data Western APIs can't reach (real-time Chinese internet pulse + structured CN market intelligence), quant trading signals across China/HK/US equities, crypto and cross-asset macro, OR a pre-trade safety verdict on a tokenized US stock before buying it on-chain.
+
+Every endpoint is **x402 pay-per-call** — no signup, no API key. The skill's job is to execute the x402 flow correctly and pick the right endpoint.
+
+## Base URL
+
+- `STOCKWAVES_BASE_URL`: `https://stockwaves.net`
+- Single origin for runtime requests AND discovery docs (`/.well-known/x402`, `/openapi.json`, `/llms.txt`).
+
+## Access Model
+
+- **x402 only** — there is no API-key path. Unpaid requests return HTTP `402`.
+- The 402 challenge offers **two rails — Base (`eip155:8453`) and Solana (`solana:…`)**. Pay on either; asset is USDC; scheme is standard x402 `exact` (EIP-3009 on Base / signed tx on Solana), settled via the Coinbase/CDP facilitator.
+- Prefer **Bankr wallet signing** (`/agent/sign`) when available — set a Bankr API key via `X-API-Key` with Agent API access + signing permissions (not read-only).
+- Otherwise use any vanilla x402 client (SIWE/SIWX) with a USDC-funded wallet.
+
+## x402 API Call Checklist
+
+1. Send the request to the StockWaves endpoint without payment headers.
+2. If the response is `402`, parse the base64 `PAYMENT-REQUIRED` header (it carries scheme, both networks, USDC asset, amount, payTo).
+3. Sign the payment and retry with the `PAYMENT-SIGNATURE` header.
+4. On success, read the data and the `PAYMENT-RESPONSE` settle receipt.
+5. Apply retry/backoff for `402` re-challenges and transient `5xx`; a `4xx` from the handler means you were NOT charged (settlement only occurs on status < 400).
+
+## Required Preflight (Deterministic)
+
+Before the first call in a session, fetch the discovery docs (all free, no payment):
+
+- `GET /.well-known/x402` — the list of paid resources.
+- `GET /openapi.json` — canonical route + query-param metadata (treat as authoritative for invocation).
+- `GET /llms.txt` — human/agent-readable catalog with prices and how-to-pay.
+- Treat the runtime `402` challenge as authoritative for price/network/payTo.
+
+## Core Endpoints (price = USDC per call)
+
+China-market intelligence (data Western agents can't reach):
+- `GET /api/cn/trending` — $0.03 — live Weibo + Baidu + Douyin hot-search, structured (per-platform rank, heat, category). Query: `?platform=all|weibo|baidu|douyin&limit=1-50&category=`
+- `GET /api/cn/news` — $0.04 — structured CN market news & risk feed: per-event-type sentiment, mention counts, ticker mapping, risk keywords + severity (English labels; derived structure, no article text). Query: `?limit=1-50&ticker=`
+- `GET /api/cn/themes` — $0.06 — China industrial-theme momentum (AI compute / semis / robotics / defense / new energy): per-theme rotation-strength + per-board rank/trend/lifecycle.
+- `GET /api/cn/brief` — $0.08 — ONE-call synthesized China daily brief: social pulse + market events + risk alerts + hot themes + top sector rotation. Query: `?top=5`
+
+Quant signals (A-share / HK / US equities, crypto, macro):
+- `GET /api/recommend` — $0.50 — Top-N stock picks (4-factor resonance) with take-profit / stop-loss. Query: `?market=A|US&limit=1-100`
+- `GET /api/dealer` — $0.08 — dealer (smart-money) 6-signal scan across A-shares. Query: `?top_n=1-1000&limit=1-500`
+- `GET /api/rotation` — $0.05 — sector rotation forecast (strength + momentum + catalyst). Query: `?limit=1-100`
+- `GET /api/anomalies/insight` — $0.05 — blind-spot / anomaly insight: setups the system keeps missing. Query: `?days=1-90`
+- `GET /api/btc/signal` — $0.03 — real-time BTC/USDT directional signal (RL model): position lean [-1,1], direction, conviction, risk flags.
+- `GET /api/macro/allocation` — $0.10 — cross-asset ETF tactical allocation (QQQ/IWM/SPY/TLT/DBC/GLD): per-ETF signal, position, confidence, regime.
+- `GET /api/crypto/microstructure` — $0.01 — live crypto perp microstructure (Binance public): funding, premium/basis, OI (+USD), taker buy/sell ratio, 24h realized vol. Query: `?symbol=BTCUSDT`
+
+Compute (bring your own signals):
+- `POST /api/portfolio/optimize` — $0.05 — stateless portfolio optimizer. POST `{assets:[{symbol,target,confidence?,vol?,regime?}], config?}` → risk-constrained weights (inverse-vol, conviction scaling, correlation penalty, gross/net + per-symbol caps, regime haircut).
+
+Tokenized US stocks — pre-trade safety gate (any issuer, multi-chain):
+- `GET /api/xstock/health` — $0.03 — before an agent BUYS an on-chain US stock, check it's the REAL token and safe right now. Multi-issuer (Backed/xStocks, Ondo, Remora/rStocks, Backpack Securities), multi-chain (Solana + EVM incl. BNB). `?symbol=AAPLx|AAPLon|TSLAr|SPCX` OR `?address=<solana mint | 0x evm>` → `decision` (ok/review/avoid) + signals: **authenticity** (verified vs the issuer's own registry — a token claiming a ticker but not on the allowlist is flagged a COPYCAT), **depeg_bps** (DEX price vs Pyth equity oracle), **market_status**, **liquidity_usd**, **trading_halted**, **freeze_authority**, supply. Diligence support — NOT investment/legal advice.
+
+Free (no payment):
+- `GET /api/track-record` — FREE — walk-forward backtest performance (Sharpe, return, max drawdown) of the systematic strategy behind the paid signals. Proof before you buy.
+- `GET /api/xstock/health/preview` — FREE (rate-limited) — the safety verdict + authenticity for one token at zero cost (the full numeric signals stay behind the paid `/api/xstock/health`). `?symbol=` or `?address=`.
+
+## Notes
+
+- All endpoints return English fields (`event_en`, `board_en`, `signals_en`, …) alongside the originals; stocks are identified by language-neutral `symbol` (ticker).
+- Derived structured output only — no third-party article text (copyright-safe).
+- Informational data, NOT investment advice. Terms: `https://stockwaves.net/terms`.
+
+## References
+- API reference (all endpoints, params, response fields): `/skill/references/api-reference.md`
+- x402 payment flow (Bankr signing + verified vanilla recipe): `/skill/references/x402-flow.md`
+- Error handling (402 / 429 / 4xx / 5xx, retry rules): `/skill/references/error-handling.md`