@termix-it/cryptoclaw 1.0.0

package/skills/dune/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: dune
+description: Execute and query Dune Analytics dashboards for on-chain data and custom SQL analytics.
+metadata:
+  {
+    "cryptoclaw":
+      { "emoji": "🔮", "requires": { "env": ["DUNE_API_KEY"] }, "primaryEnv": "DUNE_API_KEY" },
+  }
+---
+
+# Dune Analytics API
+
+Execute SQL queries on blockchain data, fetch dashboard results, and access curated datasets via the Dune API.
+
+## Base URL
+
+```
+https://api.dune.com/api/v1
+```
+
+Requires API key: set `DUNE_API_KEY`. Free tier available at https://dune.com/settings/api
+
+Pass via header: `X-Dune-API-Key: {key}`
+
+## Core Workflow
+
+### 1. Execute a Query
+
+```
+POST /query/{query_id}/execute
+```
+
+Body (optional filters):
+
+```json
+{
+  "query_parameters": {
+    "wallet_address": "0x...",
+    "token_address": "0x..."
+  }
+}
+```
+
+Returns `execution_id` for polling.
+
+### 2. Check Execution Status
+
+```
+GET /execution/{execution_id}/status
+```
+
+States: `QUERY_STATE_PENDING`, `QUERY_STATE_EXECUTING`, `QUERY_STATE_COMPLETED`, `QUERY_STATE_FAILED`
+
+Poll every 2-3 seconds until completed.
+
+### 3. Get Results
+
+```
+GET /execution/{execution_id}/results
+```
+
+Returns rows as JSON with column metadata. Use `?limit=100&offset=0` for pagination.
+
+### Shortcut: Get Latest Results
+
+```
+GET /query/{query_id}/results
+```
+
+Returns cached results from the last execution without re-running. Fast and free of execution credits.
+
+## Useful Public Query IDs
+
+| Query ID  | Description                       |
+| --------- | --------------------------------- |
+| `3237721` | Top DEX traders by volume (7d)    |
+| `3105506` | Whale token transfers (24h)       |
+| `2030664` | Stablecoin flows by chain         |
+| `1847958` | NFT marketplace volume comparison |
+| `3532352` | Bridge volume across chains       |
+| `2474310` | Gas spent by protocol (Ethereum)  |
+
+Note: Public query IDs may change or become unavailable. Verify before relying on them.
+
+## Writing Custom Queries
+
+### Create a Query
+
+```
+POST /query
+```
+
+Body:
+
+```json
+{
+  "name": "My Query",
+  "query_sql": "SELECT * FROM ethereum.transactions WHERE \"from\" = {{wallet_address}} ORDER BY block_time DESC LIMIT 100",
+  "is_private": false
+}
+```
+
+### Key Tables
+
+| Table                         | Chain    | Description            |
+| ----------------------------- | -------- | ---------------------- |
+| `ethereum.transactions`       | ETH      | All transactions       |
+| `bnb.transactions`            | BSC      | BSC transactions       |
+| `polygon.transactions`        | Polygon  | Polygon transactions   |
+| `arbitrum.transactions`       | Arbitrum | Arbitrum transactions  |
+| `erc20_ethereum.evt_Transfer` | ETH      | ERC-20 transfer events |
+| `erc20_bnb.evt_Transfer`      | BSC      | BEP-20 transfer events |
+| `dex.trades`                  | Multi    | Aggregated DEX trades  |
+| `nft.trades`                  | Multi    | Aggregated NFT trades  |
+| `prices.usd`                  | Multi    | Token prices (hourly)  |
+| `tokens.erc20`                | Multi    | Token metadata         |
+
+### DuneSQL Syntax Notes
+
+- DuneSQL is based on Trino (Presto fork)
+- Use double quotes for column names with special chars: `"from"`, `"to"`
+- Byte arrays (addresses): `0x` prefix works, use `LOWER()` for case-insensitive matching
+- Timestamps: `block_time` is TIMESTAMP type, use `NOW() - INTERVAL '7' DAY` for ranges
+- Aggregations: standard SQL — `SUM()`, `COUNT()`, `AVG()`, `GROUP BY`
+- Use `LIMIT` always — avoid unbounded queries
+
+### Example Custom Queries
+
+Wallet transaction count (last 30 days):
+
+```sql
+SELECT COUNT(*) as tx_count, SUM(value / 1e18) as total_eth
+FROM ethereum.transactions
+WHERE "from" = {{wallet_address}}
+  AND block_time > NOW() - INTERVAL '30' DAY
+```
+
+Top tokens by transfer volume (24h):
+
+```sql
+SELECT t.symbol, COUNT(*) as transfers, SUM(evt.value / POW(10, t.decimals)) as volume
+FROM erc20_ethereum.evt_Transfer evt
+JOIN tokens.erc20 t ON t.contract_address = evt.contract_address AND t.blockchain = 'ethereum'
+WHERE evt.evt_block_time > NOW() - INTERVAL '1' DAY
+GROUP BY t.symbol
+ORDER BY transfers DESC
+LIMIT 20
+```
+
+## API Limits (Free Tier)
+
+- 10 query executions per day (re-execute)
+- 250 datapoints per result
+- Cached results (`/query/{id}/results`) do not count against execution limits
+- Prefer cached results when freshness is not critical
+
+## Usage Notes
+
+- **Prefer cached results** (`GET /query/{id}/results`) over re-executing queries to conserve credits
+- For wallet-specific analysis, pass the address as a `query_parameter` rather than hardcoding
+- Always use `LIMIT` in custom SQL to avoid timeouts and large payloads
+- Combine with `debank` for real-time portfolio data and `defillama` for protocol-level TVL
+- When building custom queries, test with small limits first
+- Present results in tables or summaries — raw Dune output can be verbose
+
+## Example Interactions
+
+User: "Show top DEX traders this week"
+→ Fetch cached results from query 3237721, present top 10 by volume
+
+User: "How many transactions has my wallet done?"
+→ Execute custom query with wallet_address parameter, report count and total value
+
+User: "What are the biggest token transfers today?"
+→ Fetch cached whale transfer query, present top movers
+
+User: "Write a query to find all USDT transfers over $100k on BSC"
+→ Create custom SQL on `erc20_bnb.evt_Transfer`, filter by USDT address and amount threshold

package/skills/etherscan/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: etherscan
+description: Query block explorer APIs (Etherscan, BSCScan, Polygonscan, etc.) for transactions, contracts, and gas data.
+metadata:
+  {
+    "cryptoclaw":
+      {
+        "emoji": "🔍",
+        "requires": { "env": ["ETHERSCAN_API_KEY"] },
+        "primaryEnv": "ETHERSCAN_API_KEY",
+      },
+  }
+---
+
+# Multi-chain Explorer API
+
+Query Etherscan-compatible block explorer APIs for transaction history, contract source code, ABIs, and gas data.
+
+## Supported Explorers
+
+| Chain    | Base URL                                  | Env Var (optional override)   |
+| -------- | ----------------------------------------- | ----------------------------- |
+| Ethereum | `https://api.etherscan.io/api`            | `ETHERSCAN_API_KEY`           |
+| BSC      | `https://api.bscscan.com/api`             | `BSCSCAN_API_KEY` or same key |
+| Polygon  | `https://api.polygonscan.com/api`         | `POLYGONSCAN_API_KEY`         |
+| Arbitrum | `https://api.arbiscan.io/api`             | `ARBISCAN_API_KEY`            |
+| Optimism | `https://api-optimistic.etherscan.io/api` | `OPTIMISM_API_KEY`            |
+| Base     | `https://api.basescan.org/api`            | `BASESCAN_API_KEY`            |
+
+All explorers accept the `apikey` parameter. Many share a single Etherscan key, but some chains require separate registration.
+
+**Rate limit**: 5 calls/second per key.
+
+## Modules & Actions
+
+### Account — Transaction History
+
+```
+?module=account&action=txlist&address={addr}&startblock=0&endblock=99999999&page=1&offset=20&sort=desc&apikey={key}
+```
+
+Returns normal transactions for an address.
+
+### Account — Token Transfers (ERC-20)
+
+```
+?module=account&action=tokentx&address={addr}&page=1&offset=20&sort=desc&apikey={key}
+```
+
+Filter by contract: add `&contractaddress={token}`
+
+### Account — ERC-721 Transfers
+
+```
+?module=account&action=tokennfttx&address={addr}&page=1&offset=20&sort=desc&apikey={key}
+```
+
+### Account — Balance
+
+```
+?module=account&action=balance&address={addr}&tag=latest&apikey={key}
+```
+
+Returns balance in wei. Divide by 1e18 for ETH/BNB.
+
+### Contract — Get ABI
+
+```
+?module=contract&action=getabi&address={addr}&apikey={key}
+```
+
+Returns the contract ABI as a JSON string. **Tip**: Parse the result and pass it to `read_contract` or `write_contract` for dynamic contract interaction.
+
+### Contract — Get Source Code
+
+```
+?module=contract&action=getsourcecode&address={addr}&apikey={key}
+```
+
+Returns source code, compiler version, constructor arguments, and proxy implementation address if applicable.
+
+### Gas Tracker (Ethereum only)
+
+```
+?module=gastracker&action=gasoracle&apikey={key}
+```
+
+Returns SafeGasPrice, ProposeGasPrice, FastGasPrice in gwei.
+
+## Workflow: Dynamic Contract Interaction
+
+1. User provides a contract address
+2. Call `getabi` to fetch the ABI
+3. Parse the ABI to list available read/write functions
+4. Use `read_contract` with the ABI and function name to query
+5. Use `write_contract` for state-changing calls (with user confirmation)
+
+This enables interacting with ANY verified contract without pre-built tools.
+
+## Usage Notes
+
+- Always include `&apikey={key}` — requests without it are heavily rate-limited
+- Use `offset` and `page` for pagination; don't fetch more than needed
+- The `getabi` endpoint only works for verified contracts
+- For proxy contracts, `getsourcecode` includes the implementation address — fetch that ABI too
+- Cross-reference contract data with `security-check` skill for risk assessment
+
+## Example Queries
+
+User: "Show my recent transactions on BSC"
+→ Call BSCScan `txlist` for active wallet, present last 10 with value and status
+
+User: "Get the ABI for this contract: 0x..."
+→ Call `getabi`, parse result, summarize available functions
+
+User: "What's the current gas price on Ethereum?"
+→ Call `gasoracle`, present safe/standard/fast prices

package/skills/four-meme/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: four-meme
+description: Discover and analyze tokens on the four.meme BSC launchpad.
+metadata: { "cryptoclaw": { "emoji": "🐸", "always": true } }
+---
+
+# four.meme Launchpad
+
+Discover and analyze memecoin launches on the four.meme BSC launchpad.
+
+## Overview
+
+four.meme is a memecoin launchpad on BSC where tokens are created with bonding curve mechanics. This skill covers **read-only discovery and analysis** — it does NOT auto-execute trades.
+
+**Experimental**: Contract addresses and page structure may change. Verify before relying on cached data.
+
+## Data Sources
+
+### Web Fetch
+
+Fetch trending and new token listings from the four.meme website:
+
+```
+https://four.meme
+```
+
+Parse the page for:
+
+- Token name, symbol, contract address
+- Creator address
+- Current bonding curve progress
+- Market cap / liquidity
+
+### On-chain Queries
+
+Use `read_contract` to query bonding curve contracts:
+
+- **Token balance**: Check how many tokens remain in the curve
+- **Current price**: Read the current price point on the curve
+- **Graduation threshold**: When the token migrates to PancakeSwap
+- **LP status**: Whether liquidity has been added to a DEX
+
+## Workflow
+
+1. User asks about four.meme tokens → web fetch the page
+2. Extract token list with contract addresses
+3. For a specific token: `read_contract` on the bonding curve for price/supply data
+4. Present findings with contract address, progress, and holder count
+5. If user wants to buy: direct them to use the `token-swap` skill with the contract address
+
+## Risk Warning
+
+Memecoins launched on four.meme carry **extreme risk**:
+
+- Most tokens go to zero
+- Bonding curves can be manipulated by creators
+- Rug pulls are common — creator can dump tokens after graduation
+- Low liquidity means high slippage
+- Smart contract risk — contracts may not be verified
+
+**Always remind users of these risks when discussing four.meme tokens.**
+
+## Usage Notes
+
+- This skill is discovery-only; actual trades go through `token-swap`
+- Contract addresses for the launchpad factory may change — verify on the site
+- The bonding curve contract differs from the final PancakeSwap pair
+- Check if the token has graduated (migrated to DEX) before attempting swaps
+- Track creator wallets for patterns across multiple launches
+
+## Example Interactions
+
+User: "What's trending on four.meme?"
+→ Web fetch four.meme, parse trending tokens, list top 5 with progress %
+
+User: "Analyze this four.meme token: 0x..."
+→ Read bonding curve contract, report price, supply, graduation progress
+
+User: "Has this token graduated yet?"
+→ Check if liquidity exists on PancakeSwap for the token address

package/skills/gas-tracker/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: gas-tracker
+description: Monitor gas prices across blockchain networks.
+metadata: { "cryptoclaw": { "emoji": "⛽", "always": true } }
+---
+
+# Gas Tracker Skill
+
+Monitor gas prices across blockchain networks.
+
+## Overview
+
+Provide real-time gas price information to help users time their transactions for optimal costs.
+
+## Capabilities
+
+- **Current gas price**: Show gas price in Gwei for any network
+- **Multi-chain comparison**: Compare gas costs across networks
+- **Gas estimation**: Estimate cost for specific transaction types
+- **Network congestion**: Report on current network load
+
+## Tools Used
+
+- `get_network_info` - Fetch current gas price per network
+- `estimate_gas` - Estimate specific transaction costs
+- `get_block_info` - Check block utilization
+
+## Example Interactions
+
+User: "What's gas on Ethereum right now?"
+Action: Query ETH mainnet gas price, report in Gwei and USD
+
+User: "Compare gas across chains"
+Action: Query gas price on ETH, BSC, Polygon, Arbitrum, format comparison
+
+User: "How much would a token transfer cost on BSC?"
+Action: Estimate gas for ERC20 transfer on BSC, show in BNB and USD
+
+## Notes
+
+- Gas prices fluctuate rapidly; always note the timestamp
+- For L2s (Arbitrum, Optimism, Base), note that gas is typically much cheaper
+- BSC gas is typically 3-5 Gwei; Ethereum varies widely

package/skills/github/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: github
+description: "Interact with GitHub using the `gh` CLI. Use `gh issue`, `gh pr`, `gh run`, and `gh api` for issues, PRs, CI runs, and advanced queries."
+metadata:
+  {
+    "cryptoclaw":
+      {
+        "emoji": "🐙",
+        "requires": { "bins": ["gh"] },
+        "install":
+          [
+            {
+              "id": "brew",
+              "kind": "brew",
+              "formula": "gh",
+              "bins": ["gh"],
+              "label": "Install GitHub CLI (brew)",
+            },
+            {
+              "id": "apt",
+              "kind": "apt",
+              "package": "gh",
+              "bins": ["gh"],
+              "label": "Install GitHub CLI (apt)",
+            },
+          ],
+      },
+  }
+---
+
+# GitHub Skill
+
+Use the `gh` CLI to interact with GitHub. Always specify `--repo owner/repo` when not in a git directory, or use URLs directly.
+
+## Pull Requests
+
+Check CI status on a PR:
+
+```bash
+gh pr checks 55 --repo owner/repo
+```
+
+List recent workflow runs:
+
+```bash
+gh run list --repo owner/repo --limit 10
+```
+
+View a run and see which steps failed:
+
+```bash
+gh run view <run-id> --repo owner/repo
+```
+
+View logs for failed steps only:
+
+```bash
+gh run view <run-id> --repo owner/repo --log-failed
+```
+
+## API for Advanced Queries
+
+The `gh api` command is useful for accessing data not available through other subcommands.
+
+Get PR with specific fields:
+
+```bash
+gh api repos/owner/repo/pulls/55 --jq '.title, .state, .user.login'
+```
+
+## JSON Output
+
+Most commands support `--json` for structured output. You can use `--jq` to filter:
+
+```bash
+gh issue list --repo owner/repo --json number,title --jq '.[] | "\(.number): \(.title)"'
+```

package/skills/macro-calendar/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: macro-calendar
+description: Track macroeconomic events, Fed rates, CPI, and economic indicators affecting crypto.
+metadata: { "cryptoclaw": { "emoji": "📅", "always": true } }
+---
+
+# Economic Calendar & Macro Data
+
+Track macroeconomic events and economic indicators that impact crypto markets.
+
+## Data Sources
+
+### 1. FRED API (Federal Reserve Economic Data)
+
+```
+https://api.stlouisfed.org/fred/
+```
+
+Free API key: register at https://fred.stlouisfed.org/docs/api/api_key.html
+
+If `FRED_API_KEY` is set, use it. Otherwise, note the data is unavailable and suggest the user register for a free key.
+
+#### Key Series
+
+| Series ID  | Description                    |
+| ---------- | ------------------------------ |
+| `FEDFUNDS` | Federal Funds Effective Rate   |
+| `CPIAUCSL` | Consumer Price Index (CPI)     |
+| `UNRATE`   | Unemployment Rate              |
+| `GDP`      | Gross Domestic Product         |
+| `DGS10`    | 10-Year Treasury Yield         |
+| `DGS2`     | 2-Year Treasury Yield          |
+| `T10Y2Y`   | 10Y-2Y Spread (yield curve)    |
+| `M2SL`     | M2 Money Supply                |
+| `WALCL`    | Fed Balance Sheet Total Assets |
+| `DEXUSEU`  | USD/EUR Exchange Rate          |
+
+#### Endpoints
+
+Latest observation:
+
+```
+GET /fred/series/observations?series_id={id}&sort_order=desc&limit=1&api_key={key}&file_type=json
+```
+
+Historical data:
+
+```
+GET /fred/series/observations?series_id={id}&observation_start={YYYY-MM-DD}&api_key={key}&file_type=json
+```
+
+Series metadata:
+
+```
+GET /fred/series?series_id={id}&api_key={key}&file_type=json
+```
+
+### 2. Finnhub Economic Calendar
+
+```
+https://finnhub.io/api/v1/calendar/economic
+```
+
+Free API key: register at https://finnhub.io. Set `FINNHUB_API_KEY`.
+
+#### Endpoint
+
+```
+GET /calendar/economic?from={YYYY-MM-DD}&to={YYYY-MM-DD}&token={key}
+```
+
+Returns upcoming economic events with:
+
+- `event` — event name
+- `country` — country code
+- `impact` — `high`, `medium`, `low`
+- `actual` / `estimate` / `prev` — data values
+- `time` — event timestamp
+
+## Key Events for Crypto
+
+### High Impact
+
+| Event                   | Frequency | Why It Matters                      |
+| ----------------------- | --------- | ----------------------------------- |
+| FOMC Rate Decision      | 8x/year   | Rate hikes → risk-off → crypto down |
+| CPI (Inflation)         | Monthly   | High CPI → more hikes expected      |
+| Non-Farm Payrolls (NFP) | Monthly   | Strong jobs → hawkish Fed           |
+| GDP                     | Quarterly | Recession fears → flight to safety  |
+| PCE Price Index         | Monthly   | Fed's preferred inflation gauge     |
+
+### Medium Impact
+
+| Event               | Frequency | Why It Matters             |
+| ------------------- | --------- | -------------------------- |
+| PMI (Manufacturing) | Monthly   | Economic health indicator  |
+| Retail Sales        | Monthly   | Consumer spending strength |
+| Jobless Claims      | Weekly    | Labor market pulse         |
+| ISM Services        | Monthly   | Service sector health      |
+
+## Impact on Crypto
+
+General patterns (not financial advice):
+
+- **Rate cuts / dovish Fed** → bullish for crypto (more liquidity)
+- **Rate hikes / hawkish Fed** → bearish for crypto (less liquidity)
+- **CPI above expectations** → bearish (more hikes coming)
+- **CPI below expectations** → bullish (rate cuts possible)
+- **Strong jobs data** → mixed (good economy but hawkish Fed)
+- **Yield curve inversion** → recession signal, initially bearish then bullish
+
+## Usage Notes
+
+- Always note that macro-to-crypto correlation is not guaranteed
+- Present event times in the user's timezone when possible
+- For FOMC meetings, note both the date and the press conference time
+- Combine with `crypto-news` for full market context
+- If no API keys are available, summarize what data would be accessible and suggest registration
+
+## Example Interactions
+
+User: "When is the next Fed meeting?"
+→ Check Finnhub calendar for FOMC events, report date and current rate expectations
+
+User: "What's the current CPI?"
+→ Fetch FRED series CPIAUCSL, report latest reading and YoY change
+
+User: "Any major economic events this week?"
+→ Fetch Finnhub calendar for current week, filter by high impact, list events
+
+User: "How does the yield curve look?"
+→ Fetch DGS10, DGS2, T10Y2Y from FRED, report current spread and inversion status

package/skills/market-data/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: market-data
+description: Fetch cryptocurrency prices, market caps, charts, and trending tokens.
+metadata: { "cryptoclaw": { "emoji": "📊", "always": true } }
+---
+
+# Market Data Skill
+
+Fetch cryptocurrency prices, market caps, charts, and trending tokens.
+
+## Overview
+
+Provide real-time and historical market data for cryptocurrencies using public APIs (CoinGecko free tier).
+
+## Capabilities
+
+- **Price lookup**: Current price of any token in USD/BTC/ETH
+- **Market overview**: Top tokens by market cap, 24h volume, gainers/losers
+- **Trending tokens**: Currently trending on CoinGecko
+- **Price history**: Historical price data for charting
+- **Token search**: Find tokens by name or symbol
+
+## Data Sources
+
+- CoinGecko API (free, no key required for basic queries)
+- On-chain price from DEX pools via `read_contract` when needed
+
+## Example Interactions
+
+User: "What's the price of ETH?"
+Action: Query CoinGecko for ethereum price, report USD value and 24h change
+
+User: "Show me trending tokens"
+Action: Query CoinGecko trending endpoint, list top 10 with prices
+
+User: "How has BNB performed this week?"
+Action: Query 7-day price history, summarize with high/low/change
+
+## Notes
+
+- Rate limits: CoinGecko free tier allows ~30 calls/minute
+- For on-chain token prices, use DEX router contracts
+- Always show the data source and timestamp
+- For detailed CoinGecko API usage (endpoints, parameters, ID lookup), see the `coingecko` skill