bybit-trading

What this skill does

# Bybit Trading Skill

Trade on Bybit using natural language. Supports spot, linear perpetuals (USDT/USDC), inverse contracts, options, and earn products.

### Rule Priority

When rules in this skill conflict, follow this order: **Safety > User Responsiveness > Convenience**. For example, never skip confirmation to be faster; never block the user's first request to run an auto-update check.

### Auto Update (MUST follow at session start)

This skill supports self-update with integrity verification. At the start of each new session, launch the update check as a **background sub-agent** so it never blocks the user's first request:

```
FOREGROUND (main agent — immediate):
1. Respond to the user's request using the current local version. Do NOT wait for the update check.

BACKGROUND (sub-agent — parallel):
1. LOCAL_VERSION = metadata.version  (from YAML frontmatter above)
2. SKILL_DIR = directory where this SKILL.md is located
3. MANIFEST = curl -sf -H "User-Agent: bybit-skill/1.4.1" https://api.bybit.com/skill/manifest
   (returns JSON: {"version":"x.y.z", "files":{"SKILL.md":"sha256:...","modules/market.md":"sha256:...",...}})
4. If fetch fails: return {status: "error", reason: "fetch_failed"}
5. Path validation: For each file in manifest.files, reject the entire update if ANY path:
   - Does not match `SKILL.md` or `modules/<name>.md` (where <name> is [a-z0-9-]+)
   - Contains `..`, starts with `/` or `~`, contains backslashes, or has a non-.md extension
   If any path is invalid: return {status: "error", reason: "invalid_path", path: "<rejected>"}
6. Version comparison (semver): split by ".", compare major → minor → patch numerically.
   If manifest.version > LOCAL_VERSION:
   a. For each file in manifest.files:
      - Download: curl -sf -H "User-Agent: bybit-skill/1.4.1" https://raw.githubusercontent.com/bybit-exchange/skills/main/<file>
      - Save content to temp file, then compute SHA256: shasum -a 256 <temp_file> | awk '{print $1}'
      - Compare with manifest checksum (strip "sha256:" prefix)
      - If mismatch: ABORT entire update. return {status: "error", reason: "checksum_mismatch", file: "<file>"}
      - If match: save to SKILL_DIR/.skill-update-tmp/<file>
   b. ALL files verified → move from temp to SKILL_DIR:
      - For each file: mkdir -p parent dir, then mv .skill-update-tmp/<file> SKILL_DIR/<file>
      - rm -rf SKILL_DIR/.skill-update-tmp/
   c. return {status: "updated", from: LOCAL_VERSION, to: manifest.version}
   If manifest.version == LOCAL_VERSION:
   d. return {status: "current"}

WHEN SUB-AGENT COMPLETES (main agent receives result):
- If status="updated": notify user "Skill updated from {from} to {to}. Using latest version." Re-read updated SKILL.md.
- If status="current" or status="error": silently continue with current version.
- Cache manifest (if returned) in session memory for module loading (see Module Router).
```

**Rules:**
- Check at most ONCE per session. Do not re-check during the same conversation.
- If any network request fails (timeout, 404, etc.), skip silently and proceed with current version. (See Graceful Degradation below for unified fallback rules.)
- **Never block the user's first request.** The sub-agent runs in the background; the main agent responds immediately. If a module is needed before the sub-agent finishes, use the current local version.
- If checksum algorithm prefix is not "sha256:", refuse the update (fail closed).

---

## Quick Start

### Step 1: Get an API Key

1. Log in to [Bybit](https://www.bybit.com) → API Management → Create New Key
2. Permissions: enable **Read + Trade only** (NEVER enable Withdraw for AI use)
3. Recommended: bind your IP address (makes the key permanent; otherwise expires in 3 months)
4. **Strongly recommended**: Create a dedicated **sub-account** for AI trading with limited balance

### Step 2: Configure Credentials

Credential setup depends on where the AI runs. Auto-detect the environment and follow the matching path:

**Path A — Local CLI** (Claude Code, Cursor, or any tool with shell access):

Copy-paste this into `~/.zshrc` or `~/.bashrc`:

```bash
export BYBIT_API_KEY="your_api_key"
export BYBIT_API_SECRET="your_secret_key"
export BYBIT_ENV="testnet"  # or "mainnet"
```

> **Using an RSA API Key instead?** (Self-generated: you uploaded a public key to Bybit and kept the private key locally.) Replace the `BYBIT_API_SECRET` line with:
> ```bash
> export BYBIT_API_PRIVATE_KEY_PATH="/absolute/path/to/private.pem"
> ```
> Everything else stays the same. Do NOT set both `BYBIT_API_SECRET` and `BYBIT_API_PRIVATE_KEY_PATH` — the skill will pick RSA if both are present, but it's clearer to keep only the one you actually use.

On first use, check if these environment variables exist. If they do, use them directly — do NOT ask the user to paste keys in the conversation. If they don't exist, guide the user to set them up:

1. Tell the user: "For security, I recommend storing your API keys as environment variables instead of pasting them here."
2. Provide the export commands above
3. After the user has set them, verify with `echo $BYBIT_API_KEY | head -c5` (only show first 5 chars to confirm)

**Path B — Self-hosted OpenClaw** (user runs OpenClaw on their own machine/server):

Keys stay on the user's machine — same security level as Path A. Configure via `.env` file:

Paste into `~/.openclaw/.env` (recommended) or `./.env` in your working directory:

```
BYBIT_API_KEY=your_api_key
BYBIT_API_SECRET=your_secret_key
BYBIT_ENV=testnet
```

> **Using an RSA API Key instead?** Replace the `BYBIT_API_SECRET` line with:
> ```
> BYBIT_API_PRIVATE_KEY_PATH=/absolute/path/to/private.pem
> ```
> Everything else stays the same. Only set one of `BYBIT_API_SECRET` or `BYBIT_API_PRIVATE_KEY_PATH`, not both.

Alternative: `openclaw.json` env block — `{ "env": { "vars": { "BYBIT_API_KEY": "...", "BYBIT_API_SECRET": "...", "BYBIT_ENV": "testnet" } } }` (swap `BYBIT_API_SECRET` for `BYBIT_API_PRIVATE_KEY_PATH` if using RSA).

On first use, check if these environment variables exist. If they do, use them directly. If they don't, guide the user to create `~/.openclaw/.env` with the variables above.

**Path C — Cloud platforms** (hosted OpenClaw, Claude.ai, ChatGPT, Gemini, and other hosted AI services):

These platforms have no secret store. Keys must be pasted in the conversation (sent to AI provider's servers).

On first use:
1. Accept keys pasted in the conversation
2. Warn once: "Your keys will be sent through this platform's servers. For safety, use a **sub-account with limited balance** and **Read+Trade permissions only** (no Withdraw)."
3. Do NOT ask again in the same session

**Fallback (all platforms)**: If the user provides keys directly in the conversation, accept them but remind once about the more secure alternative for their platform.

**Display rules** (never show full credentials):
- API Key: show first 5 + last 4 characters (e.g., `AbCdE...x1y2`)
- Secret Key: show last 5 only (e.g., `***...vWxYz`)
- **Code blocks (CRITICAL)**: NEVER include raw API Key or Secret Key values in generated code, scripts, or curl examples — even if the actual values are available in environment variables or session context. ALWAYS use `$BYBIT_API_KEY` / `$BYBIT_API_SECRET` (or `${API_KEY}` / `${SECRET_KEY}`) as variable references. This applies to ALL output formats including bash, python, and JSON. Violation of this rule is a **security incident**.

### Step 3: Verify Connection (auto-run on first use)

After credentials are configured, automatically run these checks:

**0. Determine sign type (no network call):**

```
If $BYBIT_API_PRIVATE_KEY_PATH is set:
  - Expand leading ~/ to absolute path
  - If file exists, is readable, and its first line contains "PRIVATE KEY":
      → Select RSA (X-BAPI-SIGN-TYPE: 2) for all subsequent requests
  - Else:
      → Halt. Tell user: "Private key path set but file unreadable: <path>"
        Do NOT silently fall back to HMAC.
Else if $BYBIT_API_SE