pionex-trade

Pionex Trading Skill

Spot order placement and management on Pionex via the pionex-trade-cli CLI. Requires API credentials in ~/.pionex/config.toml (run pionex-ai-kit onboard first).
Security: Pionex API Docs recommend IP whitelisting and never sharing your API Key/Secret.

Prerequisites

1. Install CLI and configure credentials:

   npm install -g @pionex/pionex-ai-kit
   pionex-ai-kit onboard
   

2. Test (read-only):

   pionex-trade-cli account balance
   

Skill Routing

• Market data (price, depth, klines, symbol info) → pionex-market
• Account balance → pionex-portfolio (or use pionex-trade-cli account balance here when checking before order)
• Place/cancel orders, open orders, fills → pionex-trade (this skill)
• Futures grid bot lifecycle (create/adjust/reduce/cancel) → pionex-bot

Command Index (orders & account used by this skill)

Command	Type	Description
pionex-trade-cli account balance	READ	All spot balances (filter by currency from JSON if needed)
pionex-trade-cli orders new --symbol <s> --side BUY|SELL --type MARKET|LIMIT [--amount | --size] [--price] [--dry-run]	WRITE	Create order. MARKET buy: use --amount (quote). MARKET sell / LIMIT: use --size (base). LIMIT: add --price
pionex-trade-cli orders get --symbol <s> --order-id <id>	READ	Get one order by ID
pionex-trade-cli orders open --symbol <s>	READ	List open orders for symbol
pionex-trade-cli orders all --symbol <s> [--limit <n>]	READ	Order history (filled/cancelled)
pionex-trade-cli orders fills --symbol <s> [--startTime] [--endTime]	READ	Fills (executed trades)
pionex-trade-cli orders fills_by_order_id --symbol <s> --order-id <id>	READ	Fills for one specific order
pionex-trade-cli orders cancel --symbol <s> --order-id <id> [--dry-run]	WRITE	Cancel one order
pionex-trade-cli orders cancel_all --symbol <s> [--dry-run]	WRITE	Cancel all open orders for symbol

Symbol info (min size, precision) before placing orders: use pionex-market → pionex-trade-cli market symbols --symbols BTC_USDT.

---

1. When to use this skill

Use pionex-trade when the user wants to:

• Place a spot order (market or limit buy/sell).
• Cancel an order or all orders for a symbol.
• Query open orders, order history, or fills.

Do not use for: only checking prices or order book (use pionex-market); only checking balance (pionex-portfolio, or pionex-trade-cli account balance as part of a trade flow).

---

2. General rules

1. Explicit parameters — Do not guess symbol, side, or size. If unclear, ask the user for: symbol (e.g. BTC_USDT), side (BUY/SELL), type (MARKET/LIMIT), and amount or size.
2. Prefer dry-run then confirm — For any write (new order, cancel, cancel_all), run with --dry-run first when supported, show the user what would be done, then ask for confirmation before running without --dry-run.
3. Do not increase risk without telling the user — No larger size, no extra orders, without explicit user agreement.
4. On errors — Explain and suggest next steps (e.g. adjust size to min, or check balance).

---

3. Balance-aware order flow

When the user asks to buy with a quote amount (e.g. “buy BTC with 1000 USDT”):

1. Check balance

   pionex-trade-cli account balance
   

   From the JSON result, read the available balance for the quote asset (e.g. USDT). There is no --asset flag; the command returns all currencies.

2. Compare to requested amount

   • If available < requested: do not place the order. Tell the user the available balance and requested amount; suggest reducing amount or skipping.
   • If available ≥ requested: proceed with order flow (still prefer dry-run + user confirm).

3. Example

   • User: “Buy BTC with 1000 USDT.”
   • Agent: run pionex-trade-cli account balance → if USDT available is 600, reply: “Your available USDT is 600, less than 1000. Should I place a market buy for 600 USDT instead? I’ll use --dry-run first.”
   • Only after user confirms, run e.g. pionex-trade-cli orders new --symbol BTC_USDT --side BUY --type MARKET --amount 600 (and optionally run with --dry-run first, then without after confirm).

---

4. Min size / “amount too small” errors

If the API returns an error about minimum order size or notional (e.g. minimum notional 10 USDT):

1. Get symbol rules

   pionex-trade-cli market symbols --symbols BTC_USDT
   

   Use the result to see min size, min notional, step size.

2. Suggest a valid size — Round to the required precision and ensure notional ≥ min notional. Explain to the user: original request, exchange minimum, and suggested size.

3. Confirm then retry — After user agrees, place the order again (prefer --dry-run first).

---

5. Order commands (exact CLI)

• Market buy (quote amount)
  pionex-trade-cli orders new --symbol BTC_USDT --side BUY --type MARKET --amount 100

• Market sell (base quantity)
  pionex-trade-cli orders new --symbol BTC_USDT --side SELL --type MARKET --size 0.01

• Limit order
  pionex-trade-cli orders new --symbol BTC_USDT --side BUY --type LIMIT --price 50000 --size 0.01

• Cancel one
  pionex-trade-cli orders cancel --symbol BTC_USDT --order-id 123456

• Cancel all for symbol
  pionex-trade-cli orders cancel_all --symbol BTC_USDT
  Before running, list what will be cancelled: pionex-trade-cli orders open --symbol BTC_USDT, then confirm with the user.

---

6. Cancel_all and batch actions

• Always preview — Before pionex-trade-cli orders cancel_all --symbol <s>, run pionex-trade-cli orders open --symbol <s> and show the user how many orders and for which symbol.
• Explicit confirmation — e.g. “This will cancel 3 open orders on BTC_USDT. Confirm?” Only then run without --dry-run if applicable.

---

7. Summary

• pionex-trade defines how to safely place and cancel spot orders using the pionex-trade-cli CLI.
• Use pionex-trade-cli account balance to check funds; use pionex-trade-cli market symbols (pionex-market) to respect min size/notional.
• Prefer --dry-run and user confirmation for writes. Never increase risk without the user’s explicit agreement.