介绍
# Maxxit Lazy Trading
通过 Maxxit 的 Lazy Trading API 在 Ostium 协议上执行永续合约交易。此技能支持通过程序化端点进行自动交易，包括开仓/平仓以及风险管理。
## 何时使用此技能
- 用户希望在 Ostium 上执行交易 - 用户询问其懒人交易账户详情 - 用户希望检查其 USDC/ETH 余额 - 用户希望查看其未平仓位或投资组合 - 用户希望查看其平仓历史或盈亏 (PnL) - 用户希望发现可用的交易标的 - 用户希望获取市场数据或 LunarCrush 指标进行分析 - 用户希望获取用于交易目的的全市场快照 - 用户希望比较不同代币的山寨币排名 (AltRank) - 用户希望识别高情绪的交易机会 - 用户希望了解加密资产的社会交易量趋势 - 用户希望开设新的交易仓位 (做多/做空) - 用户希望平掉现有仓位 - 用户希望设置或修改止盈水平 - 用户希望设置或修改止损水平 - 用户希望获取当前代币/市场价格 - 用户提到“lazy trade”、“perps”、“perpetuals”或“futures trading” - 用户希望自动化其交易工作流 - 用户希望跟单交易或镜像另一位交易员的仓位 - 用户希望发现其他 OpenClaw 代理以供学习 - 用户希望查看表现优异的交易员正在进行哪些交易 - 用户希望寻找高影响力的交易员进行复制
---
## ⚠️ 关键：API 参数规则（调用任何端点前请阅读）
> **切勿假设、猜测或臆造 API 请求参数的值。** 每个必需参数必须来自先前的 API 响应或显式的用户输入。如果您没有必需的值，您必须首先从相应的依赖端点获取它。
### 参数依赖关系图
以下显示了每个必需参数的来源。**在调用端点之前，请务必解析依赖关系。**
| 参数 | 来源 | 获取端点 | |-----------|--------|------------------------| | `userAddress` / `address` | `/club-details` 响应 → `user_wallet` | `GET /club-details` | | `agentAddress` | `/club-details` 响应 → `ostium_agent_address` | `GET /club-details` | | `tradeIndex` | `/open-position` 响应 → `actualTradeIndex` **或** `/positions` 响应 → `tradeIndex` | `POST /open-position` 或 `POST /positions` | | `pairIndex` | `/positions` 响应 → `pairIndex` **或** `/symbols` 响应 → symbol `id` | `POST /positions` 或 `GET /symbols` | | `entryPrice` | `/open-position` 响应 → `entryPrice` **或** `/positions` 响应 → `entryPrice` | `POST /open-position` 或 `POST /positions` | | `market` / `symbol` | 用户指定代币 **或** `/symbols` 响应 → `symbol` (例如 `ETH/USD`) | 用户输入或 `GET /symbols` | | `side` | 用户指定 `"long"` 或 `"short"` | 用户输入 (必需) | | `collateral` | 用户指定 USDC 数量 | 用户输入 (必需) | | `leverage` | 用户指定倍数 | 用户输入 (必需) | | `takeProfitPercent` | 用户指定 (例如，0.30 = 30%) | 用户输入 (必需) | | `stopLossPercent` | 用户指定 (例如，0.10 = 10%) | 用户输入 (必需) | | `address` (用于 copy-trader-trades) | `/copy-traders` 响应 → `creatorWallet` 或 `walletAddress` | `GET /copy-traders` |
### 强制工作流规则
1. **首先始终调用 `/club-details`** 以获取 `user_wallet` (用作 `userAddress`/`address`) 和 `ostium_agent_address` (用作 `agentAddress`)。在会话期间缓存这些值——它们不会改变。 2. **切勿硬编码或猜测钱包地址。** 它们对每个用户都是唯一的，必须来自 `/club-details`。 3. **对于开仓：** 首先获取市场数据 (通过 `/lunarcrush` 或 `/market-data`)，将其展示给用户，获取显式确认以及交易参数 (保证金、杠杆、方向、TP、SL)，然后执行。 - **市场格式规则 (Ostium)：** `/symbols` 返回像 `ETH/USD` 这样的交易对，但 `/open-position` 期望 `market` 仅为基础代币 (例如 `ETH`)。通过取 `/` 之前的基础代币进行转换。 4. **对于开仓后设置 TP/SL：** 使用来自 `/open-position` 响应的 `actualTradeIndex`。如果您没有它 (例如，仓位是之前开设的)，请调用 `/positions` 来获取 `tradeIndex`、`pairIndex` 和 `entryPrice`。 5. **对于平仓：** 您需要 `tradeIndex` —— 始终先调用 `/positions` 来查找用户指定市场/仓位的正确索引。 6. **询问用户交易参数** —— 切勿假设保证金金额、杠杆、TP% 或 SL%。展示默认值但让用户确认或覆盖。 7. **通过调用 `/symbols` 验证市场是否存在**，如果您不确定代币在 Ostium 上是否可用。
### 预检清单 (每次 API 调用前在脑海中运行)
``` ✅ Do I have the user's wallet address? → If not, call /club-details ✅ Do I have the agent address? → If not, call /club-details ✅ Does this endpoint need a tradeIndex? → If not in hand, call /positions ✅ Does this endpoint need entryPrice/pairIndex? → If not in hand, call /positions ✅ Did I ask the user for all trade parameters? → collateral, leverage, side, TP%, SL% ✅ Is the market/symbol valid? → If unsure, call /symbols to verify ```
---
## 身份验证
所有请求都需要带有前缀 `lt_` 的 API 密钥。通过以下方式传递： - Header: `X-API-KEY: lt_your_api_key` - 或: `Authorization: Bearer lt_your_api_key`
## API 端点
## Ostium 程序化端点 (`/api/lazy-trading/programmatic/*`)
> `/api/lazy-trading/programmatic/*` 下的所有端点均用于 **Ostium**，除非明确带有 `/aster/` 前缀。
### 获取账户详情
检索懒人交易账户信息，包括代理状态、Telegram 连接和交易偏好。
```bash curl -L -X GET "${MAXXIT_API_URL}/api/lazy-trading/programmatic/club-details" \ -H "X-API-KEY: ${MAXXIT_API_KEY}" ```
**响应：** ```json { "success": true, "user_wallet": "0x...", "agent": { "id": "agent-uuid", "name": "Lazy Trader - Username", "venue": "ostium", "status": "active" }, "telegram_user": { "id": 123, "telegram_user_id": "123456789", "telegram_username": "trader" }, "deployment": { "id": "deployment-uuid", "status": "active", "enabled_venues": ["ostium"] }, "trading_preferences": { "risk_tolerance": "medium", "trade_frequency": "moderate" }, "ostium_agent_address": "0x...", "aster_configured": "true", } ```
### 获取可用标的
从 Ostium 交易所检索所有可用的交易标的。使用此功能来发现您可以交易哪些标的并获取 LunarCrush 数据。
```bash curl -L -X GET "${MAXXIT_API_URL}/api/lazy-trading/programmatic/symbols" \ -H "X-API-KEY: ${MAXXIT_API_KEY}" ```
**响应：** ```json { "success": true, "symbols": [ { "id": 0, "symbol": "BTC/USD", "group": "crypto", "maxLeverage": 150 }, { "id": 1, "symbol": "ETH/USD", "group": "crypto", "maxLeverage": 100 } ], "groupedSymbols": { "crypto": [ { "id": 0, "symbol": "BTC/USD", "group": "crypto", "maxLeverage": 150 }, { "id": 1, "symbol": "ETH/USD", "group": "crypto", "maxLeverage": 100 } ], "forex": [...] }, "count": 45 } ```
### 获取 LunarCrush 市场数据
检索特定标的的缓存 LunarCrush 市场指标。此数据包括社会情绪、价格变化、波动性和市场排名。
> **⚠️ 依赖项**：您必须先调用 `/symbols` 端点以获取确切的标的字符串 (例如 `"BTC/USD"`)。标的需要精确匹配。
```bash # First, get available symbols SYMBOL=$(curl -s -L -X GET "${MAXXIT_API_URL}/api/lazy-trading/programmatic/symbols" \ -H "X-API-KEY: ${MAXXIT_API_KEY}" | jq -r '.symbols[0].symbol')
# Then, get LunarCrush data for that symbol curl -L -X GET "${MAXXIT_API_URL}/api/lazy-trading/programmatic/lunarcrush?symbol=${SYMBOL}" \ -H "X-API-KEY: ${MAXXIT_API_KEY}" ```
**响应：** ```json { "success": true, "symbol": "BTC/USD", "lunarcrush": { "galaxy_score": 72.5, "alt_rank": 1, "social_volume_24h": 15234, "sentiment": 68.3, "percent_change_24h": 2.45, "volatility": 0.032, "price": "95000.12345678", "volume_24h": "45000000000.00000000", "market_cap": "1850000000000.00000000", "market_cap_rank": 1, "social_dominance": 45.2, "market_dominance": 52.1, "interactions_24h": 890000, "galaxy_score_previous": 70.1, "alt_rank_previous": 1 }, "updated_at": "2026-02-14T08:30:00.000Z" } ```
**LunarCrush 字段描述：**
| 字段 | 类型 | 描述 | |-------|------|-------------| | `galaxy_score` | Float | 整体代币质量评分 (0-100)，结合了社交、市场和开发者活动 | | `alt_rank` | Int | 所有加密货币中的排名 (越低越好，1 = 最好) | | `social_volume_24h` | Float | 过去 24 小时的社交媒体提及量 | | `sentiment` | Float | 市场情绪评分 (0-100，50 为中性，>50 为看涨) | | `percent_change_24h` | Float | 过去 24 小时的价格变化百分比 | | `volatility` | Float | 价格波动性评分 (0-1，<0.02 稳定，0.02-0.05 正常，>0.05 风险高) | | `price` | String | 当前美元价格 (用于精度的十进制字符串) | | `volume_24h` | String | 过去 24 小时的交易量 (十进制字符串) | | `market_cap` | String | 市值 (十进制字符串) | | `market_cap_rank` | Int | 市值排名 (越低越好) | | `social_dominance` | Float | 相对于总市场的社交量 | | `market_dominance` | Float | 相对于总市场的市值 | | `interactions_24h` | Float | 过去 24 小时的社交媒体互动量 | | `galaxy_score_previous` | Float | 之前的 galaxy score (用于趋势分析) | | `alt_rank_previous` | Int | 之前的 alt rank (用于趋势分析) |
**数据新鲜度：** - LunarCrush 数据由后台工作进程缓存并定期更新 - 检查 `updated_at` 字段以查看数据上次刷新的时间 - 数据通常每几个小时刷新一次
### 获取账户余额
检索用户 Ostium 钱包地址的 USDC 和 ETH 余额。
> **⚠️ 依赖项**：`address` 字段是用户的 Ostium 钱包地址 (`user_wallet`)。您必须先从 `/club-details` 获取它 —— 切勿硬编码或假设任何地址。
```bash curl -L -X POST "${MAXXIT_API_URL}/api/lazy-trading/programmatic/balance" \ -H "X-API-KEY: ${MAXXIT_API_KEY}" \ -H "Content-Type: application/json" \ -d "{"address": "0x..."}" ```
**响应：** ```json { "success": true, "address": "0x...", "usdcBalance": "1000.50", "ethBalance": "0.045" } ```
### 获取投资组合仓位
获取用户 Ostium 交易账户的所有未平仓位。**此端点至关重要** —— 它返回平仓和设置 TP/SL 所需的 `tradeIndex`、`pairIndex` 和 `entryPrice`。
> **⚠️ 依赖项**：`address` 字段必须来自 `/club-details` → `user_wallet`。切勿猜测它。 > > **🔑 此端点提供以下所需的值**：`/close-position` (需要 `tradeIndex`)、`/set-take-profit` (需要 `tradeIndex`、`pairIndex`、`entryPrice`)、`/set-stop-loss` (需要 `tradeIndex`、`pairIndex`、`entryPrice`)。
```bash curl -L -X POST "${MAXXIT_API_URL}/api/lazy-trading/programmatic/positions" \ -H "X-API-KEY: ${MAXXIT_API_KEY}" \ -H "Content-Type: application/json" \ -d "{"address": "0x..."}" ```
**请求体：** ```json { "address": "0x..." // REQUIRED — from /club-details → user_wallet. NEVER guess this. } ```
**响应：** ```json { "success": true, "positions": [ { "market": "BTC", "marketFull": "BTC/USD", "side": "long", "collateral": 100.0, "entryPrice": 95000.0, "leverage": 10.0, "tradeId": "12345", "tradeIndex": 2, "pairIndex": "0", "notionalUsd": 1000.0, "totalFees": 2.50, "stopLossPrice": 85500.0, "takeProfitPrice": 0.0 } ], "totalPositions": 1 } ```
> **需要从每个仓位提取的关键字段：** > - `tradeIndex` — `/close-position`、`/set-take-profit`、`/set-stop-loss` 所需 > - `pairIndex` — `/set-take-profit`、`/set-stop-loss` 所需 > - `entryPrice` — `/set-take-profit`、`/set-stop-loss` 所需 > - `side` — `/set-take-profit`、`/set-stop-loss` 所需 ```
### Get Position History
Get raw trading history for an address (includes open, close, cancelled orders, etc.).
**Note:** The user's Ostium wallet address can be fetched from the `/api/lazy-trading/programmatic/club-details` endpoint (see Get Account Balance section above).
```bash curl -L -X POST "${MAXXIT_API_URL}/api/lazy-trading/programmatic/history" \ -H "X-API-KEY: ${MAXXIT_API_KEY}" \ -H "Content-Type: application/json" \ -d '{"address": "0x...", "count": 50}' ```
**Request Body:** ```json { "address": "0x...", // 用户的 Ostium 钱包地址（必填） "count": 50 // 要检索的最近订单数量（默认：50） } ```
**Response:** ```json { "success": true, "history": [ { "market": "ETH", "side": "long", "collateral": 50.0, "leverage": 5, "price": 3200.0, "pnlUsdc": 15.50, "profitPercent": 31.0, "totalProfitPercent": 31.0, "rolloverFee": 0.05, "fundingFee": 0.10, "executedAt": "2025-02-10T15:30:00Z", "tradeId": "trade_123" } ], "count": 25 } ```
### Open Position
Open a new perpetual futures position on Ostium.
> **⚠️ Dependencies — ALL must be resolved BEFORE calling this endpoint:** > 1. `agentAddress` → from `/club-details` → `ostium_agent_address` (NEVER guess) > 2. `userAddress` → from `/club-details` → `user_wallet` (NEVER guess) > 3. `market` → validate via `/symbols` endpoint if unsure the token exists > - If `/symbols` returns `ETH/USD`, pass `market: "ETH"` to `/open-position` (not `ETH/USD`) > 4. `side`, `collateral`, `leverage` → **ASK the user explicitly**, do not assume > > **📊 Recommended Pre-Trade Flow:** > 1. Call `/lunarcrush?symbol=TOKEN/USD` or `/market-data` to get market conditions > 2. Present the market data to the user (price, sentiment, volatility) > 3. Ask the user: "Do you want to proceed? Specify: collateral (USDC), leverage, long/short" > 4. Only after user confirms → call `/open-position` > > **🔑 SAVE the response** — `actualTradeIndex` and `entryPrice` are needed for setting TP/SL later.
```bash curl -L -X POST "${MAXXIT_API_URL}/api/lazy-trading/programmatic/open-position" \ -H "X-API-KEY: ${MAXXIT_API_KEY}" \ -H "Content-Type: application/json" \ -d '{ "agentAddress": "0x...", "userAddress": "0x...", "market": "BTC", "side": "long", "collateral": 100, "leverage": 10 }' ```
**Request Body:** ```json { "agentAddress": "0x...", // 必填 — 来自 /club-details → ostium_agent_address。切勿猜测。 "userAddress": "0x...", // 必填 — 来自 /club-details → user_wallet。切勿猜测。 "market": "BTC", // 必填 — 仅限 Ostium 的基础代币（例如 "ETH"，而非 "ETH/USD"）。如不确定，请通过 /symbols 验证。 "side": "long", // 必填 — "long" 或 "short"。请询问用户。 "collateral": 100, // 必填 — USDC 中的抵押品。请询问用户。 "leverage": 10, // 可选（默认：10）。请询问用户。 "deploymentId": "uuid...", // 可选 — 关联的部署 ID "signalId": "uuid...", // 可选 — 关联的信号 ID "isTestnet": false // 可选（默认：false） } ```
**Response (IMPORTANT — save these values):** ```json { "success": true, "orderId": "order_123", "tradeId": "trade_abc", "transactionHash": "0x...", "txHash": "0x...", "status": "OPEN", "message": "Position opened successfully", "actualTradeIndex": 2, // ← 保存此项 — /set-take-profit 和 /set-stop-loss 所需 "entryPrice": 95000.0 // ← 保存此项 — /set-take-profit 和 /set-stop-loss 所需 } ```
### Close Position
Close an existing perpetual futures position on Ostium.
> **⚠️ Dependencies — resolve BEFORE calling this endpoint:** > 1. `agentAddress` → from `/club-details` → `ostium_agent_address` > 2. `userAddress` → from `/club-details` → `user_wallet` > 3. `tradeIndex` → call `/positions` first to find the position you want to close, then use its `tradeIndex` > > **NEVER guess the `tradeIndex` or `tradeId`.** Always fetch from `/positions` endpoint.
```bash curl -L -X POST "${MAXXIT_API_URL}/api/lazy-trading/programmatic/close-position" \ -H "X-API-KEY: ${MAXXIT_API_KEY}" \ -H "Content-Type: application/json" \ -d '{ "agentAddress": "0x...", "userAddress": "0x...", "market": "BTC", "tradeId": "12345" }' ```
**Request Body:** ```json { "agentAddress": "0x...", // 必填 — 来自 /club-details → ostium_agent_address。切勿猜测。 "userAddress": "0x...", // 必填 — 来自 /club-details → user_wallet。切勿猜测。 "market": "BTC", // 必填 — 代币符号 "tradeId": "12345", // 可选 — 来自 /positions → tradeId "actualTradeIndex": 2, // 强烈推荐 — 来自 /positions → tradeIndex。切勿猜测。 "isTestnet": false // 可选（默认：false） } ```
**Response:** ```json { "success": true, "result": { "txHash": "0x...", "market": "BTC", "closePnl": 25.50 }, "closePnl": 25.50, "message": "Position closed successfully", "alreadyClosed": false } ```
### Set Take Profit
Set or update take-profit level for an existing position on Ostium.
> **⚠️ Dependencies — you need ALL of these before calling:** > 1. `agentAddress` → from `/club-details` → `ostium_agent_address` > 2. `userAddress` → from `/club-details` → `user_wallet` > 3. `tradeIndex` → from `/open-position` response → `actualTradeIndex`, **OR** from `/positions` → `tradeIndex` > 4. `entryPrice` → from `/open-position` response → `entryPrice`, **OR** from `/positions` → `entryPrice` > 5. `pairIndex` → from `/positions` → `pairIndex`, **OR** from `/symbols` → symbol `id` > 6. `takeProfitPercent` → **ASK the user** (default: 0.30 = 30%) > 7. `side` → from `/positions` → `side` ("long" or "short") > > **If you just opened a position:** Use `actualTradeIndex` and `entryPrice` from the `/open-position` response. > **If the position was opened earlier:** Call `/positions` to fetch `tradeIndex`, `entryPrice`, `pairIndex`, and `side`.
```bash curl -L -X POST "${MAXXIT_API_URL}/api/lazy-trading/programmatic/set-take-profit" \ -H "X-API-KEY: ${MAXXIT_API_KEY}" \ -H "Content-Type: application/json" \ -d '{ "agentAddress": "0x...", "userAddress": "0x...", "market": "BTC", "tradeIndex": 2, "takeProfitPercent": 0.30, "entryPrice": 90000, "pairIndex": 0 }' ```
**Request Body:** ```json { "agentAddress": "0x...", // 必填 — 来自 /club-details。切勿猜测。 "userAddress": "0x...", // 必填 — 来自 /club-details。切勿猜测。 "market": "BTC", // 必填 — 代币符号 "tradeIndex": 2, // 必填 — 来自 /open-position 或 /positions。切勿猜测。 "takeProfitPercent": 0.30, // 可选（默认：0.30 = 30%）。请询问用户。 "entryPrice": 90000, // 必填 — 来自 /open-position 或 /positions。切勿猜测。 "pairIndex": 0, // 必填 — 来自 /positions 或 /symbols。切勿猜测。 "side": "long", // 可选（默认："long"）— 来自 /positions。 "isTestnet": false // 可选（默认：false） } ```
**Response:** ```json { "success": true, "message": "Take profit set successfully", "tpPrice": 117000.0 } ```
### Set Stop Loss
Set or update stop-loss level for an existing position on Ostium.
> **⚠️ Dependencies — identical to Set Take Profit. You need ALL of these before calling:** > 1. `agentAddress` → from `/club-details` → `ostium_agent_address` > 2. `userAddress` → from `/club-details` → `user_wallet` > 3. `tradeIndex` → from `/open-position` response → `actualTradeIndex`, **OR** from `/positions` → `tradeIndex` > 4. `entryPrice` → from `/open-position` response → `entryPrice`, **OR** from `/positions` → `entryPrice` > 5. `pairIndex` → from `/positions` → `pairIndex`, **OR** from `/symbols` → symbol `id` > 6. `stopLossPercent` → **ASK the user** (default: 0.10 = 10%) > 7. `side` → from `/positions` → `side` ("long" or "short") > > **If you just opened a position:** Use `actualTradeIndex` and `entryPrice` from the `/open-position` response. > **If the position was opened earlier:** Call `/positions` to fetch `tradeIndex`, `entryPrice`, `pairIndex`, and `side`.
```bash # 依赖项解析与设置止盈相同（完整示例见上文） # 第一步：从 /club-details 获取地址 # 第二步：从 /positions 获取仓位详情 # 第三步：使用用户指定的 stopLossPercent 设置止损
curl -L -X POST "${MAXXIT_API_URL}/api/lazy-trading/programmatic/set-stop-loss" \ -H "X-API-KEY: ${MAXXIT_API_KEY}" \ -H "Content-Type: application/json" \ -d '{ "agentAddress": "0x...", "userAddress": "0x...", "market": "BTC", "tradeIndex": 2, "stopLossPercent": 0.10, "entryPrice": 90000, "pairIndex": 0, "side": "long" }' ```
**Request Body:** ```json { "agentAddress": "0x...", // 必填 — 来自 /club-details。切勿猜测。 "userAddress": "0x...", // 必填 — 来自 /club-details。切勿猜测。 "market": "BTC", // 必填 — 代币符号 "tradeIndex": 2, // 必填 — 来自 /open-position 或 /positions。切勿猜测。 "stopLossPercent": 0.10, // 可选（默认：0.10 = 10%）。请询问用户。 "entryPrice": 90000, // 必填 — 来自 /open-position 或 /positions。切勿猜测。 "pairIndex": 0, // 必填 — 来自 /positions 或 /symbols。切勿猜测。 "side": "long", // 可选（默认："long"）— 来自 /positions。 "isTestnet": false // 可选（默认：false） } ```
**Response:** ```json { "success": true, "message": "Stop loss set successfully", "slPrice": 81000.0, "liquidationPrice": 85500.0, "adjusted": false } ```
### Get All Market Data
Retrieve the complete market snapshot from Ostium, including all symbols and their full LunarCrush metrics. This is highly recommended for AI agents that want to perform market-wide scanning or analysis in a single request.
```bash curl -L -X GET "${MAXXIT_API_URL}/api/lazy-trading/programmatic/market-data" \ -H "X-API-KEY: ${MAXXIT_API_KEY}" ```
**Response:** ```json { "success": true, "data": [ { "id": 0, "symbol": "BTC/USD", "group": "crypto", "maxLeverage": 150, "metrics": { "galaxy_score": 72.5, "alt_rank": 1, "social_volume_24h": 15234, "sentiment": 68.3, "percent_change_24h": 2.45, "volatility": 0.032, "price": "95000.12345678", "volume_24h": "45000000000.00000000", "market_cap": "1850000000000.00000000", "market_cap_rank": 1, "social_dominance": 45.2, "market_dominance": 52.1, "interactions_24h": 890000, "galaxy_score_previous": 70.1, "alt_rank_previous": 1 }, "updated_at": "2026-02-14T08:30:00.000Z" }, ... ], "count": 45 } ```
### Get Token Price
Fetch the current market price for a token from Ostium price feed.
```bash curl -L -X GET "${MAXXIT_API_URL}/api/lazy-trading/programmatic/price?token=BTC&isTestnet=false" \ -H "X-API-KEY: ${MAXXIT_API_KEY}" ```
**Query Parameters:** | Parameter | Type | Required | Description | |-----------|-------|----------|-------------| | `token` | string | Yes | Token symbol to fetch price for (e.g., BTC, ETH, SOL) | | `isTestnet` | boolean | No | Use testnet price feed (default: false) |
**Response:** ```json { "success": true, "token": "BTC", "price": 95000.0, "isMarketOpen": true, "isDayTradingClosed": false } ```
### Discover Traders to Copy (Copy Trading — Step 1)
Discover other OpenClaw Traders and top-performing traders to potentially copy-trade. This is the **first step** in the copy-trading workflow — the returned wallet addresses are used as the `address` parameter in the `/copy-trader-trades` endpoint.
> **⚠️ Dependency Chain**: This endpoint provides the wallet addresses needed by `/copy-trader-trades`. You MUST call this endpoint FIRST to get trader addresses — do NOT guess or hardcode addresses.
```bash # 获取所有交易员（OpenClaw + 排行榜） curl -L -X GET "${MAXXIT_API_URL}/api/lazy-trading/programmatic/copy-traders" \ -H "X-API-KEY: ${MAXXIT_API_KEY}"
# 仅获取 OpenClaw 交易员（优先） curl -L -X GET "${MAXXIT_API_URL}/api/lazy-trading/programmatic/copy-traders?source=openclaw" \ -H "X-API-KEY: ${MAXXIT_API_KEY}"
# 仅获取带筛选条件的排行榜交易员 curl -L -X GET "${MAXXIT_API_URL}/api/lazy-trading/programmatic/copy-traders?source=leaderboard&minImpactFactor=50&minTrades=100" \ -H "X-API-KEY: ${MAXXIT_API_KEY}" ```
**Query Parameters:** | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `source` | string | `all` | `openclaw` (OpenClaw agents only), `leaderboard` (top traders only), `all` (both) | | `limit` | int | 20 | Max results per tier (max 100) | | `minTrades` | int | — | Min trade count filter (leaderboard only) | | `minImpactFactor` | float | — | Min impact factor filter (leaderboard only) |
**Response:** ```json { "success": true, "openclawTraders": [ { "agentId": "3dbc322f-...", "agentName": "OpenClaw Trader - 140226114735", "creatorWallet": "0x4e7f1e29d9e1f81c3e9249e3444843c2006f3325", "venue": "OSTIUM", "status": "PRIVATE", "isCopyTradeClub": false, "performance": { "apr30d": 0, "apr90d": 0, "aprSinceInception": 0, "sharpe30d": 0 }, "deployment": { "id": "dep-uuid", "status": "ACTIVE", "safeWallet": "0x...", "isTestnet": false } } ], "topTraders": [ { "walletAddress": "0xabc...", "totalVolume": "1500000.000000", "totalClosedVolume": "1200000.000000", "totalPnl": "85000.000000", "totalProfitTrades": 120, "totalLossTrades": 30, "totalTrades": 150, "winRate": 0.80, "lastActiveAt": "2026-02-15T10:30:00.000Z", "scores": { "edgeScore": 0.82, "consistencyScore": 0.75, "stakeScore": 0.68, "freshnessScore": 0.92, "impactFactor": 72.5 }, "updatedAt": "2026-02-17T06:00:00.000Z" } ], "openclawCount": 5, "topTradersCount": 20 } ```
**Key fields to use in next steps:** - `openclawTraders[].creatorWallet` → use as `address` in `/copy-trader-trades` - `topTraders[].walletAddress` → use as `address` in `/copy-trader-trades`
### Get Trader's Recent Trades (Copy Trading — Step 2)
Fetch recent on-chain trades for a specific trader address. This queries the Ostium subgraph in real-time for fresh trade data.
> **⚠️ Dependency**: The `address` parameter MUST come from the `/copy-traders` endpoint response: > - For OpenClaw traders: use `creatorWallet` from `openclawTraders[]` > - For leaderboard traders: use `walletAddress` from `topTraders[]` > > **NEVER guess or hardcode the address.** Always call `/copy-traders` first.
```bash # 第一步：首先发现交易员 TRADER_ADDRESS=$(curl -s -L -X GET "${MAXXIT_API_URL}/api/lazy-trading/programmatic/copy-traders?source=openclaw" \ -H "X-API-KEY: ${MAXXIT_API_KEY}" | jq -r '.openclawTraders[0].creatorWallet')
# 第二步：获取他们的近期交易 curl -L -X GET "${MAXXIT_API_URL}/api/lazy-trading/programmatic/copy-trader-trades?address=${TRADER_ADDRESS}" \ -H "X-API-KEY: ${MAXXIT_API_KEY}"
# 使用自定义回溯时间和限制 ```
**Query Parameters:** | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `address` | string | *required* | Trader wallet address (from `/copy-traders`) | | `limit` | int | 20 | Max trades to return (max 50) | | `hours` | int | 24 | Lookback window in hours (max 168 / 7 days) |
**Response:** ```json ```
**Trade Field Descriptions:** | Field | Description | |-------|-------------| | `side` | `"LONG"` or `"SHORT"` — the trade direction | | `tokenSymbol` | Token being traded (e.g., `BTC`, `ETH`) | | `pair` | Full pair label (e.g., `BTC/USD`) | | `collateral` | USDC amount used as collateral | | `leverage` | Leverage multiplier (e.g., 10.0 = 10x) | | `entryPrice` | Price at which the trade was opened | | `takeProfitPrice` | Take profit price (null if not set) | | `stopLossPrice` | Stop loss price (null if not set) | | `timestamp` | When the trade was opened |
> **Next step**: After reviewing the trades, use `/open-position` to open a similar position. You'll need your own `agentAddress` and `userAddress` from `/club-details`.
## Signal Format Examples
The lazy trading system processes natural language trading signals. Here are examples:
### Opening Positions - `"Long ETH with 5x leverage, entry at 3200"` - `"Short BTC 10x, TP 60000, SL 68000"` - `"Buy 100 USDC worth of ETH perpetual"`
### With Risk Management - `"Long SOL 3x leverage, entry 150, take profit 180, stop loss 140"` - `"Short AVAX 5x, risk 2% of portfolio"`
### Closing Positions - `"Close ETH long position"` - `"Take profit on BTC short"`
---
## Complete Workflow Examples
These are the mandatory step-by-step workflows for common trading operations. **Follow these exactly.**
### Workflow 1: Opening a New Position (Full Flow)
``` 步骤 1：GET /club-details → 提取：user_wallet（→ userAddress），ostium_agent_address（→ agentAddress） → 为当前会话缓存这些信息
步骤 2：GET /symbols → 验证用户请求的代币在 Ostium 上是否可用 → 提取精确的代币符号字符串和 maxLeverage → 将交易对格式转换为 /open-position 所需的市场代币： "ETH/USD" -> "ETH"
步骤 3：GET /lunarcrush?symbol=TOKEN/USD （或 GET /market-data 获取全部） → 获取市场数据：价格、情绪、波动率、galaxy_score → 向用户展示这些数据： "BTC 当前价格为 $95,000，情绪指数 68.3（看涨），波动率 0.032（正常）。 Galaxy Score：72.5/100。您要继续吗？"
步骤 4：询问用户交易参数 → "请确认：保证金（USDC）、杠杆、做多还是做空？" → "您想设置止盈（TP）和止损（SL）吗？如果是，具体百分比是多少？" → 等待用户明确确认后再继续
步骤 5：POST /open-position → 使用步骤 1 中的 agentAddress 和 userAddress → 使用步骤 4 中的 market、side、collateral、leverage → 重要：仅传递基础代币作为 market（例如 ETH），不要使用交易对格式（ETH/USD） → 保存响应：actualTradeIndex 和 entryPrice
步骤 6（如果用户想要 TP/SL）：POST /set-take-profit 和/或 POST /set-stop-loss → 使用步骤 5 中的 tradeIndex = actualTradeIndex → 使用步骤 5 中的 entryPrice → 对于 pairIndex，使用步骤 2 中的代币 ID id 或调用 /positions → 使用步骤 4 中的 takeProfitPercent/stopLossPercent ```
### Workflow 2: Closing an Existing Position
``` 步骤 1：GET /club-details → 提取：user_wallet，ostium_agent_address
步骤 2：POST /positions（address = 步骤 1 中的 user_wallet） → 列出所有持仓 → 如果有多个，向用户展示："您有 3 个持仓：BTC 多头，ETH 空头，SOL 多头。您想平掉哪一个？" → 提取要平仓的 tradeIndex
步骤 3：POST /close-position → 使用步骤 1 中的 agentAddress 和 userAddress → 使用步骤 2 中的 market 和 actualTradeIndex → 向用户展示响应中的 closePnl ```
### Workflow 3: Setting TP/SL on an Existing Position
``` 步骤 1：GET /club-details → 提取：user_wallet，ostium_agent_address
步骤 2：POST /positions（address = 步骤 1 中的 user_wallet） → 找到目标持仓 → 提取：tradeIndex，entryPrice，pairIndex，side
步骤 3：询问用户 → "持仓：BTC 多头，入场价 $95,000。当前止盈：无，止损：$85,500。" → "您想设置多少的止盈百分比（TP%）和止损百分比（SL%）？"
步骤 4：POST /set-take-profit 和/或 POST /set-stop-loss → 使用步骤 1-3 中的所有值 —— 切勿猜测任何值 ```
### Workflow 4: Checking Portfolio & Market Overview
``` 步骤 1：GET /club-details → 提取：user_wallet
步骤 2：POST /balance（address = user_wallet） → 向用户展示他们的 USDC 和 ETH 余额
步骤 3：POST /positions（address = user_wallet） → 展示所有持仓及其盈亏（PnL）详情
步骤 4（可选）：GET /market-data → 展示其持有的代币的市场状况 ```
### Workflow 5: Copy-Trading Another OpenClaw Agent (Full Flow)
``` 步骤 1：GET /copy-traders?source=openclaw → 发现其他 OpenClaw 交易员代理 → 提取：您想要跟单的交易员的 creatorWallet → 重要：这是必须的第一步 —— 如果没有此接口返回的地址， 您将无法调用 /copy-trader-trades
步骤 2：GET /copy-trader-trades?address={creatorWallet} → 从 Ostium 子图获取该交易员最近的交易 → 审查：方向（LONG/SHORT）、代币符号、杠杆、保证金、入场价格 → 决定："我应该跟单这笔交易吗？" → 依赖关系：address 参数来自步骤 1（creatorWallet 或 walletAddress）
步骤 3：GET /club-details → 获取您自己的 userAddress（user_wallet）和 agentAddress（ostium_agent_address） → 这些是执行您自己的交易所必需的
步骤 4：POST /open-position → 使用步骤 3 中的您自己的地址镜像步骤 2 中的交易： - market = 跟单交易中的 tokenSymbol - side = 跟单交易中的 side（LONG/SHORT → long/short） - collateral = 根据您自己的风险承受能力决定 - leverage = 匹配跟单交易员的杠杆或自行调整 → 保存：响应中的 actualTradeIndex 和 entryPrice
步骤 5（可选）：POST /set-take-profit 和/或 POST /set-stop-loss → 使用步骤 4 中的 actualTradeIndex 和 entryPrice → 匹配跟单交易员的止盈止损（TP/SL）比率或设置您自己的 ```
**Dependency Chain Summary:** ``` /copy-traders → 提供地址 → /copy-trader-trades → 提供交易详情 /club-details → 提供您的地址 → /open-position → 复制交易 ```
---
## Aster DEX (BNB Chain) Endpoints
> Aster DEX is a perpetual futures exchange on BNB Chain. Use Aster endpoints when the user wants to trade on BNB Chain. The Aster API uses **API Key + Secret** authentication (stored server-side) — you do NOT need `agentAddress`. You only need `userAddress` from `/club-details`.
### Venue Selection
| Venue | Chain | Symbol Format | Auth Required | When to Use | |-------|-------|--------------|---------------|-------------| | **Ostium** | Arbitrum | `BTC`, `ETH` | `agentAddress` + `userAddress` | Default for most trades | | **Aster** | BNB Chain | `BTCUSDT`, `ETHUSDT` | `userAddress` only | When user specifies BNB Chain or Aster |
**How to check if Aster is configured:** In the `/club-details` response, `aster_configured: true` means the user has set up Aster API keys. If `false`, direct them to set up Aster at maxxit.ai/openclaw.
### Aster Symbols
Aster uses Binance-style symbol format: `BTCUSDT`, `ETHUSDT`, etc. The API auto-appends `USDT` if you pass just `BTC`.
```bash ```
**Response:** ```json ```
### Aster Price
```bash ```
**Response:** ```json ```
### Aster Market Data
```bash ```
### Aster Balance
```bash ```
**Request Body:** ```json ```
**Response:** ```json ```
### Aster Positions
```bash ```
**Response:** ```json ```
### Aster Open Position
> **📋 LLM Pre-Call Checklist — Ask the user these questions before calling this endpoint:** > 1. **Symbol**: "Which token do you want to trade?" (e.g. BTC, ETH, SOL) > 2. **Side**: "Long or short?" > 3. **Quantity**: "How much [TOKEN] do you want to trade?" — get the answer in base asset units (e.g. `0.01 BTC`, `0.5 ETH`). > 4. **Leverage**: "What leverage? (e.g. 10x)" > 5. **Order type**: "Market order or limit order?" (default: MARKET). If LIMIT, also ask for the limit price. > > **Aster requires `quantity` (base asset) for open-position. Do not use collateral.** > **NEVER call this endpoint without a confirmed `quantity` in base asset units.**
```bash ```
**Request Body:** ```json ```
> ⚠️ **IMPORTANT:** `quantity` must always be specified in the **base asset** (e.g. `0.01` for 0.01 BTC). > If the user provides a USDT/collateral amount, ask them to provide the exact token quantity instead. > Do not convert collateral to quantity in this workflow.
**Response (IMPORTANT — save these values):** ```json ```
### Aster Close Position
```bash ```
**Request Body:** ```json ```
### Aster Set Take Profit
```bash ```
**Request Body (two options):** ```json ``` ```json ```
### Aster Set Stop Loss
Same pattern as take profit:
```bash ```
### Aster Change Leverage
```bash ```
### Aster Parameter Dependency Graph
| Parameter | Source | How to Get | |-----------|--------|-----------| | `userAddress` | `/club-details` → `user_wallet` | `GET /club-details` | | `aster_configured` | `/club-details` → `aster_configured` | `GET /club-details` (must be `true`) | | `symbol` | User specifies token | User input (auto-resolved: `BTC` → `BTCUSDT`) | | `side` | User specifies `"long"` or `"short"` | User input (required) | | `quantity` | User specifies in base asset units (e.g. `0.01 BTC`) | User input (required). If user provides USDT/collateral amount, ask for quantity instead. Do not calculate in the workflow. | | `leverage` | User specifies | User input | | `entryPrice` | `/aster/positions` → `entryPrice` | From position data | | `stopPrice` | User specifies or calculated from percent | User input or calculated |
### Aster Workflow: Open Position on BNB Chain
``` 步骤 1：GET /club-details → 提取：user_wallet → 检查：aster_configured == true（如果为 false，提示用户前往 maxxit.ai/openclaw 配置 Aster）
{ "text": "步骤 2：GET /aster/symbols\n → 验证 Token 在 Aster 上是否可用\n\n步骤 3：GET /aster/price?token=BTC\n → 获取当前价格，展示给用户\n\n步骤 4：询问用户所有交易参数\n → “哪个 Token？”（例如 BTC, ETH, SOL）\n → “做多还是做空？”\n → “你想买入/卖出多少 [TOKEN]？” — 以基础资产单位收集答案（例如 0.01 BTC）\n • 如果用户提供的 USDT/抵押品金额，请让他们提供 Token 数量。\n → “杠杆？（例如 10x）”\n → “市价单还是限价单？” — 如果选择 LIMIT，则询问限价\n\n步骤 5：POST /aster/open-position\n → 使用来自步骤 1 的 userAddress\n → 使用来自步骤 4 的 symbol、side、quantity（基础资产）、leverage\n → 保存响应中的 orderId 和 avgPrice\n\n步骤 6（如果用户想要止盈/止损）：POST /aster/set-take-profit 和/或 POST /aster/set-stop-loss\n → 使用 entryPrice = 步骤 5 中的 avgPrice\n → 使用步骤 4 中的 side\n → 询问用户 takeProfitPercent / stopLossPercent（或具体的 stopPrice）\n```
### Aster Workflow: Close Position
```\n步骤 1：GET /club-details → 提取 user_wallet\n\n步骤 2：POST /aster/positions (userAddress = user_wallet)\n → 向用户展示持仓，让他们选择要平仓的\n\n步骤 3：POST /aster/close-position\n → 传递 userAddress 和 symbol\n → 省略 quantity 以平掉全部持仓\n