Onchain CLI

# Onchain CLI

用于加密货币投资组合追踪、市场数据和 CEX（中心化交易所）历史的 CLI。

## 首次设置（必填）

在使用大多数功能之前，用户必须配置其 API 密钥：

```bash onchain setup ```

此交互式向导有助于配置： - **Coinbase/Binance** - 用于 CEX 余额和交易历史 - **DeBank** - 用于 EVM 钱包数据（Ethereum, Polygon, Arbitrum 等） - **Helius** - 用于 Solana 钱包数据

**未设置的情况**：仅 `onchain price` 和 `onchain markets` 可用（使用免费的 CoinGecko 层级）。

**验证设置**：运行 `onchain test` 以检查哪些提供程序已配置且正常工作。

**代理说明**：如果命令因“未配置”或“需要 API 密钥”而失败，请引导用户先运行 `onchain setup`，然后运行 `onchain test` 进行验证。

## 调用

``` onchain <command> ```

## 命令

### 市场数据

```bash onchain price <token> # Token price (btc, eth, sol, etc.) onchain markets # Market overview with trending onchain search <query> # Search tokens by name or symbol onchain gas # Current gas prices (Ethereum default) onchain gas --chain polygon # Gas prices for other EVM chains ```

### 钱包数据

```bash onchain balance [address] # Token balances (auto-detects EVM/Solana) onchain balance --chain polygon # Filter by chain onchain history [address] # Transaction history onchain portfolio [address] # Full portfolio with DeFi positions ```

### 交易查询

```bash onchain tx <hash> # Lookup transaction details (auto-detects chain) onchain tx <hash> --chain base # Specify chain explicitly onchain tx <explorer-url> # Paste block explorer URL directly ```

支持 EVM 链（Ethereum, Polygon, Base, Arbitrum, Optimism, BSC, Avalanche, Fantom）和 Solana。接受原始哈希或浏览器 URL（etherscan.io, basescan.org, solscan.io 等）。

#### 示例输出 ``` Transaction Details

✓ Status: SUCCESS Hash: 0xd757...5f31 Chain: Base Block: 41,310,593 Time: Jan 26, 2026, 01:55 PM (4h ago)

Addresses From: 0xc4e7263dd870a29f1cfe438d1a7db48547b16888 To: 0xab98b760e5ad88521a97c0f87a3f6eef8c42641d

Value & Fee Value: 0 ETH Fee: 3.62e-7 ETH Gas: 96,893 / 249,604 (39%)

Method ID: 0x6a761202

🔗 https://basescan.org/tx/0xd757... ```

**此输出包含所有可用的交易数据。** CLI 直接查询 Etherscan/Solscan API - 没有来自其他来源的额外数据。

### CEX 数据

```bash onchain coinbase balance # Coinbase balances onchain coinbase history # Coinbase trade history onchain binance balance # Binance balances onchain binance history # Binance trade history ```

### 预测市场

```bash onchain polymarket tags # List all available tags/categories onchain polymarket tags --popular # Show popular tags by market count onchain polymarket trending # Trending markets (respects config filters) onchain polymarket trending --all # Show all markets (ignore config filters) onchain polymarket trending --exclude sports,nfl # Exclude specific tags onchain polymarket trending --include crypto,ai # Only show specific tags onchain polymarket search <query> # Search markets (respects config filters) onchain polymarket view <slug> # View market details onchain polymarket sentiment <topic> # Analyze market sentiment for a topic ```

**情绪分析**：分析预测市场以确定看涨/看跌预期： ```bash onchain polymarket sentiment fed # Fed rate expectations onchain polymarket sentiment bitcoin # Bitcoin market sentiment onchain polymarket sentiment ai # AI-related predictions onchain polymarket sentiment trump # Political sentiment onchain polymarket sentiment fed --json # JSON output for agents ```

**标签过滤**：在 `~/.config/onchain/config.json5` 中配置默认排除项： ```json5 { "polymarket": { "excludeTags": ["sports", "nfl", "nba", "mlb"], "includeTags": [] // empty = all non-excluded } } ```

### 配置

```bash onchain setup # Interactive setup wizard onchain config # View current config onchain config wallet add <name> <address> onchain config wallet set-default <name> ```

## 全局选项

- `--json` - 以 JSON 格式输出（适合代理） - `--plain` - 禁用颜色和表情符号 - `--timeout <ms>` - 请求超时

## 配置

配置文件：`~/.config/onchain/config.json5`

### 必需的 API 密钥

| 功能 | API 密钥 | 获取密钥 | |---------|---------|---------| | EVM 钱包 | `DEBANK_API_KEY` | [DeBank](https://cloud.debank.com/) | | Solana 钱包 | `HELIUS_API_KEY` | [Helius](https://helius.xyz/) | | Coinbase CEX | `COINBASE_API_KEY` + `COINBASE_API_SECRET` | [Coinbase](https://www.coinbase.com/settings/api) | | Binance CEX | `BINANCE_API_KEY` + `BINANCE_API_SECRET` | [Binance](https://www.binance.com/en/my/settings/api-management) |

### 可选的 API 密钥

| 功能 | API 密钥 | 备注 | |---------|---------|-------| | 市场数据 | `COINGECKO_API_KEY` | 免费层级可用，Pro 版拥有更高限制 | | 市场回退 | `COINMARKETCAP_API_KEY` | 备用市场数据源 | | EVM 交易查询 | `ETHERSCAN_API_KEY` | 用于 EVM 链上的 `onchain tx` | | Solana 交易查询 | `SOLSCAN_API_KEY` | 用于 Solana 上的 `onchain tx` |

## 示例

### 获取比特币价格 ```bash onchain price btc ```

### 检查钱包余额 ```bash onchain balance 0x1234...5678 ```

### 查看包含 DeFi 仓位的投资组合 ```bash onchain portfolio main # Uses saved wallet named "main" ```

### 获取热门预测市场 ```bash onchain polymarket trending -n 5 # Top 5 (respects config filters) onchain polymarket trending --all # All markets, ignore config onchain polymarket trending --exclude sports # Filter out sports on-the-fly ```

### 查询一笔交易 ```bash onchain tx 0xd757e7e4cdb424e22319cbf63bbcfcd4b26c93ebef31d1458ab7d5e986375f31 onchain tx https://basescan.org/tx/0x... # Or paste explorer URL ```

### 搜索代币 ```bash onchain search pepe # Find tokens matching "pepe" onchain search "shiba inu" -l 5 # Limit to 5 results ```

### 检查 Gas 价格 ```bash onchain gas # Ethereum gas prices onchain gas --chain polygon # Polygon gas prices onchain gas --json # JSON output ```

### 用于脚本的 JSON 输出 ```bash onchain --json price eth | jq '.priceUsd' ```

## 支持的链

### EVM（通过 DeBank） Ethereum, BNB Chain, Polygon, Arbitrum, Optimism, Avalanche, Base, zkSync Era, Linea, Scroll, Blast, Mantle, Gnosis, Fantom, Celo 等。

### Solana（通过 Helius） 完整的 Solana 主网支持，包括 SPL 代币和 NFT。

## 代理集成

此 CLI 专为代理使用而设计。主要模式：

1. **始终使用 `--json`** 以便进行程序化访问 2. **检查退出代码** - 0 表示成功，1 表示错误 3. **使用已保存的钱包** - 使用 `onchain setup` 配置一次，按名称引用 4. **速率限制** - API 具有速率限制，在快速调用之间添加延迟

### 代理使用示例

```bash # Get portfolio value VALUE=$(onchain --json portfolio main | jq -r '.totalValueUsd')

# Get price with change onchain --json price btc | jq '{price: .priceUsd, change24h: .priceChange24h}'

# Check if market is bullish CHANGE=$(onchain --json markets | jq '.marketCapChange24h')

# Get transaction details as JSON TX=$(onchain --json tx 0x... --chain base) echo $TX | jq '{status: .status, from: .from, to: .to, method: .methodId}' ```

### 交易查询指南

**重要：信任 CLI 输出。** `onchain tx` 命令直接查询 Etherscan (EVM) 或 Solscan (Solana) API 并返回所有可用数据。

**不要：** - 使用 curl 直接访问 Etherscan/Basescan API - 使用 `cast` 或其他 CLI 工具作为“回退” - 使用 WebFetch 抓取区块浏览器网站 - 假设 CLI 缺少数据 - 它返回所有可用数据

**要：** - 使用 `onchain tx <hash>` 或 `onchain tx <explorer-url>` - 使用 `--json` 进行结构化数据解析 - 直接解释输出以回答用户问题

**解释示例：** ```bash onchain tx 0x... --chain base ``` 如果输出显示 `Status: SUCCESS`、`From: 0x...`、`To: 0x...`、`Method ID: 0x6a761202` - 那就是一次成功的合约交互。方法 ID `0x6a761202` 是 `execTransaction`（Gnosis Safe）。无需额外查询。