@oracle-agent/oracle 0.24.1 → 0.24.2

package/dist/assets/skills/polymarket/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: polymarket
+description: "Query Polymarket: markets, prices, orderbooks, history."
+version: 1.1.0
+author: Hermes Agent + Teknium
+tags: [polymarket, prediction-markets, market-data, trading]
+platforms: [linux, macos, windows]
+---
+
+> Oracle native tools: `oracle_cli` (read/prepare), `vault_status`, `signer_status`, `signer_execute` (needs human confirmationNonce), `skill_load`. No generic shell. No fleet SSH.
+
+
+# Polymarket — Prediction Market Data
+
+Query prediction market data from Polymarket using their public REST APIs.
+All endpoints are read-only and require zero authentication.
+
+See `references/api-endpoints.md` for the full endpoint reference with curl examples.
+See `scripts/polymarket.py` for the CLI helper.
+See `scripts/polymarket_digest.py` for the automated digest script.
+See `references/2026-competitive-landscape.md` for who's making money in 2026 and which strategies work.
+See `references/odds-api-io-provider.md` for the bot's sports-odds source (odds-api.io v3) — auth, the host-mismatch 401 trap, the 5-book plan cap, and the working call sequence to pull a match's live moneyline.
+See `references/odds-api-io-football.md` for World Cup / football-specific usage: correct sport slug (`football` not `soccer_fifa_world_cup`), required `bookmakers` param, pre-configured 5-book list, event ID discovery, and response shape.
+
+## When to Use
+
+- User asks about prediction markets, betting odds, or event probabilities
+- User wants to know "what are the odds of X happening?"
+- User asks about Polymarket specifically
+- User wants market prices, orderbook data, or price history
+- User asks to monitor or track prediction market movements
+- Scheduled cron job to produce a market digest
+
+## Key Concepts
+
+- **Events** contain one or more **Markets** (1:many relationship)
+- **Markets** are binary outcomes with Yes/No prices between 0.00 and 1.00
+- Prices ARE probabilities: price 0.65 means the market thinks 65% likely
+- `outcomePrices` field: JSON-encoded array like `["0.80", "0.20"]`
+- `clobTokenIds` field: JSON-encoded array of two token IDs [Yes, No] for price/book queries
+- `conditionId` field: hex string used for price history queries
+- Volume is in USDC (US dollars)
+
+## Three Public APIs
+
+1. **Gamma API** at `gamma-api.polymarket.com` — Discovery, search, browsing
+2. **CLOB API** at `clob.polymarket.com` — Real-time prices, orderbooks, history
+3. **Data API** at `data-api.polymarket.com` — Trades, open interest
+
+## Typical Workflow
+
+When a user asks about prediction market odds:
+
+1. **Search** using the Gamma API public-search endpoint with their query
+2. **Parse** the response — extract events and their nested markets
+3. **Present** market question, current prices as percentages, and volume
+4. **Deep dive** if asked — use clobTokenIds for orderbook, conditionId for history
+
+## Presenting Results
+
+Format prices as percentages for readability:
+- outcomePrices `["0.652", "0.348"]` becomes "Yes: 65.2%, No: 34.8%"
+- Always show the market question and probability
+- Include volume when available
+
+Example: `"Will X happen?" — 65.2% Yes ($1.2M volume)`
+
+## Parsing Double-Encoded Fields
+
+The Gamma API returns `outcomePrices`, `outcomes`, and `clobTokenIds` as JSON strings
+inside JSON responses (double-encoded). When processing with Python, parse them with
+`json.loads(market['outcomePrices'])` to get the actual array.
+
+## Pitfalls
+
+### Data API attributes trades to proxy wallet, not signing EOA
+
+When querying `data-api.polymarket.com` endpoints (`/trades`, `/positions`, `/activity`) for a specific wallet, **query the PROXY wallet, not the signing EOA.** Polymarket assigns a proxy contract address for each user — trades, positions, and activity are attributed to the proxy, not the EOA that signed the transactions.
+
+- The EOA `0x4d47b675` (DEMI's wallet) returns **zero results** from the Data API — query the proxy address instead.
+- The proxy wallet for this setup: `0x635be4D2eE8EE926C1EF44D982a2D031ba0d1013`.
+- Trade record keys from `/trades`: `proxyWallet, side, asset, conditionId, size, price, timestamp, title, slug, eventSlug, outcome, outcomeIndex, transactionHash`. `timestamp` is unix seconds. `price` 0-1. `size` = shares.
+- The stale bot analysis file at `data/all_trades_analysis.json` is **generatedAt 2026-04-28, wrong-proxy, contaminated** — always pull live from the Data API.
+- Pre-2026-05-14 trade data has ~30% zero-edge contamination — filter by timestamp when computing PnL/win-rate.
+- Wins auto-redeem: resolved-wins show as redemption inflows in `/activity`, not sell-side fills in `/trades`. Full PnL needs merging both endpoints.
+
+### Security scanner blocks curl-to-python pipelines
+The Hermes security scanner flags `curl ... | python3` as HIGH risk (piped input to interpreter). Save to a temp file first, then parse:
+```
+curl -s 'https://gamma-api.polymarket.com/...' > /tmp/pm_data.json
+python3 -c "import json; data = json.load(open('/tmp/pm_data.json'))"
+```
+Or use `execute_code()` with `hermes_tools.terminal()` and separate calls.
+
+### Public search returns stale historical markets
+`public-search?q=NBA` surfaces game-level markets from previous seasons (2024 dates) alongside active championship markets. These are `active=true` but often `closed=true` or have prices at 100%/0%. To find active championship contenders:
+- Query event-specific slug: `events?slug=2026-nba-champion`
+- Filter: `market['active'] == True and not market['closed']`
+- Teams eliminated but not yet resolved have `active=true` + `closed=true` + `outcomePrices=["0.0000","1.0000"]`
+
+### Volume field type inconsistency
+The `volume` field can be a string or number depending on context. When available, prefer `volumeNum` (always float) over `volume` (may be string). Always cast with `float(val)` when computing.
+
+### CLOB `/book` endpoint returns UNSORTED arrays
+
+`clob.polymarket.com/book?token_id=<id>` returns `asks` and `bids` as **unsorted arrays**. `asks[0]` is often `0.999` (not the best ask), `bids[0]` can be near-zero. This looks like "always sort ascending" but it's actually random order.
+
+**Always use reduce to find BBO:**
+```js
+const bestAsk = book.asks.reduce((lo, o) => {
+  const p = parseFloat(o.price);
+  return (Number.isFinite(p) && p > 0 && p < 1 && (lo === 0 || p < lo)) ? p : lo;
+}, 0);
+const bestBid = book.bids.reduce((hi, o) => {
+  const p = parseFloat(o.price);
+  return (Number.isFinite(p) && p > 0 && p < 1 && p > hi) ? p : hi;
+}, 0);
+```
+Using `asks[0].price` as "best ask" is a **silent logic bug** that will:
+- Inflate `sumBestAsk` in neg-risk scanners (neg-risk scanner was broken for its entire deployment because of this)
+- Report false-stale edges in CLOB validation passes
+- Cause BBO-based edge calculations to be completely wrong
+
+This is confirmed in the bot codebase comments: *"CLOB /book returns unsorted arrays"* (bot.js ~line 1804) and was a known bug. Always grep for `asks[0]` when auditing any CLOB-consuming code.
+
+### Volume field paths vary
+- At event level: `event['volume']` (float)
+- At market level: `market['volumeNum']` (float) or `market['volume']` (string)
+- Normalize with: `float(m.get('volumeNum', 0) or m.get('volume', 0))`
+
+### Event-by-slug can return empty
+Not all slugs resolve. `events?slug=some-slug` returns an empty list `[]` for invalid slugs. Check for this before indexing.
+
+## Digest / Cron Workflow
+
+For automated market scanning (scheduled cron job), use `scripts/polymarket_digest.py`.
+
+Typical flow:
+1. Fetch trending events: `events?limit=10&active=true&closed=false&order=volume&ascending=false`
+2. Keyword search: `public-search?q=NBA&limit=5`, `public-search?q=NHL&limit=5`, etc.
+3. For each keyword result, supplement with event-slug queries for championship/tournament events (more reliable than free-text search)
+4. Parse prices via double-encoded JSON loading
+5. Filter to active + non-closed markets with non-zero Yes prices for contenders
+6. Format as readable digest with event title, market question, Yes/No %, volume, conditionId
+
+Important: Some keyword results are game-level markets (single games) vs championship-level. Both are valid but should be labeled clearly. Championship-level data comes from event-slug queries, game-level from public-search.
+
+## Rate Limits
+
+Generous — unlikely to hit for normal usage:
+- Gamma: 4,000 requests per 10 seconds (general)
+- CLOB: 9,000 requests per 10 seconds (general)
+- Data: 1,000 requests per 10 seconds (general)
+
+## Limitations
+
+- This skill is read-only — it does not support placing trades
+- Trading requires wallet-based crypto authentication (EIP-712 signatures)
+- Some new markets may have empty price history
+- Geographic restrictions apply to trading but read-only data is globally accessible

package/dist/assets/skills/protocol-api-key-integration/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: protocol-api-key-integration
+description: Safely connect API keys for trading protocols and venue SDKs without exposing secrets; use read/health/preview first, live execution double-gated.
+triggers:
+  - connect protocol API keys
+  - Pear Protocol keys
+  - Hyperliquid protocol keys
+  - add venue API key
+  - trading SDK credentials
+  - ChangeNOW API key
+  - BTC to ETH convert in Oracle
+---
+
+> Oracle native tools: `oracle_cli` (read/prepare), `vault_status`, `signer_status`, `signer_execute` (needs human confirmationNonce), `skill_load`. No generic shell. No fleet SSH.
+
+
+# Protocol API key integration
+
+Use when DEMI wants Pear Protocol, Hyperliquid-adjacent tools, ChangeNOW convert, or any trading protocol API keys connected to the agent stack.
+
+## Hard rules
+- Never accept key values in chat, prompts, or tool args.
+- Never print secrets. Health output reports present/source/value redacted only.
+- Main/capital wallet is not an automated signer.
+- Prefer agent/API wallets that cannot withdraw.
+- Install credentials through owner-only files or a local prompt that never echoes values.
+- Start with read/health/preview; live orders stay disabled until explicit GO plus caps.
+
+## API-key-gated aggregators (0x / 1inch)
+
+For aggregator adapters, “wired” and “configured” are different. Code/tests can prove the prepare path with fake keys, but live routes still require real keys installed in owner-only env.
+
+- 0x uses `ZEROX_API_KEY` / `0X_API_KEY`; health with no key should report `configured:false` / key-missing, not pretend the provider is down.
+- 1inch uses `ONEINCH_API_KEY`; executable `/swap` and `/approve/spender` are key-gated. Slippage for 1inch Classic Swap API is percentage points (`0.3` = 30 bps).
+- Do not paste keys into chat or test fixtures. Unit tests may pass `{ apiKey: "test-key" }` only against mocked `fetchImpl`; never claim that means live configuration.
+- After adding keys, verify with redacted health and one tiny fresh quote/prepare smoke; never print returned auth headers, raw key values, or env file contents.
+
+## ChangeNOW multi-asset convert (BTC↔ETH / any ticker)
+Hosted deposit-address rail when DEX+bridges cannot cover **native BTC** or awkward pairs. No good fully on-chain BTC→ETH path in Oracle today.
+
+- Provider: `multiagent-desk` catalog `changenow` (`src/data/providers/changenow.mjs`).
+- Ops: health · currencies · minAmount · estimate/convertQuote · createExchange · status.
+- **Prepare-only:** create returns deposit address; user funds it; Oracle never custodies unless separate GO to fund deposit from agent.
+- Currencies public; **estimate/create need** `CHANGENOW_API_KEY` (`x-changenow-api-key`). Health reports `keyConfigured` honestly.
+- Env: `CHANGENOW_API_KEY`, optional `CHANGENOW_API_URL`. Never paste keys in chat.
+- Prefer desk DEX/bridges for EVM↔EVM. Full detail: `references/changenow-convert.md` + repo `docs/CHANGENOW_CONVERT.md`.
+
+## Standard implementation shape
+1. Pick the right repo/surface.
+   - Internal cross-venue/cross-chain tooling: `multiagent-desk`.
+   - Public RH product/site/API/MCP: only if DEMI explicitly asks; RH product normally stays RH-only.
+2. Create a root/user-only env or secret file.
+   - Directory mode `0700`.
+   - File mode `0600` or `0400`.
+   - Refuse group/other-readable files.
+3. Parse dotenv manually; do not shell-source untrusted secret files inside agent code.
+4. Merge precedence: owner-only file first, environment overrides second.
+5. Add redacted health output:
+   - file exists/mode
+   - credential present true/false
+   - SDK installed true/false
+   - endpoint reachable/auth-required status
+   - live gates true/false
+6. Add preview builders that validate symbol, size, notional cap, and return `dryRun:true`, `executable:false` by default.
+7. Add tests before production code:
+   - bad permissions rejected
+   - redacted status contains no raw secret substring
+   - live execution refuses when gates are off
+   - preview validates amount/cap without sending an order
+8. Live execution gate ladder:
+   - protocol key installed
+   - agent wallet approved/funded if required
+   - global execute gate on
+   - protocol-specific trade gate on
+   - per-symbol/venue allowlist
+   - max notional cap
+   - fresh quote/sim/preview
+   - explicit DEMI GO
+
+## Pear + Hyperliquid case
+See `references/pear-hyperliquid-keys.md` for the current `multiagent-desk` implementation pattern, commands, and Pear SDK quirks.
+
+## Documenting key setup for OTHER people (open-source SETUP.md)
+
+When the project ships to strangers, the same rules become **docs**, and DEMI asks
+for them by name ("fix the read mes on how to set up, ie api for hyperliquid api
+for polymarket keys and how they are stored etc"). Put it in a dedicated
+`SETUP.md` and link it prominently from the README — buried key docs mean people
+export secrets however they guess.
+
+Cover, in this order:
+
+1. **The two planes, stated first.** Read/prepare needs no key; execute always
+   does. A prepared artifact is inert until something signs it. Without this
+   framing every later instruction reads as "give the tool your key".
+2. **What each key unlocks AND what still works without it** — as a table. People
+   need to know they can evaluate the thing before handing over credentials.
+   Hyperliquid reads are keyless; Polymarket market data is keyless.
+3. **Per-venue credential shape**, because they differ structurally:
+   - **Hyperliquid issues no API key.** You authorize with an Ethereum private
+     key — use an **API wallet** (`app.hyperliquid.xyz/API`) that can trade but
+     **cannot withdraw**. Say that explicitly; it is the single most important
+     safety fact for an agent.
+   - **Polymarket needs two different things**: L2 API credentials
+     (`API_KEY`/`API_SECRET`/`API_PASSPHRASE`) for CLOB order posting, *and* the
+     Polygon private key that owns the funds. Conflating them wastes an hour.
+4. **Storage, worst → best**, with the honest tradeoff at each tier: env vars
+   (visible in `ps`, inherited by children), a `0600` key file, an encrypted
+   vault. Include the `chmod`/`printf` commands so nobody invents their own.
+5. **What the encryption does NOT protect.** A vault defends backups, cloud sync,
+   and stolen disks at rest; it does **not** defend malware running as the user
+   while the process is unlocked. Overselling a file-level scheme is worse than
+   shipping none, because it changes behaviour.
+6. **Both trade paths side by side** — non-custodial (Oracle prepares, user's
+   wallet signs) and agentic (Oracle holds a key and submits) — so the reader
+   picks deliberately rather than defaulting into custody.
+
+Also state where credentials travel: pinned provider endpoints, key dropped
+rather than forwarded when a `baseUrl` is redirected or downgraded to `http://`.
+
+### Arguing for a model router without overclaiming
+
+When the project is a library, say plainly that **any** provider works (it is
+just functions plus an MCP server), then make the specific case for Hermes:
+per-profile routing matches a stack whose workloads have opposite needs —
+cheap/wide for research, fast for execution (latency is money), strongest for
+risk review, small for unattended crons — and the research profile can hold **no
+signing key at all**.
+
+Ground it in evidence rather than adjectives. The strongest available argument is
+a multi-lineage audit result: four model families reviewed this codebase and each
+found a CRITICAL the others missed, so one model reviewing its own work would
+have shipped three of them. That is a fact about blind spots, not a vendor pitch.
+
+## Reporting format
+Use terse plain labels:
+- Status: connected / missing keys / preview-only / live disabled
+- Gates: global, protocol, cap
+- Agent wallet: address only
+- Secrets: present or missing, value redacted
+- Next: exact local/SSH step for DEMI to install keys without pasting them