fix(gmx-v2): pre-flight checks for balance, collateral, ETH fee (v0.2.1)

[GeoGu360]

Problem

Orders were silently created on-chain then immediately cancelled by the GMX keeper because post-fee collateral fell below the minCollateralUsd threshold ($1.00 on Arbitrum). The error (0xc4bc1211) was visible in the OrderCancelled event but not surfaced to the user — the skill returned ok: true with a tx hash, misleading agents into thinking the position had opened.

Changes

Pre-flight checks in open-position (fail fast with structured JSON)

1. ERC-20 token balance — checks wallet holds enough collateral token before building any calldata
2. GMX minCollateralUsd — queries DataStore on-chain (getUint(0x6497f0...)), estimates 0.1% open fee, aborts if collateral_after_fee < minCollateralUsd
3. ETH execution fee — checks wallet ETH balance ≥ execution_fee + 0.0002 ETH gas buffer

All three return {"ok": false, "error": "<CODE>", "reason": "...", "suggestion": "..."} instead of throwing exceptions, so calling agents can parse and act on them.

get-orders cleanup

Removed "raw" hex field from output (was leaking the full RPC response).

Error codes

Code	Trigger
INSUFFICIENT_TOKEN_BALANCE	wallet collateral balance < --collateral-amount
INSUFFICIENT_COLLATERAL	post-fee collateral < GMX minCollateralUsd
INSUFFICIENT_ETH_FOR_EXECUTION	ETH balance < execution fee + gas buffer

Version

0.2.0 → 0.2.1 (patch: bugfix + pre-flight guards)

Checklist

• cargo build passes (no warnings)
• plugin-store lint passes
• Version bumped in all 4 files
• SKILL.md updated with new Flow steps and error JSON examples
• api_calls unchanged (no new external domains)
• diff scoped to skills/gmx-v2/ only

🤖 Generated with Claude Code

[github-actions]

🔨 Phase 2: Build Verification — ✅ PASSED

Plugin: gmx-v2 | Language: rust
Source: @

Compiled from developer source code by our CI. Users install our build artifacts.

Build succeeded. Compiled artifact uploaded as workflow artifact.

---

Source integrity: commit SHA `` is the content fingerprint.

[github-actions]

Phase 4: Summary + Pre-flight for gmx-v2

Review below. AI Code Review is in a separate check.

---

SUMMARY.md

gmx-v2

Trade perpetuals and spot on GMX V2 with leveraged positions, limit/stop orders, and GM pool liquidity management on Arbitrum and Avalanche.

Highlights

• Open/close leveraged perpetual positions (long/short) on GMX V2
• Place conditional orders (limit, stop-loss, take-profit)
• Add/remove liquidity to GM pools for yield generation
• Support for Arbitrum and Avalanche networks
• Real-time market data and position monitoring
• Automatic slippage protection and fee estimation
• Pre-flight balance and collateral validation
• Keeper-based execution model with 1-30 second delays

SKILL_SUMMARY.md

gmx-v2 -- Skill Summary

Overview

This skill enables trading perpetual futures and managing liquidity on GMX V2, a leading decentralized perpetuals exchange. Users can open leveraged long/short positions, place conditional orders, and participate in GM liquidity pools on Arbitrum and Avalanche networks. The plugin handles all complex interactions with GMX's keeper-based execution model, providing safety checks and clear confirmation flows.

Usage

Connect your wallet with onchainos wallet login, then use commands like gmx-v2 open-position for trading or gmx-v2 deposit-liquidity for LP operations. Always run with --dry-run first to preview transactions before execution.

Commands

Command	Description
list-markets	View active GMX V2 markets with liquidity and rates
get-prices	Get current oracle prices for all tokens
get-positions	Query open perpetual positions
get-orders	Query pending conditional orders
open-position	Open leveraged long/short position
close-position	Close existing position (full or partial)
place-order	Place limit/stop-loss/take-profit orders
cancel-order	Cancel pending conditional order
deposit-liquidity	Add liquidity to GM pools
withdraw-liquidity	Remove liquidity from GM pools
claim-funding-fees	Claim accrued funding fee income

Triggers

Activate when users want to trade perpetuals with leverage, manage GMX positions, place stop-losses or take-profits, or participate in GMX liquidity mining. Common phrases include "open position GMX", "GMX leverage", "GMX stop loss", or "deposit GM pool".

Auto-injected Pre-flight

## Pre-flight Dependencies (auto-injected by Plugin Store CI)

> Run once per session before first use. These checks ensure required tools are installed.

### Install onchainos CLI + Skills (auto-injected)

```bash
# 1. Install onchainos CLI
onchainos --version 2>/dev/null || curl -fsSL https://raw.githubusercontent.com/okx/onchainos-skills/main/install.sh | sh

# 2. Install onchainos skills (enables AI agent to use onchainos commands)
npx skills add okx/onchainos-skills --yes --global

# 3. Install plugin-store skills (enables plugin discovery and management)
npx skills add okx/plugin-store --skill plugin-store --yes --global

Install gmx-v2 binary (auto-injected)

if ! command -v gmx-v2 >/dev/null 2>&1; then
  OS=$(uname -s | tr A-Z a-z)
  ARCH=$(uname -m)
  EXT=""
  case "${OS}_${ARCH}" in
    darwin_arm64)  TARGET="aarch64-apple-darwin" ;;
    darwin_x86_64) TARGET="x86_64-apple-darwin" ;;
    linux_x86_64)  TARGET="x86_64-unknown-linux-gnu" ;;
    linux_i686)    TARGET="i686-unknown-linux-gnu" ;;
    linux_aarch64) TARGET="aarch64-unknown-linux-gnu" ;;
    linux_armv7l)  TARGET="armv7-unknown-linux-gnueabihf" ;;
    mingw*_x86_64|msys*_x86_64|cygwin*_x86_64)   TARGET="x86_64-pc-windows-msvc"; EXT=".exe" ;;
    mingw*_i686|msys*_i686|cygwin*_i686)           TARGET="i686-pc-windows-msvc"; EXT=".exe" ;;
    mingw*_aarch64|msys*_aarch64|cygwin*_aarch64)  TARGET="aarch64-pc-windows-msvc"; EXT=".exe" ;;
  esac
  mkdir -p ~/.local/bin
  curl -fsSL "https://github.com/okx/plugin-store/releases/download/plugins/gmx-v2@0.2.1/gmx-v2-${TARGET}${EXT}" -o ~/.local/bin/gmx-v2${EXT}
  chmod +x ~/.local/bin/gmx-v2${EXT}
fi

Report install (auto-injected, runs once)

REPORT_FLAG="$HOME/.plugin-store/reported/gmx-v2"
if [ ! -f "$REPORT_FLAG" ]; then
  mkdir -p "$HOME/.plugin-store/reported"
  # Device fingerprint → SHA256 → 32-char device ID
  DEV_RAW="$(hostname):$(uname -s):$(uname -m):$HOME"
  DEV_ID=$(echo -n "$DEV_RAW" | shasum -a 256 | head -c 32)
  # HMAC signature (obfuscated key, same as CLI binary)
  _K=$(echo 'OE9nNWFRUFdfSVJkektrMExOV2RNeTIzV2JibXo3ZWNTbExJUDFIWnVoZw==' | base64 -d 2>/dev/null || echo 'OE9nNWFRUFdfSVJkektrMExOV2RNeTIzV2JibXo3ZWNTbExJUDFIWnVoZw==' | openssl base64 -d)
  HMAC_SIG=$(echo -n "${_K}${DEV_ID}" | shasum -a 256 | head -c 8)
  DIV_ID="${DEV_ID}${HMAC_SIG}"
  unset _K
  # Report to Vercel stats
  curl -s -X POST "https://plugin-store-dun.vercel.app/install" \
    -H "Content-Type: application/json" \
    -d '{"name":"gmx-v2","version":"0.2.1"}' >/dev/null 2>&1 || true
  # Report to OKX API (with HMAC-signed device token)
  curl -s -X POST "https://www.okx.com/priapi/v1/wallet/plugins/download/report" \
    -H "Content-Type: application/json" \
    -d '{"pluginName":"gmx-v2","divId":"'"$DIV_ID"'"}' >/dev/null 2>&1 || true
  touch "$REPORT_FLAG"
fi

---

</details>

---
*Generated by Plugin Store CI after maintainer approval.*