@portkey/eoa-agent-skills 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Portkey
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,191 @@
+# @portkey/eoa-agent-skills
+
+AI Agent Skills for Portkey EOA Wallet on [aelf blockchain](https://aelf.com). Provides MCP, CLI, and SDK interfaces for wallet management, token transfers, asset queries, and smart contract interactions.
+
+## Features
+
+- **Wallet Management**: Create, import, list, and backup EOA wallets with AES-encrypted local storage
+- **Token Queries**: Check balances, prices, and token lists across aelf chains
+- **NFT Queries**: Browse NFT collections and items
+- **Transaction History**: Query and inspect past transactions
+- **Token Transfers**: Same-chain and cross-chain transfers within aelf
+- **Contract Interactions**: Generic view/send calls, approve, fee estimation
+- **eBridge**: Cross-chain transfers between aelf and EVM chains
+
+## Consumption Modes
+
+| Mode | Entry | Use Case |
+|------|-------|----------|
+| **MCP** | `src/mcp/server.ts` | Claude Desktop, Cursor, GPT, and other AI tools |
+| **CLI** | `portkey_eoa_skill.ts` | Terminal scripts, OpenClaw |
+| **SDK** | `index.ts` | LangChain, LlamaIndex, custom agents |
+
+## Quick Start
+
+### Install
+
+```bash
+bun install
+```
+
+### One-Click Setup
+
+```bash
+# Claude Desktop
+bun run bin/setup.ts claude
+
+# Cursor (project-level)
+bun run bin/setup.ts cursor
+
+# Cursor (global)
+bun run bin/setup.ts cursor --global
+
+# OpenClaw (output config)
+bun run bin/setup.ts openclaw
+
+# OpenClaw (merge into existing config)
+bun run bin/setup.ts openclaw --config-path /path/to/openclaw-config.json
+
+# Check status
+bun run bin/setup.ts list
+```
+
+### Environment Variables
+
+```bash
+cp .env.example .env
+# Edit .env with your values
+```
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `PORTKEY_NETWORK` | `mainnet` | `mainnet` |
+| `PORTKEY_API_URL` | Override API base URL | Auto from network |
+| `PORTKEY_PRIVATE_KEY` | Plaintext private key (optional) | — |
+| `PORTKEY_WALLET_DIR` | Custom wallet storage directory | `~/.portkey-agent/wallets/` |
+| `PORTKEY_WALLET_PASSWORD` | Password for local wallet encryption | — |
+
+### MCP Server
+
+```bash
+bun run src/mcp/server.ts
+```
+
+Or add to your MCP client config (see `mcp-config.example.json`):
+
+```json
+{
+  "mcpServers": {
+    "portkey-eoa-agent-skills": {
+      "command": "bun",
+      "args": ["run", "/path/to/src/mcp/server.ts"],
+      "env": {
+        "PORTKEY_NETWORK": "mainnet",
+        "PORTKEY_WALLET_PASSWORD": "your_password"
+      }
+    }
+  }
+}
+```
+
+### CLI Usage
+
+```bash
+# Wallet
+bun run portkey_eoa_skill.ts wallet create --password mypass
+bun run portkey_eoa_skill.ts wallet list
+bun run portkey_eoa_skill.ts wallet import --mnemonic "word1 word2 ..." --password mypass
+
+# Queries
+bun run portkey_eoa_skill.ts query tokens --address YOUR_ADDRESS
+bun run portkey_eoa_skill.ts query balance --address YOUR_ADDRESS --symbol ELF --chain-id AELF
+bun run portkey_eoa_skill.ts query price --symbols ELF,USDT
+bun run portkey_eoa_skill.ts query history --address YOUR_ADDRESS
+bun run portkey_eoa_skill.ts query chains
+
+# Transfer
+bun run portkey_eoa_skill.ts transfer --to RECIPIENT --symbol ELF --amount 100000000 --chain-id AELF
+
+# Contract
+bun run portkey_eoa_skill.ts contract view --contract-address ADDR --method GetBalance --params '{"symbol":"ELF","owner":"..."}' --chain-id AELF
+```
+
+### SDK Usage
+
+```typescript
+import { getConfig, createWallet, getTokenList, transfer } from '@portkey/eoa-agent-skills';
+
+const config = getConfig('mainnet');
+
+// Create wallet
+const wallet = await createWallet(config, { password: 'mypass' });
+console.log('Address:', wallet.address);
+
+// Query tokens
+const tokens = await getTokenList(config, { address: wallet.address });
+console.log('Tokens:', tokens.data);
+
+// Transfer
+const result = await transfer(config, {
+  privateKey: 'YOUR_PRIVATE_KEY',
+  to: 'RECIPIENT_ADDRESS',
+  symbol: 'ELF',
+  amount: '100000000',
+  chainId: 'AELF',
+});
+console.log('TX:', result.transactionId);
+```
+
+## MCP Tools (20 total)
+
+### Wallet Management (5)
+- `portkey_create_wallet` — Create new wallet with encrypted local storage
+- `portkey_import_wallet` — Import from mnemonic or private key
+- `portkey_get_wallet_info` — View wallet public info
+- `portkey_list_wallets` — List all local wallets
+- `portkey_backup_wallet` — Export wallet credentials
+
+### Asset Queries (7)
+- `portkey_get_token_list` — Token portfolio with balances
+- `portkey_get_token_balance` — Single token balance
+- `portkey_get_token_prices` — Token USD prices
+- `portkey_get_nft_collections` — NFT collection list
+- `portkey_get_nft_items` — NFT items in collection
+- `portkey_get_transaction_history` — Transaction history
+- `portkey_get_transaction_detail` — Single transaction detail
+
+### Transfers (2)
+- `portkey_transfer` — Same-chain token transfer
+- `portkey_cross_chain_transfer` — Cross-chain aelf transfer
+
+### Contract (4)
+- `portkey_approve` — Token spending approval
+- `portkey_call_view_method` — Generic contract read
+- `portkey_call_send_method` — Generic contract write
+- `portkey_estimate_fee` — Transaction fee estimation
+
+### eBridge (2)
+- `portkey_ebridge_transfer` — eBridge cross-chain transfer
+- `portkey_ebridge_info` — eBridge limits and fees
+
+## Architecture
+
+```
+index.ts (SDK)  ─┐
+server.ts (MCP)  ─┼─> src/core/  ──> lib/
+skill.ts (CLI)   ─┘   (pure logic)    (infra)
+```
+
+Three adapters call the same core functions — zero duplicated logic.
+
+## Testing
+
+```bash
+bun test                    # All tests
+bun test tests/unit/        # Unit tests
+bun run tests/e2e/mcp-verify.ts  # MCP verification
+```
+
+## License
+
+MIT

package/README.zh-CN.md

@@ -0,0 +1,191 @@
+# @portkey/eoa-agent-skills
+
+[aelf 区块链](https://aelf.com) 上 Portkey EOA 钱包的 AI Agent Skills。提供 MCP、CLI 和 SDK 三种接口，覆盖钱包管理、Token 转账、资产查询和智能合约交互。
+
+## 功能
+
+- **钱包管理**：创建、导入、列表、备份 EOA 钱包，本地 AES 加密存储
+- **Token 查询**：查询余额、价格、Token 列表（跨链）
+- **NFT 查询**：浏览 NFT Collection 和具体 Item
+- **交易历史**：查询和检索历史交易
+- **Token 转账**：aelf 同链和跨链转账
+- **合约交互**：通用 view/send 调用、Approve、手续费预估
+- **eBridge**：aelf 与 EVM 链之间的跨链转账
+
+## 消费方式
+
+| 模式 | 入口 | 适用场景 |
+|------|------|---------|
+| **MCP** | `src/mcp/server.ts` | Claude Desktop、Cursor、GPT 等 AI 工具 |
+| **CLI** | `portkey_eoa_skill.ts` | 终端脚本、OpenClaw |
+| **SDK** | `index.ts` | LangChain、LlamaIndex、自定义 Agent |
+
+## 快速开始
+
+### 安装
+
+```bash
+bun install
+```
+
+### 一键配置
+
+```bash
+# Claude Desktop
+bun run bin/setup.ts claude
+
+# Cursor（项目级）
+bun run bin/setup.ts cursor
+
+# Cursor（全局）
+bun run bin/setup.ts cursor --global
+
+# OpenClaw（输出配置）
+bun run bin/setup.ts openclaw
+
+# OpenClaw（合并到已有配置文件）
+bun run bin/setup.ts openclaw --config-path /path/to/openclaw-config.json
+
+# 查看配置状态
+bun run bin/setup.ts list
+```
+
+### 环境变量
+
+```bash
+cp .env.example .env
+# 编辑 .env 填入你的配置
+```
+
+| 变量 | 说明 | 默认值 |
+|------|------|--------|
+| `PORTKEY_NETWORK` | `mainnet` | `mainnet` |
+| `PORTKEY_API_URL` | 覆盖 API 基础 URL | 根据网络自动选择 |
+| `PORTKEY_PRIVATE_KEY` | 明文私钥（可选） | — |
+| `PORTKEY_WALLET_DIR` | 自定义钱包存储目录 | `~/.portkey-agent/wallets/` |
+| `PORTKEY_WALLET_PASSWORD` | 本地钱包加密密码 | — |
+
+### MCP Server
+
+```bash
+bun run src/mcp/server.ts
+```
+
+或添加到你的 MCP 客户端配置（参见 `mcp-config.example.json`）：
+
+```json
+{
+  "mcpServers": {
+    "portkey-eoa-agent-skills": {
+      "command": "bun",
+      "args": ["run", "/path/to/src/mcp/server.ts"],
+      "env": {
+        "PORTKEY_NETWORK": "mainnet",
+        "PORTKEY_WALLET_PASSWORD": "your_password"
+      }
+    }
+  }
+}
+```
+
+### CLI 使用
+
+```bash
+# 钱包
+bun run portkey_eoa_skill.ts wallet create --password mypass
+bun run portkey_eoa_skill.ts wallet list
+bun run portkey_eoa_skill.ts wallet import --mnemonic "word1 word2 ..." --password mypass
+
+# 查询
+bun run portkey_eoa_skill.ts query tokens --address 你的地址
+bun run portkey_eoa_skill.ts query balance --address 你的地址 --symbol ELF --chain-id AELF
+bun run portkey_eoa_skill.ts query price --symbols ELF,USDT
+bun run portkey_eoa_skill.ts query history --address 你的地址
+bun run portkey_eoa_skill.ts query chains
+
+# 转账
+bun run portkey_eoa_skill.ts transfer --to 收款地址 --symbol ELF --amount 100000000 --chain-id AELF
+
+# 合约调用
+bun run portkey_eoa_skill.ts contract view --contract-address 合约地址 --method GetBalance --params '{"symbol":"ELF","owner":"..."}' --chain-id AELF
+```
+
+### SDK 使用
+
+```typescript
+import { getConfig, createWallet, getTokenList, transfer } from '@portkey/eoa-agent-skills';
+
+const config = getConfig('mainnet');
+
+// 创建钱包
+const wallet = await createWallet(config, { password: 'mypass' });
+console.log('地址:', wallet.address);
+
+// 查询 Token
+const tokens = await getTokenList(config, { address: wallet.address });
+console.log('Tokens:', tokens.data);
+
+// 转账
+const result = await transfer(config, {
+  privateKey: '你的私钥',
+  to: '收款地址',
+  symbol: 'ELF',
+  amount: '100000000',
+  chainId: 'AELF',
+});
+console.log('交易ID:', result.transactionId);
+```
+
+## MCP Tools（共 20 个）
+
+### 钱包管理（5）
+- `portkey_create_wallet` — 创建新钱包并加密存储
+- `portkey_import_wallet` — 导入钱包（助记词/私钥）
+- `portkey_get_wallet_info` — 查看钱包公开信息
+- `portkey_list_wallets` — 列出所有本地钱包
+- `portkey_backup_wallet` — 导出钱包凭证
+
+### 资产查询（7）
+- `portkey_get_token_list` — Token 列表和余额
+- `portkey_get_token_balance` — 单个 Token 余额
+- `portkey_get_token_prices` — Token USD 价格
+- `portkey_get_nft_collections` — NFT Collection 列表
+- `portkey_get_nft_items` — Collection 内的 NFT
+- `portkey_get_transaction_history` — 交易历史
+- `portkey_get_transaction_detail` — 单笔交易详情
+
+### 转账（2）
+- `portkey_transfer` — 同链 Token 转账
+- `portkey_cross_chain_transfer` — aelf 跨链转账
+
+### 合约（4）
+- `portkey_approve` — Token 授权
+- `portkey_call_view_method` — 通用合约只读调用
+- `portkey_call_send_method` — 通用合约写调用
+- `portkey_estimate_fee` — 交易手续费预估
+
+### eBridge（2）
+- `portkey_ebridge_transfer` — eBridge 跨链转账
+- `portkey_ebridge_info` — eBridge 限额和手续费
+
+## 架构
+
+```
+index.ts (SDK)  ─┐
+server.ts (MCP)  ─┼─> src/core/  ──> lib/
+skill.ts (CLI)   ─┘   (纯逻辑)      (基础设施)
+```
+
+三个适配器调用同一套 Core 函数——零重复逻辑。
+
+## 测试
+
+```bash
+bun test                    # 所有测试
+bun test tests/unit/        # 单元测试
+bun run tests/e2e/mcp-verify.ts  # MCP 验证
+```
+
+## License
+
+MIT

package/bin/platforms/claude.ts

@@ -0,0 +1,54 @@
+import {
+  getPlatformPaths,
+  readJsonFile,
+  writeJsonFile,
+  mergeMcpConfig,
+  removeMcpConfig,
+  generateMcpEntry,
+  SERVER_NAME,
+} from './utils.js';
+
+export function setupClaude(opts: {
+  configPath?: string;
+  serverPath?: string;
+  force?: boolean;
+}) {
+  const paths = getPlatformPaths();
+  const configPath = opts.configPath || paths.claude;
+  const existing = readJsonFile(configPath);
+  const entry = generateMcpEntry(opts.serverPath);
+  const { config, action } = mergeMcpConfig(
+    existing,
+    SERVER_NAME,
+    entry,
+    opts.force,
+  );
+
+  if (action === 'skipped') {
+    console.log(
+      `[SKIP] "${SERVER_NAME}" already exists in ${configPath}. Use --force to overwrite.`,
+    );
+    return;
+  }
+
+  writeJsonFile(configPath, config);
+  console.log(`[${action.toUpperCase()}] Claude Desktop config → ${configPath}`);
+  console.log(
+    '\nRemember to replace <YOUR_PRIVATE_KEY> and <YOUR_WALLET_PASSWORD> in the config.',
+  );
+}
+
+export function uninstallClaude(opts: { configPath?: string }) {
+  const paths = getPlatformPaths();
+  const configPath = opts.configPath || paths.claude;
+  const existing = readJsonFile(configPath);
+  const { config, removed } = removeMcpConfig(existing, SERVER_NAME);
+
+  if (!removed) {
+    console.log(`[SKIP] "${SERVER_NAME}" not found in ${configPath}`);
+    return;
+  }
+
+  writeJsonFile(configPath, config);
+  console.log(`[REMOVED] "${SERVER_NAME}" from ${configPath}`);
+}

package/bin/platforms/cursor.ts

@@ -0,0 +1,63 @@
+import {
+  getPlatformPaths,
+  readJsonFile,
+  writeJsonFile,
+  mergeMcpConfig,
+  removeMcpConfig,
+  generateMcpEntry,
+  SERVER_NAME,
+} from './utils.js';
+
+export function setupCursor(opts: {
+  global?: boolean;
+  configPath?: string;
+  serverPath?: string;
+  force?: boolean;
+}) {
+  const paths = getPlatformPaths();
+  const configPath =
+    opts.configPath || (opts.global ? paths.cursorGlobal : paths.cursorProject);
+  const existing = readJsonFile(configPath);
+  const entry = generateMcpEntry(opts.serverPath);
+  const { config, action } = mergeMcpConfig(
+    existing,
+    SERVER_NAME,
+    entry,
+    opts.force,
+  );
+
+  if (action === 'skipped') {
+    console.log(
+      `[SKIP] "${SERVER_NAME}" already exists in ${configPath}. Use --force to overwrite.`,
+    );
+    return;
+  }
+
+  writeJsonFile(configPath, config);
+  const scope = opts.global ? 'global' : 'project-level';
+  console.log(
+    `[${action.toUpperCase()}] Cursor ${scope} config → ${configPath}`,
+  );
+  console.log(
+    '\nRemember to replace <YOUR_PRIVATE_KEY> and <YOUR_WALLET_PASSWORD> in the config.',
+  );
+}
+
+export function uninstallCursor(opts: {
+  global?: boolean;
+  configPath?: string;
+}) {
+  const paths = getPlatformPaths();
+  const configPath =
+    opts.configPath || (opts.global ? paths.cursorGlobal : paths.cursorProject);
+  const existing = readJsonFile(configPath);
+  const { config, removed } = removeMcpConfig(existing, SERVER_NAME);
+
+  if (!removed) {
+    console.log(`[SKIP] "${SERVER_NAME}" not found in ${configPath}`);
+    return;
+  }
+
+  writeJsonFile(configPath, config);
+  console.log(`[REMOVED] "${SERVER_NAME}" from ${configPath}`);
+}

package/bin/platforms/openclaw.ts

@@ -0,0 +1,57 @@
+import * as path from 'path';
+import * as fs from 'fs';
+import {
+  getPackageRoot,
+  readJsonFile,
+  writeJsonFile,
+} from './utils.js';
+
+export function setupOpenclaw(opts: {
+  configPath?: string;
+  cwd?: string;
+  force?: boolean;
+}) {
+  const pkgRoot = getPackageRoot();
+  const openclawSrc = path.join(pkgRoot, 'openclaw.json');
+
+  if (!fs.existsSync(openclawSrc)) {
+    console.log('[ERROR] openclaw.json not found in package root');
+    return;
+  }
+
+  const openclawConfig = readJsonFile(openclawSrc);
+
+  // Replace cwd placeholder if specified
+  if (opts.cwd) {
+    if (openclawConfig.tools) {
+      for (const tool of openclawConfig.tools) {
+        if (tool.cwd) tool.cwd = opts.cwd;
+      }
+    }
+  }
+
+  if (opts.configPath) {
+    // Merge into existing config
+    const existing = readJsonFile(opts.configPath);
+    if (!existing.tools) existing.tools = [];
+
+    const existingNames = new Set(
+      existing.tools.map((t: any) => t.name),
+    );
+    let added = 0;
+    for (const tool of openclawConfig.tools || []) {
+      if (existingNames.has(tool.name) && !opts.force) continue;
+      existing.tools = existing.tools.filter(
+        (t: any) => t.name !== tool.name,
+      );
+      existing.tools.push(tool);
+      added++;
+    }
+
+    writeJsonFile(opts.configPath, existing);
+    console.log(`[DONE] Merged ${added} tools into ${opts.configPath}`);
+  } else {
+    // Just output the config
+    console.log(JSON.stringify(openclawConfig, null, 2));
+  }
+}