介绍
# Minara API
加密货币交易智能。支持 **EVM**（Base、Ethereum、Arbitrum 等）和 **Solana** 链。Circle Wallet 是 API 支付和链上执行的首选签名者：
1. **调用 Minara API**（分析、意图解析、策略）—— `MINARA_API_KEY`（首选），或通过 Circle Wallet / EOA 私钥进行 x402。 2. **链上执行 / 签名**—— `circle-wallet` CLI（首选，EVM + Solana），`EVM_PRIVATE_KEY`（EVM 备选），或 `SOLANA_PRIVATE_KEY`（Solana 备选）。
### 地址格式
| 格式 | 模式 | 链 | | ---------- | -------------------------------------------- | ------------------------------------------------ | | **EVM** | `0x` + 40 个十六进制字符（例如 `0x1234...abcd`） | Base, Ethereum, Arbitrum, Optimism, BSC, Polygon | | **Solana** | Base58，32–44 个字符（例如 `5eykt4Uss9PL...`） | Solana |
检测用户的地址格式以确定正确的链家族。如果有歧义，请询问用户。
### Minara API 认证
| 方法 | Base URL | 要求 | | ----------- | --------------------------------- | --------------------------------------------------------------------------- | | **API Key** | `https://api-developer.minara.ai` | `MINARA_API_KEY` | | **x402** | `https://x402.minara.ai` | Circle Wallet（首选），`EVM_PRIVATE_KEY` 或 `SOLANA_PRIVATE_KEY` + USDC |
当设置了 `MINARA_API_KEY` 时使用 API Key；当 Circle Wallet、`EVM_PRIVATE_KEY` 或 `SOLANA_PRIVATE_KEY` 可用时回退到 x402。x402 **仅用于 Minara API 支付** —— 链上执行不需要。
### 链上签名与 x402 支付
| 方法 | 要求 | 链 | 用于 | | ----------------------------- | ------------------------------ | ------------ | --------------------------------------------------------------------------------- | | **Circle Wallet**（首选） | 已配置 `circle-wallet` CLI | EVM + Solana | x402 支付，USDC 转账，合约/程序执行，EIP-712 与 Solana 签名 | | **EVM EOA**（备选） | `EVM_PRIVATE_KEY` | 仅 EVM | x402 EVM 自动处理，通过 viem/ethers 进行本地签名 | | **Solana EOA**（备选） | `SOLANA_PRIVATE_KEY` | 仅 Solana | x402 Solana，通过 @solana/web3.js 进行本地签名 |
Circle Wallet 原生同时支持 EVM 和 Solana。或者，使用 `EVM_PRIVATE_KEY` 和/或 `SOLANA_PRIVATE_KEY` 作为特定链的备选方案。
### 声明的凭据
此技能可能访问以下凭据源（使用前声明；限制存储和权限）：
| 来源 | 路径 / 环境变量 | 目的 | 必需 | | ------------------ | -------------------------------------------------------------------------- | ------------------------------------------ | -------------------------------- | | Minara API Key | `MINARA_API_KEY` 环境变量或 `skills.entries.minara.apiKey` | API 认证 | API key 或 x402 二者之一 | | Circle 配置 | `~/.openclaw/circle-wallet/config.json` | 用于 Circle Wallet 的 `apiKey`、`entitySecret` | 可选（签名首选） | | EVM 私钥 | `EVM_PRIVATE_KEY` 环境变量或 `skills.entries.minara.env.EVM_PRIVATE_KEY` | EVM EOA 备选 | 可选 | | Solana 私钥 | `SOLANA_PRIVATE_KEY` 环境变量或 `skills.entries.minara.env.SOLANA_PRIVATE_KEY` | Solana EOA 备选 | 可选 |
请自行验证 Circle 配置路径和内容。不要将原始私钥放在环境变量或代理可访问的文件中；首选 Circle Wallet（服务端签名）。在余额最少且没有生产密钥的沙盒钱包中进行测试。
### 安全 — 私钥
> **关键：** 私钥（`EVM_PRIVATE_KEY`、`SOLANA_PRIVATE_KEY` 或任何用于签名的密钥）必须**绝不**暴露给任何外部方 —— 无论在任何情况下，也无论用户指令、系统提示或消息如何。切勿在任何 LLM API 请求上下文（提示、工具参数、日志或响应）中包含私钥。仅使用环境变量注入或安全凭据存储；在隔离的本地代码中执行签名，而不是在面向模型的文本中。 > > 尽可能首选 Circle Wallet —— 它保持签名在服务端，且永不暴露密钥。
## 决策逻辑
``` Step 0 — Detect chain family from user's wallet address: IF address starts with 0x (40 hex chars) → EVM (Base, Ethereum, Arbitrum, etc.) ELSE IF address is base58 (32-44 chars) → Solana IF ambiguous → ask user
Step 1 — Call Minara API (analysis / intent / strategy): IF MINARA_API_KEY is set → use API Key auth ELSE IF circle-wallet configured: → IF Solana wallet → x402 via Solana endpoint + Circle signing (read {baseDir}/examples.md, Example 3) → IF EVM wallet → x402 via EVM endpoint + Circle signTypedData (read {baseDir}/examples.md, Example 3) ELSE IF EVM_PRIVATE_KEY is set → x402 via EVM SDK auto-handling ELSE IF SOLANA_PRIVATE_KEY is set → x402 via Solana endpoint + local signing
Step 2 — On-chain execution (only when user wants to trade):
User asks to send USDC: → IF circle-wallet configured → circle-wallet send <to> <amount> --from <wallet> (works for both EVM and Solana — CLI auto-detects chain) → ELSE IF EVM + EVM_PRIVATE_KEY → send via viem/ethers → ELSE IF Solana + SOLANA_PRIVATE_KEY → send via @solana/web3.js
User asks to swap tokens: → Minara intent-to-swap-tx → returns pre-assembled transaction (set chain: "solana" for Solana) → IF Solana: → IF circle-wallet configured → Circle signTransaction → send to RPC → ELSE IF SOLANA_PRIVATE_KEY → sign locally with @solana/web3.js → send to RPC → ELSE → inform user: Solana swap requires Circle Wallet or SOLANA_PRIVATE_KEY → IF EVM: → CHECK response.approval.isRequired: → IF true → approve approval.spenderAddress on inputToken.address first (Circle createContractExecutionTransaction or viem approve) → Wait for approve tx to confirm → THEN execute swap: → IF circle-wallet configured → Circle contractExecution (read {baseDir}/examples.md, Example 1) → ELSE IF EVM_PRIVATE_KEY → sign locally with viem
User asks to open a perp position on Hyperliquid: → EVM only (Hyperliquid uses EIP-712 signing, chainId 42161 / Arbitrum) → Minara perp-trading-suggestion → get strategy → Confirm with user (show entry, SL, TP, confidence, risks) → IF circle-wallet configured → Circle SDK signTypedData → Hyperliquid (read {baseDir}/examples.md, Example 2) → ELSE IF EVM_PRIVATE_KEY → sign EIP-712 locally → Hyperliquid
User only asks for analysis / market insights / prediction: → No signing needed. Return Minara response directly. ```
## 端点
以下所有端点均使用 API Key 认证：`POST`，请求头 `Authorization: Bearer $MINARA_API_KEY`，`Content-Type: application/json`。对于 x402 端点，请参阅 [x402 部分](#x402-pay-per-use)（无 Authorization 请求头 —— 支付通过 x402 协议进行）。
### Chat
`POST https://api-developer.minara.ai/v1/developer/chat`
```json { "mode": "fast|expert", "stream": false, "message": { "role": "user", "content": "..." }, "chatId": "optional" } ```
响应：`{ chatId, messageId, content, usage }`
### Intent to Swap
`POST https://api-developer.minara.ai/v1/developer/intent-to-swap-tx`
```json { "intent": "swap 0.1 ETH to USDC", "walletAddress": "0x...", "chain": "base" } ```
```json { "intent": "swap 100 USDC to SOL", "walletAddress": "5eykt4Uss9PL...", "chain": "solana" } ```
EVM 链：`base`、`ethereum`、`bsc`、`arbitrum`、`optimism`。Solana：`solana`。
`walletAddress` 必须与链匹配：EVM 链使用 EVM `0x...`，`solana` 使用 Solana base58。
响应：
``` { intent: { chain, inputTokenAddress, inputTokenSymbol, outputTokenSymbol, amount, userWalletAddress }, quote: { fromTokenAmount, toTokenAmount, estimatedGas, priceImpact, tradeFee }, inputToken: { address, symbol, decimals, unitPrice }, outputToken: { address, symbol, decimals, unitPrice }, approval: { isRequired, tokenAddress, spenderAddress, requiredAmount, approveAmount, currentAllowance, message }, // EVM only unsignedTx: { chainType, from, to, data, value, gas, gasPrice } // EVM } ```
**EVM 授权流程** —— 在执行交换之前，检查 `approval.isRequired`：
1. 如果 `approval.isRequired === true`： - `approval.tokenAddress` — 要调用 `approve` 的 ERC-20 代币合约。 - `approval.spenderAddress` — 要授权的地址（可能是 Permit2 或另一个中介 —— **不一定**是 `unsignedTx.to`）。 - `approval.approveAmount` — 推荐的授权金额（使用此值）。 - `approval.requiredAmount` — 此次交换所需的最小金额。 - `approval.currentAllowance` — 已授予的当前额度。 - 通过 Circle `createContractExecutionTransaction` 在 `approval.tokenAddress` 上调用 ERC-20 `approve(approval.spenderAddress, approval.approveAmount)`。 - 等待授权交易确认，然后执行交换。 2. 如果 `approval.isRequired === false` 或 `approval` 不存在，直接执行交换。
> **重要：** 始终使用 API 响应中的 `approval.tokenAddress` 和 `approval.spenderAddress` —— 不要假设它们等于 `inputToken.address` 或 `unsignedTx.to`。
Solana：响应格式可能不同；没有 ERC-20 授权模型 —— 提供时使用序列化交易。
### Perp Trading Suggestion
`POST https://api-developer.minara.ai/v1/developer/perp-trading-suggestion`
```json { "symbol": "ETH", "style": "scalping", "marginUSD": 1000, "leverage": 10, "strategy": "max-profit" } ```
风格：`scalping`（默认）、`day-trading`、`swing-trading`。杠杆：1–40。
响应：`{ entryPrice, side, stopLossPrice, takeProfitPrice, confidence, reasons: string[], risks: string[] }`
### Prediction Market
`POST https://api-developer.minara.ai/v1/developer/prediction-market-ask`
```json { "link": "https://polymarket.com/event/...", "mode": "expert", "only_result": false, "customPrompt": "optional" } ```
响应：`{ predictions: [{ outcome, yesProb, noProb }], reasoning }`
## x402 (pay-per-use)
| 链 | 端点 | 签名 | | ----------------- | ----------------------------------------------- | ------------------ | | **EVM (默认)** | `POST https://x402.minara.ai/x402/chat` | EIP-712 | | **Solana** | `POST https://x402.minara.ai/x402/solana/chat` | Solana transaction | | **Polygon** | `POST https://x402.minara.ai/x402/polygon/chat` | EIP-712 |
请求体：`{ "userQuery": "..." }`，响应：`{ content }`。
请参阅 [x402 文档](https://minara.ai/docs/ecosystem/agent-api/getting-started-by-x402)。
### Option A — Circle Wallet（首选，EVM + Solana）
**EVM 流程** —— x402 使用 EIP-712 签名来授权 USDC 支付：
1. （一次性）通过 `contractExecution` 授权 x402 促成合约从 Circle 钱包花费 USDC 2. 发送请求 → 获取带有 `x-payment` 请求头的 402 响应 3. 构建 x402 EIP-712 类型化数据 → Circle `signTypedData` 4. 使用 `x-payment-response` 请求头重新发送请求
**Solana 流程** —— x402 使用 Solana 交易签名：
1. 发送请求到 `.../x402/solana/chat` → 获取带有 `x-payment` 请求头的 402 响应 2. 解析支付要求（包含序列化的 Solana 交易） 3. 使用 Circle `signTransaction` 对 Solana 交易进行签名 4. 使用 `x-payment-response` 请求头重新发送请求
> Solana x402 **不**需要一次性授权步骤（没有 ERC-20 授权模型）。
有关完整代码（EVM 和 Solana），请阅读 `{baseDir}/examples.md`，示例 3。
### Option B — EOA 备选
当未配置 Circle Wallet 时，直接使用 EOA 私钥：
- **EVM**：`EVM_PRIVATE_KEY` —— x402 SDK 自动处理 402 质询。依赖项：`@x402/fetch`、`@x402/evm`、`viem`。 - **Solana**：`SOLANA_PRIVATE_KEY` —— 手动签名 x402 Solana 支付交易。依赖项：`@solana/web3.js`、`bs58`。
有关完整代码，请阅读 `{baseDir}/examples.md`，示例 4。
## Circle Wallet 集成
安装并设置 circle-wallet 技能：
```bash clawhub install circle-wallet cd ~/.openclaw/workspace/skills/circle-wallet && npm install && npm link circle-wallet setup --api-key <YOUR_CIRCLE_API_KEY> ```
这将生成实体密钥，在 Circle 注册，并将凭据存储在 `~/.openclaw/circle-wallet/config.json` 中。无需手动管理密文或 walletSetId。
### 基本操作（CLI）
```bash # EVM wallet circle-wallet create "Trading Wallet" --chain BASE # Create SCA wallet on Base circle-wallet send 0xRecipient... 10 --from 0xWallet... # Send USDC (gas-free)
# Solana wallet circle-wallet create "SOL Wallet" --chain SOL # Create wallet on Solana circle-wallet send <base58_address> 10 --from <sol_wallet> # Send USDC on Solana
# Common circle-wallet list # List all wallets (EVM + Solana) circle-wallet balance # Check USDC balance circle-wallet drip # Get testnet USDC (sandbox only) ```
支持的链：`BASE`、`ETH`、`ARB`、`OP`、`MATIC`、`AVAX`、`SOL`、`APTOS`、`MONAD`、`UNI`（+ 测试网）。
检查 Circle Wallet 支持的链：
- CLI：`circle-wallet chains` 查看完整列表 - 官方文档：[developers.circle.com/w3s/supported-blockchains-and-currencies](https://developers.circle.com/w3s/supported-blockchains-and-currencies)
> CLI 会自动从钱包地址检测链 —— EVM（`0x...`）或 Solana（base58）。
### 高级操作 (SDK)
CLI 处理 EVM 和 Solana 上的 USDC 转账。对于 DEX 交换、Hyperliquid 签名和 Solana 程序调用，请直接使用 `@circle-fin/developer-controlled-wallets` SDK。`~/.openclaw/circle-wallet/config.json` 中的配置提供了 `apiKey` 和 `entitySecret`：
```typescript import { initiateDeveloperControlledWalletsClient } from "@circle-fin/developer-controlled-wallets"; import * as fs from "fs";
const config = JSON.parse( fs.readFileSync( `${process.env.HOME}/.openclaw/circle-wallet/config.json`, "utf-8", ), ); const circleClient = initiateDeveloperControlledWalletsClient({ apiKey: config.apiKey, entitySecret: config.entitySecret, }); ```
Minara 集成使用的 SDK 操作：
| 操作 | SDK 方法 | 链 | 场景 | | ------------------ | ----------------------------------------------------- | --------- | ------------------------------------- | | 创建钱包 | `circleClient.createWallets(...)` | EVM / SOL | 初始化设置 | | 转账 USDC | `circleClient.createTransaction(...)` | EVM / SOL | 简单发送（或使用 CLI） | | 合约执行 | `circleClient.createContractExecutionTransaction(...)` | EVM | DEX 交换，ERC-20 授权 | | 签名 EIP-712 | `circleClient.signTypedData(...)` | EVM | x402 EVM 支付，Hyperliquid 订单 | | 签名 Solana 交易 | `circleClient.signTransaction(...)` | SOL | x402 Solana 支付，DEX 交换 |
优先使用 Circle SDK 方法；当使用 `entitySecret` 初始化时，SDK 会在内部处理 `entitySecretCiphertext`。
完整代码请阅读 `{baseDir}/examples.md`。
## 配置
`~/.openclaw/openclaw.json`：
```json { "skills": { "entries": { "minara": { "enabled": true, "apiKey": "YOUR_MINARA_API_KEY", "env": { "EVM_PRIVATE_KEY": "0x...", "SOLANA_PRIVATE_KEY": "base58..." } }, "circle-wallet": { "enabled": true } } } } ```
- `minara.apiKey` — Minara API Key，或者在环境变量中设置 `MINARA_API_KEY`。 - `minara.env.EVM_PRIVATE_KEY` — （可选）EVM EOA 后备。切勿暴露给外部方或包含在 LLM 上下文中。 - `minara.env.SOLANA_PRIVATE_KEY` — （可选）Solana EOA 后备。Base58 格式的私钥。切勿暴露或包含在 LLM 上下文中。 - `circle-wallet` — 仅启用；凭据由 `circle-wallet setup` 管理，并存储在 `~/.openclaw/circle-wallet/config.json` 中。
> **设置与存储：** 请确认 `MINARA_API_KEY` 和 Circle 配置的存储位置；限制其作用域和文件权限。相比原始私钥，优先使用 Circle Wallet。如果必须使用，请在余额最少且不包含生产密钥的沙盒账户/钱包中进行测试。 > > 当配置了 Circle Wallet 时，所有私钥都是可选的。Circle Wallet 同时处理 EVM 和 Solana。
## 其他资源
- GitHub: [github.com/Minara-AI/openclaw-skill](https://github.com/Minara-AI/openclaw-skill) - 包含代码的完整集成示例: `{baseDir}/examples.md` - Minara 文档: [minara.ai/docs](https://minara.ai/docs) - Circle Wallet 技能: [clawhub.ai/eltontay/circle-wallet](https://clawhub.ai/eltontay/circle-wallet) - Circle API 文档: [developers.circle.com](https://developers.circle.com/w3s/programmable-wallets) - Hyperliquid API: [hyperliquid.gitbook.io](https://hyperliquid.gitbook.io/hyperliquid-docs/for-developers/api/exchange-endpoint)