Skill: seineruo/msx-trade (version 1.0.0)

--- name: "msx-trade" version: "1.0.0" description: "Trade security tokens on the MSX platform — check balances, place orders, view market data, and review trade history." homepage: https://github.com/YOUR_USERNAME/msx-trade-skill tags: ["finance", "trading", "security-tokens", "msx"] metadata: clawdbot: emoji: "📈" requires: env: - name: MSX_API_KEY description: "Your personal MSX platform API key. Apply at https://msx.com/api" --- # MSX Security Token Trading Skill You are an AI trading assistant connected to the MSX platform via API. Help the user manage their account, execute trades, and monitor the market. ## Authentication All requests require the following header: ``` X-[REDACTED_SECRET] ``` The key is stored in the environment variable `MSX_API_KEY`. Base URL: `https://api.msx.com/v1` > ⚠️ Never expose, log, or repeat the API key in any response. > If `MSX_API_KEY` is missing, ask the user to set it before proceeding. --- ## Modules This skill is split into four functional modules. Load the relevant file based on user intent: | Module | File | Covers | |--------|------|--------| | Account & Portfolio | `api-account.md` | Balance, holdings, profile | | Market Data | `api-market.md` | Quotes, order book, candlesticks | | Order Execution | `api-orders.md` | Place, cancel, view orders | | Trade History | `api-history.md` | Past trades, orders, fund flow | --- ## General Behavior Guidelines - Respond in the same language the user uses (Chinese or English). - For market data responses, always show the data timestamp. - For portfolio queries, present multiple positions as a table. - If a user's intent spans multiple modules, call APIs from each as needed and combine the results. ## Error Handling | HTTP Code | Meaning | Tell the user | |-----------|---------|---------------| "| 401 | Invalid or missing API key | "API KEY invalid, check MSX_API_KEY" | | 403 | Insufficient permissions | "Insufficient permissions, confirm API KEY has required features enabled" | | 429 | Rate limit exceeded | "Too many requests, please try again later" | | 404 | Resource not found | "Token or order not found, please verify input" | | 500 | Server error | "MSX service temporarily unavailable, please try again later" |

path: api-market.md
content: # Module: Market Data

**When to load this file:** User asks about token prices, market quotes, order book depth, or chart/candlestick data.

Trigger phrases: "quote", "price", "orderbook", "candle", "价格", "行情", "报价", "盘口", "K线", "走势"

---

## GET /market/tokens

Returns the full list of tradable security tokens on MSX.

**Request**
```
GET /market/tokens
X-[REDACTED_SECRET]
```

**Query params**

| Param | Type | Required | Description |
|-------|------|----------|-------------|
| status | string | No | Filter by `active` / `suspended`. Default: `active` |

**Response**
```json
{
  "tokens": [
    {
      "symbol": "TOKEN-AAPL",
      "name": "Apple Inc. Token",
      "asset_type": "equity",
      "exchange": "MSX",
      "status": "active"
    }
  ]
}
```

---

## GET /market/tokens/{symbol}/quote

Returns the latest price quote for a specific token.

**Request**
```
GET /market/tokens/TOKEN-AAPL/quote
X-[REDACTED_SECRET]
```

**Response**
```json
{
  "symbol": "TOKEN-AAPL",
  "last_price": 195.00,
  "bid": 194.95,
  "ask": 195.05,
  "change": 2.50,
  "change_pct": 1.30,
  "volume": 125000,
  "timestamp": "2025-03-25T10:30:00Z"
}
```

> Always display `timestamp` so the user knows how fresh the data is.

---

## GET /market/tokens/{symbol}/orderbook

Returns the current bid/ask order book for a token.

**Request**
```
GET /market/tokens/TOKEN-AAPL/orderbook
X-[REDACTED_SECRET]
```

**Query params**

| Param | Type | Required | Description |
|-------|------|----------|-------------|
| depth | integer | No | Number of price levels per side. Default: `10` |

**Response**
```json
{
  "symbol": "TOKEN-AAPL",
  "bids": [
    { "price": 194.95, "quantity": 200 },
    { "price": 194.90, "quantity": 500 }
  ],
  "asks": [
    { "price": 195.05, "quantity": 150 },
    { "price": 195.10, "quantity": 300 }
  ],
  "timestamp": "2025-03-25T10:30:00Z"
}
```

---

## GET /market/tokens/{symbol}/candles

Returns OHLCV candlestick data for charting or trend analysis.

**Request**
```
GET /market/tokens/TOKEN-AAPL/candles
X-[REDACTED_SECRET]
```

**Query params**

| Param | Type | Required | Description |
|-------|------|----------|-------------|
| interval | string | Yes | `1m`, `5m`, `15m`, `1h`, `1d` |
| limit | integer | No | Number of candles to return. Default: `100`, max: `500` |

**Response**
```json
{
  "symbol": "TOKEN-AAPL",
  "interval": "1d",
  "candles": [
    {
      "time": "2025-03-24T00:00:00Z",
      "open": 192.00,
      "high": 196.50,
      "low": 191.00,
      "close": 195.00,
      "volume": 980000
    }
  ]
}
```


path: api-history.md
content: # Module: Trade History & Reports

**When to load this file:** User asks about past trades, historical orders, or fund deposit/withdrawal records.

Trigger phrases: "history", "report", "transactions", "past trades", "历史", "记录", "报表", "成交", "流水"

---

## GET /trades/history — Executed trade history

Returns a list of all completed fills (actual executions).

**Request**
```
GET /trades/history
X-[REDACTED_SECRET]
```

**Query params**

| Param | Type | Required | Description |
|-------|------|----------|-------------|
| symbol | string | No | Filter by token symbol |
| from | string | No | Start date, ISO 8601 format: `2025-01-01T00:00:00Z` |
| to | string | No | End date, ISO 8601 format |
| limit | integer | No | Max records to return. Default: `50`, max: `500` |

**Response**
```json
{
  "trades": [
    {
      "trade_id": "TRD-20250324-001",
      "order_id": "ORD-20250324-005",
      "symbol": "TOKEN-AAPL",
      "side": "buy",
      "quantity": 60,
      "price": 194.45,
      "fee": 1.17,
      "fee_currency": "USD",
      "executed_at": "2025-03-24T09:36:00Z"
    }
  ],
  "total": 1
}
```

---

## GET /orders/history — Historical orders

Returns all past orders regardless of status (filled, cancelled, rejected).

**Request**
```
GET /orders/history
X-[REDACTED_SECRET]
```

**Query params**

| Param | Type | Required | Description |
|-------|------|----------|-------------|
| status | string | No | `filled`, `cancelled`, `rejected`, or `all`. Default: `all` |
| symbol | string | No | Filter by token symbol |
| from | string | No | Start date, ISO 8601 |
| to | string | No | End date, ISO 8601 |
| limit | integer | No | Default: `50`, max: `500` |

**Response**
```json
{
  "orders": [
    {
      "order_id": "ORD-20250324-005",
      "symbol": "TOKEN-AAPL",
      "side": "buy",
      "type": "limit",
      "quantity": 100,
      "filled_quantity": 100,
      "avg_fill_price": 194.48,
      "status": "filled",
      "created_at": "2025-03-24T09:35:00Z",
      "updated_at": "2025-03-24T09:37:00Z"
    }
  ],
  "total": 1
}
```

---

## GET /account/transactions — Fund transaction history

Returns cash flow records: deposits, withdrawals, trade settlements, and fees.

**Request**
```
GET /account/transactions
X-[REDACTED_SECRET]
```

**Query params**

| Param | Type | Required | Description |
|-------|------|----------|-------------|
| type | string | No | `deposit`, `withdrawal`, `trade`, `fee`, or `all`. Default: `all` |
| from | string | No | Start date, ISO 8601 |
| to | string | No | End date, ISO 8601 |
| limit | integer | No | Default: `50`, max: `500` |

**Response**
```json
{
  "transactions": [
    {
      "tx_id": "TX-20250320-001",
      "type": "deposit",
      "amount": 10000.00,
      "currency": "USD",
      "balance_after": 25000.00,
      "description": "Bank wire deposit",
      "created_at": "2025-03-20T08:00:00Z"
    },
    {
      "tx_id": "TX-20250324-010",
      "type": "trade",
      "amount": -11668.80,
      "currency": "USD",
      "balance_after": 13331.20,
      "description": "Buy 60 TOKEN-AAPL @ 194.45 + fee 1.17",
      "created_at": "2025-03-24T09:36:00Z"
    }
  ],
  "total": 2
}
```

**Display guidance:**
- Default to last 30 days if user doesn't specify a date range.
- Positive `amount` = money in (deposit, sell proceeds).
- Negative `amount` = money out (withdrawal, buy payment, fee).
- Present as a table sorted by `created_at` descending.


path: api-account.md
content: # Module: Account & Portfolio

**When to load this file:** User asks about their account info, cash balance, holdings, or portfolio value.

Trigger phrases: "balance", "portfolio", "positions", "余额", "持仓", "账户", "组合", "资产"

---

## GET /account/profile

Returns basic account information.

**Request**
```
GET /account/profile
X-[REDACTED_SECRET]
```

**Response**
```json
{
  "user_id": "U123456",
  "name": "Zhang San",
  "status": "active",
  "kyc_level": 2,
  "registered_at": "2024-01-15T08:00:00Z"
}
```

---

## GET /account/balance

Returns the user's current cash balance.

**Request**
```
GET /account/balance
X-[REDACTED_SECRET]
```

**Response**
```json
{
  "currency": "USD",
  "available": 15000.00,
  "frozen": 2500.00,
  "total": 17500.00
}
```

Field notes:
- `available` — cash free to use for new orders
- `frozen` — cash locked in pending orders
- `total` — available + frozen

---

## GET /account/positions

Returns all currently held security tokens.

**Request**
```
GET /account/positions
X-[REDACTED_SECRET]
```

**Response**
```json
{
  "positions": [
    {
      "symbol": "TOKEN-AAPL",
      "name": "Apple Inc. Token",
      "quantity": 50,
      "avg_cost": 182.30,
      "current_price": 195.00,
      "market_value": 9750.00,
      "unrealized_pnl": 635.00,
      "unrealized_pnl_pct": 6.97
    }
  ],
  "total_market_value": 9750.00,
  "total_unrealized_pnl": 635.00
}
```

**Display format:** Present as a table when multiple positions exist.

| Symbol | Qty | Avg Cost | Current Price | Market Value | P&L |
|--------|-----|----------|---------------|--------------|-----|
| TOKEN-AAPL | 50 | 182.30 | 195.00 | 9,750.00 | +635.00 (6.97%) |


path: api-orders.md
content: # Module: Order Execution

**When to load this file:** User wants to place, cancel, or check the status of orders.

Trigger phrases: "buy", "sell", "order", "cancel", "买入", "卖出", "下单", "挂单", "撤单"

---

## ⚠️ Order Safety Rules

Before calling POST /orders, always:

1. **Confirm details** — repeat back symbol, side, type, quantity, and price (if limit).
2. **Wait for explicit confirmation** — only proceed after user says "yes", "confirm", or equivalent.
3. **Large order warning** — if the order value exceeds 10% of the user's available balance, show an extra warning before confirming.
4. **Never assume** — if any parameter is ambiguous (e.g., user says "buy some AAPL"), ask for quantity and price before proceeding.

---

## POST /orders — Place an order

**Request**
```
POST /orders
X-[REDACTED_SECRET]
Content-Type: application/json
```

**Request body**

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| symbol | string | Yes | Token symbol, e.g. `TOKEN-AAPL` |
| side | string | Yes | `buy` or `sell` |
| type | string | Yes | `limit` or `market` |
| quantity | number | Yes | Number of tokens |
| price | number | Limit only | Required when type is `limit` |

**Example — limit buy**
```json
{
  "symbol": "TOKEN-AAPL",
  "side": "buy",
  "type": "limit",
  "quantity": 100,
  "price": 194.50
}
```

**Example — market sell**
```json
{
  "symbol": "TOKEN-AAPL",
  "side": "sell",
  "type": "market",
  "quantity": 50
}
```

**Response**
```json
{
  "order_id": "ORD-20250325-001",
  "symbol": "TOKEN-AAPL",
  "side": "buy",
  "type": "limit",
  "quantity": 100,
  "price": 194.50,
  "status": "open",
  "filled_quantity": 0,
  "avg_fill_price": null,
  "created_at": "2025-03-25T10:35:00Z"
}
```

---

## DELETE /orders/{order_id} — Cancel an order

**Request**
```
DELETE /orders/ORD-20250325-001
X-[REDACTED_SECRET]
```

**Response**
```json
{
  "order_id": "ORD-20250325-001",
  "status": "cancelled",
  "cancelled_at": "2025-03-25T10:40:00Z"
}
```

> Only orders with status `open` or `partial` can be cancelled.  
> If the order is already filled or cancelled, the API returns 400.

---

## GET /orders/open — List open orders

Returns all pending or partially filled orders.

**Request**
```
GET /orders/open
X-[REDACTED_SECRET]
```

**Response**
```json
{
  "orders": [
    {
      "order_id": "ORD-20250325-001",
      "symbol": "TOKEN-AAPL",
      "side": "buy",
      "type": "limit",
      "quantity": 100,
      "filled_quantity": 30,
      "price": 194.50,
      "status": "partial",
      "created_at": "2025-03-25T10:35:00Z"
    }
  ]
}
```

---

## GET /orders/{order_id} — Get a single order

**Request**
```
GET /orders/ORD-20250325-001
X-[REDACTED_SECRET]
```

**Response** — same schema as above, with additional fill details:
```json
{
  "order_id": "ORD-20250325-001",
  "status": "filled",
  "filled_quantity": 100,
  "avg_fill_price": 194.48,
  "fills": [
    { "price": 194.45, "quantity": 60, "time": "2025-03-25T10:36:00Z" },
    { "price": 194.52, "quantity": 40, "time": "2025-03-25T10:37:00Z" }
  ]
}
```

**Order status values**

| Status | Meaning |
|--------|---------|
| `open` | Pending, no fills yet |
| `partial` | Partially filled |
| `filled` | Fully executed |
| `cancelled` | Cancelled by user |
| `rejected` | Rejected by system |


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (HIGH)