Matic Trades

本技能说明如何在 OpenClaw 中通过内置脚本调用 Matic Trades。请保持说明内容简洁：运行脚本，将用户输入作为 --prompt 参数传入，并返回清晰的摘要（若存在图像，则一并提供图像 URL）。

OpenClaw 如何使用该技能

• 技能由 Markdown 文档 + 可选文件 构成；当任务与描述匹配时，模型将遵循此文件执行。
• 优先使用 python3 "{baseDir}/scripts/matic.py" … 形式调用，确保请求行为与真实 API 保持一致（避免在对话中手动拼接 JSON）。
• 脚本输出 JSON 后，需为用户做自然语言总结；除非用户明确要求，否则不得直接输出原始 JSON。

相关文档：OpenClaw — 创建技能、技能加载。

配置

切勿打印或记录 API 密钥。

1) 工具箱 — AI_PICK（“使用 Matic 工具” 的默认模式）

API 行为说明： 向 POST /toolbox/execute 发送请求，携带 mode: AI_PICK。服务器仅依据 prompt 字段 自动判断应调用哪些工具（例如 chart_analysis、market_news、social_search），然后执行。在常规使用中，context 字段非必需，且不参与工具选择逻辑——所有关键信息（如股票代码、时间范围、用户具体需求等）必须明确写入 prompt 中。

最小化请求体（此格式正确）：

{ "mode": "AI_PICK", "prompt": "用户以自然语言表达的完整请求" }

执行命令：

python3 "{baseDir}/scripts/matic.py" toolbox --prompt "USER_TEXT_HERE"

示例（仅 prompt）：

• toolbox --prompt "今日异常期权活动及相关新闻"
• toolbox --prompt "NVDA 的图表与情绪分析——重点关注短期关键价位"
• toolbox --prompt "加密货币巨鲸动向及社交媒体上的主流观点"

除非你正在实现 Matic 官方 API 文档中明确记载的高级功能（例如 custom_handlers），否则不得为 AI_PICK 模式强制添加或自行构造 context 对象。对 ClawHub 用户而言，仅使用 prompt 是官方支持的标准路径。

2) 数据查询 — SMART_SEARCH（通过自然语言调用 Twelve Data）

API 行为说明： 向 POST /data/execute 发送请求，携带 mode: SMART_SEARCH。服务器将根据 prompt 自动映射至允许的 Twelve Data 接口及其参数。

执行命令：

python3 "{baseDir}/scripts/matic.py" data --prompt "USER_TEXT_HERE"

仅当用户明确提供了额外提示时，才可选用以下可选参数：--symbol AAPL、--interval 1day。但 SMART_SEARCH 模式仍以 prompt 为核心依据。

3) 智能图表代理 — 自主生成图表并完成分析

API 行为说明： 向 POST /agent/chart/autonomous 发送请求 —— 多步骤图表智能代理；可在 snapshots 字段中返回图像 URL 或 base64 编码数据。

执行命令：

python3 "{baseDir}/scripts/matic.py" chart --prompt "USER_TEXT_HERE" --images url

若客户端支持打开链接，请使用 --images url；若 UI 支持内联显示图像，则可选 b64 或 both。

可选参数：--max-actions N、--model MODEL（详见 references/api.md）。

何时使用哪个命令？

链式调用建议： 仅在明显提升效果时采用，例如先用 data 获取数值，再用 toolbox 进行综合解读，或用 chart 呈现可视化结果。避免重复调用相同能力。

响应处理

• 解析标准输出中的 JSON；用通俗语言解释 tool_runs / analysis / data 等字段含义。
• 若输出中包含 snapshots.pre_url、snapshots.post_url 或其它图像 URL，请直接将这些链接提供给用户。

错误处理

• 401 — 缺失或错误的 MATIC_API_KEY。
• 429 — 请求超频；请降低调用频率或检查当前套餐配额。
• 配额/账单相关提示 — 引导用户前往 Matic 仪表盘查看。

相关文件

• references/api.md — 请求与响应结构定义。
• README.md — 安装说明、ClawHub 上传流程、环境配置指南。

作用域限制

仅允许使用用户提供的 prompt 文本（必要时需对 shell 特殊字符进行清洗）调用 matic.py。HTTP 请求目标仅限于本脚本所使用的 MATIC_TRADES_API_BASE 下路径。禁止使用用户数据通过任意 curl 命令向其他主机发起请求。