---
name: bybit
description: Check Bybit account — wallet balance, open positions, orders, fees, and transactions. Read-only, no trading.
version: 1.0.0
category: finance
dependencies:
  - pybit (pip install pybit)
  - requests (pip install requests)
tools:
  - terminal
---

# Bybit Account Checker

Read-only access to a Bybit Unified Trading Account via the V5 API.

## Quick Start

Run the helper script at `scripts/bybit_check.py`:

```
python3 ~/.hermes/skills/bybit/scripts/bybit_check.py <command>
```

## Commands

| Command        | Description                                          |
|----------------|------------------------------------------------------|
| `overview`     | Portfolio summary — equity, balances, open positions |
| `balance`      | Detailed wallet balance per coin                     |
| `positions`    | All open positions (linear + inverse + spot)         |
| `orders`       | Open/active orders across all categories             |
| `fees [SYMBOL]`| Fee rates (optionally for a specific symbol)         |
| `transactions` | Recent transaction log                               |
| `earn`         | Earn product balances                                |
| `p2p TOKEN CUR sell\|buy` | P2P ad rates (e.g. `p2p USDT ARS sell`) |

## Examples

```bash
# Quick portfolio check
python3 ~/.hermes/skills/bybit/scripts/bybit_check.py overview

# Detailed coin breakdown
python3 ~/.hermes/skills/bybit/scripts/bybit_check.py balance

# What positions are open?
python3 ~/.hermes/skills/bybit/scripts/bybit_check.py positions

# Any pending orders?
python3 ~/.hermes/skills/bybit/scripts/bybit_check.py orders

# Fee rates for BTCUSDT
python3 ~/.hermes/skills/bybit/scripts/bybit_check.py fees BTCUSDT
```

## Credentials

Stored in the script defaults. Override with env vars if needed:

```bash
export BYBIT_API_KEY="..."
export BYBIT_API_SECRET="..."
```

The key is **read-only** — Contracts Orders/Positions, Unified Trading, SPOT, Wallet, Exchange, Earn, P2P — all scoped to read-only.

## API Details

- **API Version:** V5 (Unified Trading Account)
- **SDK:** pybit (official Python SDK by Bybit)
- **Auth:** HMAC-SHA256, handled automatically by pybit
- **Base URL:** https://api.bybit.com

### Key Endpoints Used

| Endpoint                          | Auth         | Purpose                  |
|-----------------------------------|--------------|--------------------------|
| `GET /v5/account/wallet-balance`  | pybit        | Wallet balance (UNIFIED) |
| `GET /v5/position/list`           | pybit        | Open positions           |
| `GET /v5/order/realtime`          | pybit        | Active/open orders       |
| `GET /v5/account/fee-rate`        | pybit        | Trading fee rates        |
| `GET /v5/account/transaction-log` | pybit        | Transaction history      |
| `GET /v5/earn/position`           | raw HMAC     | Staked earn positions (FlexibleSaving, OnChain) |
| `GET /v5/earn/product`            | raw HMAC     | Available earn products  |

**Earn categories:** `FlexibleSaving`, `OnChain`. These endpoints require `category` param and are NOT in pybit — must use raw HMAC-signed requests.

## Notes

- The UNIFIED account type is used (Bybit's standard for V5).
- Positions are queried for linear (USDT-margined), inverse (coin-margined), and spot categories.
- The `overview` command gives the fastest summary — use it for quick checks.
- Earn queries use raw HMAC-signed requests (pybit doesn't support earn endpoints).
- The `earn` command shows your staked positions + top available flexible savings by APR.
- If Bybit adds new categories or changes response fields, update `bybit_check.py` accordingly.

## Extending

### Using pybit (preferred when available)

```python
from pybit.unified_trading import HTTP
session = HTTP(testnet=False, api_key=API_KEY, api_secret=API_SECRET)

result = session.get_wallet_balance(accountType="UNIFIED")
# result is a dict with retCode, retMsg, result keys
```

### Using raw HMAC (when pybit lacks the endpoint)

pybit doesn't cover all V5 endpoints (e.g., earn). Use `signed_get()` from the script:

```python
import time, hmac, hashlib, requests as req

def signed_get(endpoint, query=""):
    ts = str(int(time.time() * 1000))
    recv = "10000"
    sig_payload = ts + API_KEY + recv + query
    sig = hmac.new(API_SECRET.encode(), sig_payload.encode(), hashlib.sha256).hexdigest()
    headers = {
        "X-BAPI-API-KEY": API_KEY,
        "X-BAPI-TIMESTAMP": ts,
        "X-BAPI-RECV-WINDOW": recv,
        "X-BAPI-SIGN": sig,
    }
    url = BASE_URL + endpoint
    if query:
        url += "?" + query
    return req.get(url, headers=headers, timeout=10).json()

# Signature formula: HMAC_SHA256(timestamp + api_key + recv_window + queryString)
# For GET with no query: HMAC_SHA256(timestamp + api_key + recv_window)
```

For write operations: **do not add** — this skill is deliberately read-only.