feat: add delu-oracle skill (deluonchain)

deluonchain/delu-oracle/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: delu-oracle
+version: 16
+description: Full-cognition token analysis for Base EVM tokens via the deluagent oracle. Pass a CA or cashtag, get back a flat decision header (action, conviction, entry/stop/size, read) plus full cognition report. Tiered x402 pricing — 100M+ DELU free, 50M+ 50k DELU, public 250k DELU. Sequential calls only.
+tags: [trading, defi, base, oracle, analysis]
+visibility: public
+metadata:
+  clawdbot:
+    emoji: "🔮"
+    homepage: "https://github.com/deluonchain/deluskill"
+---
+
+# delu-oracle
+
+Intelligence layer for any Base trading agent. Pass one Base EVM contract address (or cashtag like `$BNKR`) and get back a flat `decision` header an agent can act on in a single hop — `action`, `conviction`, entry/stop/size, and a one-line delu-voiced `read` — with the full cognition report underneath for the why.
+
+Scout, auditor, and quant run server-side on every call. The full `observed` block is always present. Social signal (checkr) is opt-in via `?social=true`.
+
+## Endpoint
+
+```
+GET https://x402.bankr.bot/0xed2ceca9de162c4f2337d7c1ab44ee9c427709da/delu-oracle/analyze/{ca}
+```
+
+Base is the only supported chain — no chain parameter needed.
+
+## Parameters
+
+| Parameter | Location | Required | Notes |
+|---|---|---|---|
+| `ca` | path | yes | 0x-prefixed EVM address **or** cashtag / symbol (e.g. `$BNKR`, `BNKR`). Ambiguous symbols return a 400 asking for the CA directly. |
+| `social` | query | no | `?social=true` enables checkr social enrichment (+$0.45 USDC, billed to caller) |
+| `verbose` | query | no | Accepted but no-op — `observed` and `summary` are always present. |
+
+## ⚠️ Sequential calls required
+
+**Do not call this endpoint in parallel.** The x402 `upto` scheme uses a single-use Permit2 signature per authorization. Parallel calls with the same payer wallet result in `402 Payment could not be verified` on all but the first.
+
+**Always call sequentially — one CA at a time, await the full response, then call the next.**
+
+```js
+// ✅ correct
+for (const ca of watchlist) {
+  const result = await oracle.analyze(ca);
+  process(result);
+}
+
+// ❌ wrong
+const results = await Promise.all(watchlist.map(ca => oracle.analyze(ca)));
+```
+
+## The decision header — read this first
+
+Flat, no traversal needed:
+
+```json
+"decision": {
+  "action": "ENTER",       // ENTER | WATCH | AVOID
+  "conviction": 71,        // 0-100
+  "direction": "long",
+  "entry_low": 0.00051,
+  "entry_high": 0.00053,
+  "stop": 0.00048,
+  "size_pct": 3.1,
+  "read": "one line, delu voice"
+}
+```
+
+Simple gate: `decision.action === "ENTER" && decision.conviction >= 70 && confidence >= 0.6`
+
+`action` maps from `verdict`: strong_buy/buy → `ENTER`, hold → `WATCH`, avoid/drop → `AVOID`.
+
+## WATCH mandate — null position fields
+
+When `verdict` is `hold`, all position-specific fields are `null` in both `decision` and `mandate` — `entry_low`, `entry_high`, `stop`, `size_pct`, `entry_zone`, `stop_loss`, `stop_basis`, `size_hint_pct`, `size_basis`. Only `horizon` and `invalidations` are populated.
+
+## Payment tier
+
+The endpoint uses the `upto` scheme — agents sign for the 250k DELU ceiling, but the handler settles based on the caller's DELU balance on Base.
+
+| Tier | Balance | Settled |
+|---|---|---|
+| `whale` | 100M+ DELU | 0 DELU (free) |
+| `holder` | 50M+ DELU | 50,000 DELU |
+| `public` | < 50M DELU | 250,000 DELU |
+
+**Payment token:** DELU — `0x7b0ee9dcb5c1d4d7cd630c652959951936512ba3` on Base (18 decimals).
+
+Check `payment_tier.settled_delu` in the response body for what was actually charged — not the x402 authorization ceiling.
+
+## Response schema summary
+
+- `decision` — flat header: `action`, `conviction`, `direction`, `entry_low`, `entry_high`, `stop`, `size_pct`, `read`
+- `ca`, `chain`, `oracle_version`
+- `verdict` — `strong_buy` | `buy` | `hold` | `avoid` | `drop`
+- `score` — 0–100 fused cognition score
+- `confidence` — 0–1 data quality and signal agreement
+- `drivers` / `risks` — up to 3 each
+- `signals` — momentum, flow, structure, volatility, liquidity
+- `context` — regime_label, regime_confidence, base_eco_pulse, macro_pulse
+- `mandate` — action, entry_zone, stop_loss, stop_basis, size_hint_pct, size_basis, horizon, invalidations
+- `payment_tier` — tier, delu_balance, settled_delu, note
+- `observed` — always present: market, regime, social, deluagent (scout/auditor/quant mirror with `weights_used`)
+- `summary`, `selected_timeframe`, `candle_count`, `pool_source`, `timestamp`
+
+See [`references/response-schema.md`](./references/response-schema.md) for the full field-by-field schema.
+See [`references/mandate-fields.md`](./references/mandate-fields.md) for mandate construction details.
+See [`references/example-response.md`](./references/example-response.md) for a full annotated response example.
+See [`references/social-enrichment.md`](./references/social-enrichment.md) for the opt-in two-step social flow.
+See [`references/external-clients.md`](./references/external-clients.md) for standalone client recipes.
+
+## Error codes
+
+| Status | Meaning |
+|---|---|
+| `400` | Bad `ca`, symbol not found on Base, ambiguous symbol, or no supported Base pair |
+| `402` | Payment required or failed. `402 Payment could not be verified` on retry = parallel calls — switch to sequential |
+| `404` | Unknown token or no reportable data |
+| `5xx` | Oracle or upstream failure — retry later |

deluonchain/delu-oracle/references/example-response.md

@@ -0,0 +1,132 @@
+# Example Response
+
+Full default response (no `?social=true`) for `$BNKR` in a MIXED regime.
+
+```json
+{
+  "decision": {
+    "action": "WATCH",
+    "conviction": 25,
+    "direction": "long",
+    "entry_low": null,
+    "entry_high": null,
+    "stop": null,
+    "size_pct": null,
+    "read": "bnkr scores 46, hold, in a mixed regime at low conviction. price action is mixed, up on the hour but down on the day, a short term bounce against a broader downtrend. structure sits in markdown with a bearish bias, volatility is normal at 2.32% atr. no clean entry yet, wait for structure to resolve."
+  },
+  "ca": "0x22af33fe49fd1fa80c7149773dde5890d3c76f3b",
+  "chain": "base",
+  "score": 46,
+  "verdict": "hold",
+  "confidence": 0.55,
+  "drivers": [
+    "premium liquidity ($2.33M) — deep execution headroom",
+    "high turnover (vol24h $163k against liquidity)"
+  ],
+  "risks": [
+    "structure in markdown, downside continuation risk",
+    "hourly and daily momentum diverge"
+  ],
+  "signals": {
+    "momentum":   { "h1_aligned_with_h24": false, "direction": "bullish", "strength": "weak" },
+    "flow":       { "buyer_pressure": "balanced", "net_flow_h1_pct": -33.4, "txn_intensity": "high", "data_quality": "full" },
+    "structure":  { "state": "markdown", "bias": "bearish" },
+    "volatility": { "regime": "normal", "atr_pct_1h": 2.32, "atr_pct_band": "p25-p50" },
+    "liquidity":  { "depth_tier": "premium", "liquidity_to_volume_ratio": 14.31 }
+  },
+  "context": {
+    "regime_label": "MIXED",
+    "regime_confidence": 0.11,
+    "base_eco_pulse": "flat",
+    "macro_pulse": "neutral"
+  },
+  "mandate": {
+    "action": "WATCH",
+    "entry_zone": null,
+    "stop_loss": null,
+    "stop_basis": null,
+    "size_hint_pct": null,
+    "size_basis": null,
+    "horizon": "30m-2h",
+    "invalidations": [
+      "regime flip away from MIXED",
+      "structure confirms markdown continuation"
+    ]
+  },
+  "payment_tier": {
+    "tier": "holder",
+    "delu_balance": 50000000,
+    "settled_delu": 50000,
+    "note": "50M+ DELU holder rate applied"
+  },
+  "observed": {
+    "market": {
+      "symbol": "BNKR",
+      "price_usd": 0.000412,
+      "liquidity_usd": 2330000,
+      "volume_h24": 163000,
+      "volume_h6": 41200,
+      "volume_h1": 8900,
+      "price_change_h1": 1.2,
+      "price_change_h6": -0.8,
+      "price_change_h24": -3.1,
+      "atr_pct_1h": 2.32,
+      "pool_age_days": 13,
+      "dex_id": "uniswap_v3",
+      "raw_ohlcv_used": true
+    },
+    "regime": {
+      "label": "MIXED",
+      "confidence": 0.11
+    },
+    "social": { "status": "unavailable" },
+    "deluagent": {
+      "scout": {
+        "symbol": "BNKR",
+        "address": "0x22af33fe49fd1fa80c7149773dde5890d3c76f3b",
+        "priceUsd": 0.000412,
+        "liquidity": 2330000,
+        "volume24h": 163000,
+        "viabilityScore": 62,
+        "smartMoney": false,
+        "capitalInflowRatio": 0.04,
+        "buyPressure": 0.44,
+        "bucket": "tier2",
+        "poolAgeDays": 13,
+        "source": "internal"
+      },
+      "auditor": {
+        "verdict": "PASS",
+        "safetyScore": 78,
+        "hardFail": false,
+        "hardFails": [],
+        "source": "internal"
+      },
+      "quant": {
+        "quantScore": 46,
+        "regime": "MIXED",
+        "structure_phase": "markdown",
+        "atr_pct_1h": 2.32,
+        "volatility_regime": "normal",
+        "weights_used": { "momentum": 0.35, "volume": 0.30, "inflow": 0.35, "structure": 0.25 },
+        "source": "internal"
+      }
+    }
+  },
+  "summary": "bnkr scores 46 in a mixed regime. momentum is weak bullish on the hour but bearish on the day — divergence. structure is markdown with bearish bias. liquidity is premium at $2.33M. no clean entry.",
+  "selected_timeframe": "1h",
+  "pool_source": "primary",
+  "candle_count": 168,
+  "timestamp": "2026-06-09T00:00:00.000Z",
+  "oracle_version": "v29-tiered-flywheel"
+}
+```
+
+## Key things to note
+
+- `decision.action` is `WATCH` → all position fields are `null` (no trade to execute)
+- `payment_tier.settled_delu: 50000` — holder rate applied, not the 250k ceiling
+- `observed.social.status: "unavailable"` — social not requested (`?social=true` not passed)
+- `observed.deluagent.quant.weights_used` — live regime-adaptive weights, loaded from learning store per request
+- `selected_timeframe: "1h"` and `candle_count: 168` — data provenance for the quant read
+- `pool_source: "primary"` — canonical pool resolved without fallback

deluonchain/delu-oracle/references/external-clients.md

@@ -0,0 +1,110 @@
+# External client recipes
+
+> For developers writing a client outside an agent runtime (standalone scripts, custom servers). Agents inside Bankr, Claude, OpenAI, LangChain, or any runtime with built-in x402 support do NOT need any of this — their runtime handles payment.
+
+These examples are optional recipes for standalone callers. The API spec lives in [`../SKILL.md`](../SKILL.md).
+
+Endpoint used below:
+
+`GET https://x402.bankr.bot/0xed2ceca9de162c4f2337d7c1ab44ee9c427709da/delu-oracle/analyze/{ca}`
+
+Base is the only supported chain — no chain parameter needed. The endpoint uses x402 with the `upto` scheme (DELU token). The response leads with a flat `decision` block — read that first; the full cognition report sits underneath.
+
+## TypeScript: viem + x402-fetch
+
+Use this only in a standalone process where you are responsible for wallet custody.
+
+```bash
+npm install x402-fetch viem
+```
+
+```ts
+import { wrapFetchWithPayment } from "x402-fetch";
+import { privateKeyToAccount } from "viem/accounts";
+
+const privateKey = process.env.PRIVATE_KEY;
+if (!privateKey) throw new Error("PRIVATE_KEY is required for this standalone example");
+
+const account = privateKeyToAccount(privateKey as `0x${string}`);
+const fetchWithPayment = wrapFetchWithPayment(fetch, account);
+
+const ca = "0x22af33fe49fd1fa80c7149773dde5890d3c76f3b";
+const url = `https://x402.bankr.bot/0xed2ceca9de162c4f2337d7c1ab44ee9c427709da/delu-oracle/analyze/${ca}`;
+
+const response = await fetchWithPayment(url);
+if (!response.ok) {
+  throw new Error(`Request failed: ${response.status} ${await response.text()}`);
+}
+
+const report = await response.json();
+
+// read the decision header first — one hop to the call
+const d = report.decision;
+console.log(d.action, d.conviction, d.read);
+
+// simple agent gate
+if (d.action === "ENTER" && d.conviction >= 70 && report.confidence >= 0.6) {
+  console.log("entry", d.entry_low, d.entry_high, "stop", d.stop, "size%", d.size_pct);
+}
+```
+
+## Python: x402 SDK
+
+Use this only in a standalone process where you are responsible for wallet custody.
+
+```bash
+pip install x402
+```
+
+```python
+import os
+from x402.client import x402_client
+
+private_key = os.environ.get("PRIVATE_KEY")
+if not private_key:
+    raise RuntimeError("PRIVATE_KEY is required for this standalone example")
+
+client = x402_client(wallet=private_key)
+
+ca = "0x22af33fe49fd1fa80c7149773dde5890d3c76f3b"
+url = f"https://x402.bankr.bot/0xed2ceca9de162c4f2337d7c1ab44ee9c427709da/delu-oracle/analyze/{ca}"
+
+response = client.get(url)
+response.raise_for_status()
+report = response.json()
+
+d = report["decision"]
+print(d["action"], d["conviction"], d["read"])
+
+if d["action"] == "ENTER" and d["conviction"] >= 70 and report["confidence"] >= 0.6:
+    print("entry", d["entry_low"], d["entry_high"], "stop", d["stop"], "size%", d["size_pct"])
+```
+
+## Raw HTTP: manual x402 payment flow
+
+Use this only when implementing your own x402 client.
+
+1. Send the request without `X-PAYMENT`.
+2. Read the `402 Payment Required` response body.
+3. Select the accepted requirement for Base DELU.
+4. Build a Permit2 authorization for the required amount.
+5. Sign with the paying wallet.
+6. Encode the x402 payment payload.
+7. Retry the original request with `X-PAYMENT: <encoded-payment-payload>`.
+8. Read the JSON response (start with `decision`) and the `X-PAYMENT-RESPONSE` settlement receipt.
+
+```bash
+# 1. Discover payment requirements
+curl -i \
+  "https://x402.bankr.bot/0xed2ceca9de162c4f2337d7c1ab44ee9c427709da/delu-oracle/analyze/0x22af33fe49fd1fa80c7149773dde5890d3c76f3b"
+
+# 2. Sign and encode the x402 payload (your client)
+PAYMENT="<encoded-x402-payment-payload>"
+
+# 3. Retry with payment
+curl -i \
+  -H "X-PAYMENT: ${PAYMENT}" \
+  "https://x402.bankr.bot/0xed2ceca9de162c4f2337d7c1ab44ee9c427709da/delu-oracle/analyze/0x22af33fe49fd1fa80c7149773dde5890d3c76f3b"
+```
+
+Pass `?social=true` for checkr social enrichment. See `social-enrichment.md` for the two-step flow.