@termix-it/cryptoclaw 1.0.0 → 1.0.2

package/docs/blockchain/contracts.md

@@ -0,0 +1,96 @@
+---
+summary: "Deploy, call, and verify smart contracts on any supported EVM chain."
+title: "Smart Contracts"
+---
+
+# Smart Contracts
+
+CryptoClaw helps you deploy and interact with smart contracts across supported EVM chains.
+
+## Operations
+
+| Tool                  | Description                               | Confirmation |
+| --------------------- | ----------------------------------------- | :----------: |
+| `write_contract`      | Execute a state-changing contract call    |     Yes      |
+| `read_contract`       | Read data from a contract                 |              |
+| `get_contract_abi`    | Fetch verified contract ABI from explorer |              |
+| `get_contract_source` | Fetch verified source code                |              |
+| `deploy_contract`     | Deploy a contract from bytecode           |     Yes      |
+
+## Contract deployment
+
+CryptoClaw provides templates for common token standards:
+
+| Template | Standard | Description                                   |
+| -------- | -------- | --------------------------------------------- |
+| ERC-20   | Token    | Fungible token with standard transfer/approve |
+| ERC-721  | NFT      | Non-fungible token collection                 |
+
+### Deployment flow
+
+<Steps>
+  <Step title="Describe your contract">
+    Tell the agent what you want to deploy. For example: "Deploy an ERC-20 token called MyToken with symbol MTK and 1 million supply"
+  </Step>
+  <Step title="Review parameters">
+    The agent prepares the deployment with gas estimation and shows all parameters for review.
+  </Step>
+  <Step title="Confirm and deploy">
+    Approve the transaction. The agent submits the deployment and returns the contract address.
+  </Step>
+</Steps>
+
+<Warning>
+Always test deployments on a testnet (BSC Testnet, Sepolia) before deploying to mainnet. Mainnet deployments cost real funds and are irreversible.
+</Warning>
+
+## Contract interaction
+
+### Reading contract data
+
+```
+"Read the totalSupply of contract 0x..."
+"What's the owner of contract 0x... on BSC?"
+"Get the balance of 0x... on the USDT contract"
+```
+
+### Writing to contracts
+
+```
+"Call the approve function on USDT contract for 100 tokens"
+"Execute the stake function on contract 0x... with 10 BNB"
+```
+
+All write operations require confirmation through the tx-gate.
+
+## Explorer integration
+
+CryptoClaw integrates with block explorers via the Etherscan API family:
+
+| Chain    | Explorer             |
+| -------- | -------------------- |
+| Ethereum | Etherscan            |
+| BSC      | BSCScan              |
+| Polygon  | Polygonscan          |
+| Arbitrum | Arbiscan             |
+| Optimism | Optimistic Etherscan |
+| Base     | BaseScan             |
+
+### Setup
+
+```bash
+export ETHERSCAN_API_KEY=your_key_here
+```
+
+### Explorer operations
+
+- Fetch verified contract ABI for dynamic interaction
+- View contract source code
+- Query transaction history
+- Check token transfers
+- Monitor gas prices
+
+## Related
+
+- [NFT Manager](/blockchain/nft) — Specialized NFT operations
+- [Transaction Security](/blockchain/security) — Confirmation and spending limits

package/docs/blockchain/defi.md

@@ -0,0 +1,61 @@
+---
+summary: "Monitor DeFi positions — yield farming, staking, liquidity pools, and protocol analytics."
+title: "DeFi Dashboard"
+---
+
+# DeFi Dashboard
+
+CryptoClaw provides a comprehensive DeFi monitoring dashboard that tracks your positions across protocols and surfaces yield opportunities.
+
+## Data sources
+
+The DeFi dashboard combines data from multiple sources:
+
+- **On-chain contract queries** — Direct reads from protocol contracts (Aave, PancakeSwap, Uniswap, Compound)
+- **DeFiLlama API** — TVL data, protocol analytics, yield pool rankings (no API key required)
+- **DeBank API** — Wallet-level DeFi positions across 100+ chains (requires `DEBANK_API_KEY`)
+
+## Supported protocols
+
+| Protocol    | Chains                            | Features                               |
+| ----------- | --------------------------------- | -------------------------------------- |
+| PancakeSwap | BSC, Ethereum                     | LP positions, farming rewards          |
+| Uniswap     | Ethereum, Polygon, Arbitrum, Base | V2/V3 positions, fee earnings          |
+| Aave        | BSC, Ethereum, Polygon            | Supply/borrow positions, health factor |
+| Compound    | Ethereum                          | Supply/borrow positions                |
+
+## Operations
+
+**Position monitoring:**
+
+- "Show my DeFi positions" — Lists all active positions across protocols
+- "What's my Aave health factor?" — Checks liquidation risk
+- "How much am I earning on PancakeSwap?" — Shows farming rewards
+
+**Protocol analytics:**
+
+- "What's the TVL of Aave?" — Total value locked via DeFiLlama
+- "Top yield pools on BSC" — Ranked by APY
+- "Compare lending rates across protocols" — Side-by-side comparison
+
+**Yield discovery:**
+
+- "Best stablecoin yields on Ethereum" — Filtered yield pool search
+- "Show trending DeFi protocols" — Protocols with growing TVL
+
+## Configuration
+
+Set up API keys for enhanced data:
+
+```bash
+# Optional: DeBank for wallet-level positions
+export DEBANK_API_KEY=your_key_here
+```
+
+DeFiLlama data works without any API key.
+
+## Related
+
+- [Token Swap](/blockchain/swap) — Execute swaps on DEXs
+- [AAVE Lending](/blockchain/aave) — Supply, borrow, and repay on Aave V3
+- [Portfolio Tracker](/blockchain/portfolio) — Aggregate holdings view

package/docs/blockchain/index.md

@@ -0,0 +1,92 @@
+---
+summary: "CryptoClaw blockchain capabilities — wallet management, DeFi, NFTs, and multi-chain support across 16+ EVM networks."
+title: "Blockchain Overview"
+---
+
+# Blockchain Overview
+
+CryptoClaw extends a multi-channel AI assistant with native blockchain capabilities. Interact with EVM-compatible chains directly from chat — manage wallets, swap tokens, track portfolios, deploy contracts, and more.
+
+## Supported networks
+
+CryptoClaw supports **16+ EVM-compatible chains** including:
+
+| Network           | Chain ID | Default |
+| ----------------- | -------- | ------- |
+| BNB Smart Chain   | 56       | Yes     |
+| Ethereum          | 1        |         |
+| Polygon           | 137      |         |
+| Arbitrum One      | 42161    |         |
+| Optimism          | 10       |         |
+| Base              | 8453     |         |
+| Avalanche C-Chain | 43114    |         |
+| Fantom            | 250      |         |
+| Cronos            | 25       |         |
+| zkSync Era        | 324      |         |
+| BSC Testnet       | 97       |         |
+| Sepolia           | 11155111 |         |
+
+Specify any chain by name or ID when calling tools. BSC is the default.
+
+## Security model
+
+All blockchain operations in CryptoClaw follow strict security principles:
+
+- **Encrypted at rest** — Private keys stored with AES-256-GCM encryption (scrypt KDF)
+- **Confirmation gates** — State-changing operations (transfers, swaps, contract writes) require explicit user confirmation
+- **Spending limits** — Configurable per-transaction and daily USD caps
+- **Key redaction** — Private keys are never exposed in agent transcripts
+- **CLI-only sensitive ops** — Import/export operations restricted to the CLI
+
+See [Transaction Security](/blockchain/security) for the full architecture.
+
+## Capabilities
+
+<Columns>
+  <Card title="Wallet Management" href="/blockchain/wallet" icon="wallet">
+    Create, import, and manage encrypted wallets. Check balances across chains.
+  </Card>
+  <Card title="Token Swap" href="/blockchain/swap" icon="arrow-left-right">
+    Swap tokens on PancakeSwap, Uniswap V2/V3 with slippage protection.
+  </Card>
+  <Card title="DeFi Dashboard" href="/blockchain/defi" icon="bar-chart-3">
+    Monitor yield farming, staking, and liquidity pool positions.
+  </Card>
+  <Card title="Market Data" href="/blockchain/market-data" icon="trending-up">
+    Real-time prices, charts, trending tokens, and on-chain analytics.
+  </Card>
+  <Card title="Portfolio Tracker" href="/blockchain/portfolio" icon="pie-chart">
+    Aggregate holdings across wallets and networks with USD valuations.
+  </Card>
+  <Card title="Smart Contracts" href="/blockchain/contracts" icon="file-code">
+    Deploy, call, and verify contracts on any supported chain.
+  </Card>
+  <Card title="NFT Manager" href="/blockchain/nft" icon="image">
+    Mint, transfer, and query ERC-721 and ERC-1155 tokens.
+  </Card>
+  <Card title="AAVE Lending" href="/blockchain/aave" icon="landmark">
+    Supply, borrow, and repay on Aave V3 (BSC).
+  </Card>
+  <Card title="Agent Identity" href="/blockchain/agent-identity" icon="fingerprint">
+    Register on-chain AI agent identity via ERC-8004.
+  </Card>
+</Columns>
+
+## Quick start
+
+<Steps>
+  <Step title="Install CryptoClaw">
+    ```bash
+    npm install -g @termix-it/cryptoclaw
+    ```
+  </Step>
+  <Step title="Create a wallet">
+    ```bash
+    cryptoclaw onboard --wallet
+    ```
+    Or ask the agent: "Create a new wallet"
+  </Step>
+  <Step title="Start interacting">
+    Ask the agent to check balances, swap tokens, or track your portfolio.
+  </Step>
+</Steps>

package/docs/blockchain/market-data.md

@@ -0,0 +1,98 @@
+---
+summary: "Real-time cryptocurrency prices, charts, trending tokens, and on-chain analytics."
+title: "Market Data"
+---
+
+# Market Data
+
+CryptoClaw provides real-time and historical cryptocurrency market data through multiple data providers.
+
+## Data providers
+
+| Provider       |    API Key     | Rate Limit         | Features                           |
+| -------------- | :------------: | ------------------ | ---------------------------------- |
+| CoinGecko      |  Not required  | ~30 calls/min      | Prices, markets, trending, history |
+| Dune Analytics | `DUNE_API_KEY` | 10 exec/day (free) | Custom SQL queries, on-chain data  |
+| DeFiLlama      |  Not required  | Generous           | TVL, yields, stablecoin data       |
+
+## CoinGecko operations
+
+| Operation       | Description                                         |
+| --------------- | --------------------------------------------------- |
+| Price lookup    | Current price in USD/BTC/ETH for any token          |
+| Market overview | Top tokens by market cap with 24h changes           |
+| Trending tokens | Currently trending on CoinGecko                     |
+| Price history   | Historical price charts (1d, 7d, 30d, 1y)           |
+| Token search    | Find tokens by name or symbol                       |
+| Token details   | Full info including links, description, market data |
+
+### Examples
+
+```
+"What's the price of BNB?"
+"Show me the top 10 tokens by market cap"
+"What's trending on CoinGecko?"
+"Show BTC price chart for the last 30 days"
+"Find token info for Chainlink"
+```
+
+## Dune Analytics
+
+Query on-chain data with custom SQL through the Dune API.
+
+### Setup
+
+```bash
+export DUNE_API_KEY=your_key_here
+```
+
+### Operations
+
+| Operation       | Description                  |
+| --------------- | ---------------------------- |
+| Execute query   | Run a DuneSQL query          |
+| Check status    | Poll query execution status  |
+| Get results     | Retrieve query results       |
+| Run saved query | Execute a public query by ID |
+
+### Useful public queries
+
+| Query ID | Description                     |
+| -------- | ------------------------------- |
+| 3286091  | Weekly DEX volume by protocol   |
+| 3237721  | Daily active addresses by chain |
+| 2781844  | Stablecoin supply breakdown     |
+
+### Examples
+
+```
+"Run Dune query 3286091 for weekly DEX volumes"
+"Query total gas spent on Ethereum today"
+"Show daily active addresses on BSC this week"
+```
+
+## DeFiLlama
+
+Protocol and yield data without an API key.
+
+| Operation       | Description                                 |
+| --------------- | ------------------------------------------- |
+| Protocol TVL    | Current and historical TVL for any protocol |
+| Chain TVL       | Total TVL per blockchain                    |
+| Yield pools     | Top yield pools ranked by APY               |
+| Stablecoin data | Supply and chain distribution               |
+| Token prices    | Price data for on-chain tokens              |
+
+### Examples
+
+```
+"What's Aave's total TVL?"
+"Compare TVL across BSC, Ethereum, and Polygon"
+"Top stablecoin yield pools on Ethereum"
+"Show PancakeSwap TVL history"
+```
+
+## Related
+
+- [Portfolio Tracker](/blockchain/portfolio) — Track your own holdings
+- [DeFi Dashboard](/blockchain/defi) — Monitor your DeFi positions

package/docs/blockchain/nft.md

@@ -0,0 +1,44 @@
+---
+summary: "Mint, transfer, and query ERC-721 and ERC-1155 NFTs."
+title: "NFT Manager"
+---
+
+# NFT Manager
+
+CryptoClaw manages NFT collections and individual tokens across ERC-721 and ERC-1155 standards.
+
+## Supported standards
+
+| Standard | Description                                             |
+| -------- | ------------------------------------------------------- |
+| ERC-721  | Non-fungible tokens — unique items                      |
+| ERC-1155 | Multi-token — fungible and non-fungible in one contract |
+
+## Operations
+
+| Tool                  | Description                                   | Confirmation |
+| --------------------- | --------------------------------------------- | :----------: |
+| `transfer_nft`        | Transfer an ERC-721 token                     |     Yes      |
+| `transfer_erc1155`    | Transfer ERC-1155 tokens                      |     Yes      |
+| `get_nft_metadata`    | View token metadata (name, image, attributes) |              |
+| `get_nft_holdings`    | List NFTs owned by an address                 |              |
+| `get_collection_info` | Collection-level stats (supply, floor, etc.)  |              |
+
+## Examples
+
+```
+"Show my NFTs on BSC"
+"What's the metadata for token #42 in collection 0x...?"
+"Transfer NFT #7 from collection 0x... to 0xRecipient"
+"List all NFTs in my wallet on Ethereum"
+"Show collection info for 0x..."
+```
+
+<Warning>
+When transferring NFTs, ensure the recipient address supports the token standard. Sending to a contract that doesn't implement the receiver interface may result in permanent loss.
+</Warning>
+
+## Related
+
+- [Smart Contracts](/blockchain/contracts) — Deploy NFT contracts
+- [Transaction Security](/blockchain/security) — Transfer confirmations

package/docs/blockchain/portfolio.md

@@ -0,0 +1,57 @@
+---
+summary: "Aggregate cryptocurrency holdings across wallets and networks with USD valuations."
+title: "Portfolio Tracker"
+---
+
+# Portfolio Tracker
+
+CryptoClaw aggregates and displays your cryptocurrency holdings across all wallets and networks with real-time USD valuations.
+
+## Tools
+
+| Tool                     | Description                                 |
+| ------------------------ | ------------------------------------------- |
+| `get_native_balance`     | Query native token balance (BNB, ETH, etc.) |
+| `get_erc20_balance`      | Query ERC-20 token balance                  |
+| `wallet_list`            | List all managed wallets                    |
+| `get_supported_networks` | List available networks                     |
+
+## Features
+
+- **Multi-wallet aggregation** — View consolidated holdings across all wallets
+- **Multi-chain support** — Balances from all 16+ supported EVM chains
+- **USD valuation** — Real-time conversion using CoinGecko prices
+- **Token breakdown** — Individual token balances with percentages
+
+## Enhanced data with DeBank
+
+For a comprehensive portfolio view including DeFi positions, configure the DeBank API:
+
+```bash
+export DEBANK_API_KEY=your_key_here
+```
+
+DeBank provides:
+
+- Total portfolio value across 100+ chains
+- Per-chain balance breakdown
+- Token holdings with prices
+- DeFi positions (lending, LP, staking)
+- NFT holdings
+- Transaction history
+
+## Examples
+
+```
+"Show my portfolio"
+"What's my total balance across all wallets?"
+"List my token holdings on BSC"
+"Show my portfolio breakdown by chain"
+"What's the value of my ETH across all networks?"
+```
+
+## Related
+
+- [Wallet Management](/blockchain/wallet) — Create and manage wallets
+- [Market Data](/blockchain/market-data) — Check current prices
+- [DeFi Dashboard](/blockchain/defi) — Monitor DeFi positions in detail

package/docs/blockchain/security.md

@@ -0,0 +1,83 @@
+---
+summary: "Transaction security architecture — confirmation gates, spending limits, and private key protection."
+title: "Transaction Security"
+---
+
+# Transaction Security
+
+CryptoClaw enforces multiple layers of security for all blockchain operations to protect user funds and private keys.
+
+## Confirmation gates
+
+State-changing operations require explicit user confirmation before execution. The tx-gate system intercepts these tool calls via a `before_tool_call` hook.
+
+**Operations requiring confirmation:**
+
+| Tool                     | Action                              |
+| ------------------------ | ----------------------------------- |
+| `transfer_native_token`  | Send native tokens (BNB, ETH, etc.) |
+| `transfer_erc20`         | Send ERC-20 tokens                  |
+| `approve_token_spending` | Approve token allowance             |
+| `transfer_nft`           | Transfer ERC-721 NFTs               |
+| `transfer_erc1155`       | Transfer ERC-1155 tokens            |
+| `write_contract`         | Execute arbitrary contract calls    |
+| `swap_execute`           | Execute token swaps                 |
+| `wallet_delete`          | Remove a wallet                     |
+| `agent_register`         | Register agent identity on-chain    |
+| `agent_set_wallet`       | Update agent's on-chain wallet      |
+
+When a confirmation is required, the agent presents a human-readable summary of the transaction (recipient, amount, token, network) and waits for your approval.
+
+## Spending limits
+
+Configure per-transaction and daily spending caps in `~/.cryptoclaw/cryptoclaw.json`:
+
+```json5
+{
+  blockchain: {
+    spendingLimits: {
+      perTransaction: 100, // Max USD per single transaction
+      daily: 1000, // Max USD per 24-hour period
+    },
+  },
+}
+```
+
+Transactions exceeding these limits are blocked with a warning.
+
+## Private key protection
+
+- **Encrypted storage**: AES-256-GCM with scrypt KDF (N=2^15, r=8, p=1)
+- **Keystore permissions**: File mode `0600` (owner-only access)
+- **Transcript redaction**: The `tool_result_persist` hook strips private keys from session transcripts
+- **Secret detection**: `containsPrivateKey()` and `sanitizeSecrets()` guard all tool outputs
+- **CLI-only operations**: `wallet_import` and `wallet_export` are restricted to the terminal
+
+## Sensitive parameter handling
+
+Parameters like `privateKey`, `passphrase`, and `mnemonic` are in the `SENSITIVE_PARAM_NAMES` list. These are:
+
+- Never logged
+- Never included in session history
+- Masked in any error messages
+
+## Architecture
+
+```mermaid
+flowchart TD
+    A["Agent tool call"] --> B{"tx-gate hook"}
+    B -->|Read-only| C["Execute immediately"]
+    B -->|State-changing| D["Format confirmation prompt"]
+    D --> E["User approval"]
+    E -->|Approved| F{"Check spending limits"}
+    F -->|Within limits| G["Execute transaction"]
+    F -->|Exceeds limits| H["Block with warning"]
+    E -->|Denied| I["Cancel operation"]
+```
+
+## Best practices
+
+- Set conservative spending limits initially and increase as needed
+- Use a dedicated wallet for agent operations rather than your main wallet
+- Review confirmation prompts carefully before approving
+- Use testnet chains (BSC Testnet, Sepolia) for experimentation

package/docs/blockchain/swap.md

@@ -0,0 +1,89 @@
+---
+summary: "Swap tokens on PancakeSwap and Uniswap with slippage protection and honeypot detection."
+title: "Token Swap"
+---
+
+# Token Swap
+
+CryptoClaw enables token swaps on major decentralized exchanges across multiple EVM chains.
+
+## Supported DEXs
+
+| DEX         | Versions | Chains                                      |
+| ----------- | -------- | ------------------------------------------- |
+| PancakeSwap | V2, V3   | BSC, Ethereum                               |
+| Uniswap     | V2, V3   | Ethereum, Polygon, Arbitrum, Optimism, Base |
+
+## Tools
+
+| Tool              | Description                                | Confirmation |
+| ----------------- | ------------------------------------------ | :----------: |
+| `swap_quote`      | Get a price quote for a token pair         |              |
+| `swap_execute`    | Execute a token swap                       |     Yes      |
+| `check_allowance` | Check token spending allowance             |              |
+| `get_dex_list`    | List supported DEXs for a chain            |              |
+| `get_token_info`  | Look up token details by address or symbol |              |
+
+## Swap flow
+
+<Steps>
+  <Step title="Get a quote">
+    Ask: "Quote swapping 1 BNB to USDT on PancakeSwap"
+
+    The agent fetches the best route, shows expected output, price impact, and fees.
+
+  </Step>
+  <Step title="Review and confirm">
+    The agent displays:
+    - Input/output amounts
+    - Exchange rate
+    - Price impact percentage
+    - Slippage tolerance
+    - Gas estimate
+
+    You must confirm before execution.
+
+  </Step>
+  <Step title="Execute">
+    The swap is submitted on-chain. The agent reports the transaction hash and final amounts.
+  </Step>
+</Steps>
+
+## Safety features
+
+- **Slippage protection** — Default 0.5% slippage tolerance, configurable per swap
+- **Price impact warnings** — Alerts when price impact exceeds 3%
+- **Honeypot detection** — Checks for tokens that cannot be sold
+- **Allowance management** — Automatic approval flow when needed
+- **Spending limits** — Respects configured per-transaction and daily USD caps
+
+<Warning>
+Always verify token contract addresses. The agent will warn about unverified tokens, but exercise caution with unfamiliar tokens.
+</Warning>
+
+## Examples
+
+```
+"Swap 0.5 BNB for USDT on PancakeSwap"
+"Get a quote for 100 USDC to ETH on Uniswap V3"
+"What DEXs are available on Polygon?"
+"Check my USDT allowance for PancakeSwap router"
+```
+
+## Configuration
+
+```json5
+{
+  blockchain: {
+    swap: {
+      defaultSlippage: 0.5, // Percentage
+      maxPriceImpact: 5, // Percentage threshold for warnings
+    },
+  },
+}
+```
+
+## Related
+
+- [DeFi Dashboard](/blockchain/defi) — Monitor LP and yield positions
+- [Market Data](/blockchain/market-data) — Check token prices before swapping