Metadata-Version: 2.4
Name: btse-mcp
Version: 0.1.3
Summary: MCP server for the BTSE Futures API
License: MIT License
        
        Copyright (c) 2025 btse-mcp contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/xbotlive/btse-mcp
Project-URL: Repository, https://github.com/xbotlive/btse-mcp
Project-URL: Issues, https://github.com/xbotlive/btse-mcp/issues
Project-URL: Changelog, https://github.com/xbotlive/btse-mcp/blob/main/CHANGELOG.md
Keywords: btse,mcp,futures,trading,crypto,claude,ai-agent
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: cryptography>=42.0.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"
Dynamic: license-file

# btse-mcp

MCP server for the [BTSE](https://btse.com) Futures API. Enables AI agents (Claude Desktop, Cursor,
LangChain) to query market data, manage positions, and place orders on BTSE via natural language.

---

## Prerequisites

- **Python 3.11 or higher** — check with `python --version`
- **pip** — check with `pip --version`
- A BTSE account (testnet or live)

> **Multiple Python versions (Anaconda etc):** use the full path explicitly:
> ```bash
> /usr/local/bin/python3.14 -m pip install -e .
> /Library/Frameworks/Python.framework/Versions/3.14/bin/btse-mcp --help
> ```
> Use that same full path in the Claude Desktop config (Step 4).

---

## Step 1 — Get API keys from BTSE

### Testnet (recommended first)

1. Register at https://testnet.btse.io
2. Go to **Account → API tab → New API**
3. Save the **API Key** and **Passphrase** — the passphrase is shown only once and is your `api_secret`
4. Set permissions: **Read** + **Trading** (add Transfer if needed)

### Live

Same steps at https://btse.com

---

## Step 2 — Install

```bash
# Clone the repo
git clone https://github.com/xbotlive/btse-mcp.git
cd btse-mcp

# Install — adds `btse-mcp` command to your PATH
pip install -e .

# Verify
btse-mcp --help
```

> **Virtualenv users:** if `btse-mcp` is not found after install, use the full path:
> - macOS/Linux: `~/.venv/bin/btse-mcp`
> - Windows: `~\.venv\Scripts\btse-mcp.exe`
>
> You will need this full path in the Claude Desktop config (Step 4).

---

## Step 3 — Configure accounts

```bash
# Add a testnet account
btse-mcp config --account-id testnet
# Prompts:
#   API Key    → paste your API key
#   API Secret → paste your passphrase (input is hidden)
#   Use testnet? [y/N] → y

# Verify the connection — should print BTC-PERP last price
btse-mcp test testnet

# Add your live account when ready
btse-mcp config --account-id main
# Same prompts — answer 'n' to testnet

# See all configured accounts
btse-mcp list
```

Credentials are stored encrypted at `~/.config/btse-mcp/accounts.enc`.

> **Unified Futures Wallet:** If your BTSE account has been upgraded to the Unified Futures Wallet (all accounts from late 2024 onwards), account endpoints automatically use the v2.2 API. No action needed.

---

## Step 4 — Connect to Claude Desktop

```bash
btse-mcp install-claude
```

This auto-writes the correct config for your OS and creates the file if it doesn't exist. Then **restart Claude Desktop**.

> **Manual alternative:** if the command fails, add this to your config file directly:
>
> | OS      | Path |
> |---------|------|
> | macOS   | `~/Library/Application Support/Claude/claude_desktop_config.json` |
> | Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
> | Linux   | `~/.config/Claude/claude_desktop_config.json` |
>
> ```json
> {
>   "mcpServers": {
>     "btse": {
>       "command": "btse-mcp",
>       "args": ["start"]
>     }
>   }
> }
> ```
>
> **Virtualenv users:** replace `"btse-mcp"` with the full path, e.g.:
> ```json
> "command": "/Users/yourname/.venv/bin/btse-mcp"
> ```

Open a new chat in Claude Desktop — you should see a tools icon (🔧) in the input bar.

**Test it:**
> "What is the BTC-PERP mark price on BTSE using account testnet?"

---

## Step 5 — Connect to Cursor

Open Cursor → **Settings → MCP → Add Server** and enter:

```json
{
  "name": "btse",
  "command": "btse-mcp",
  "args": ["start"]
}
```

Then use natural language in Cursor chat:
> "Show my open BTSE positions"
> "Place a limit buy on BTC-PERP at 60000 size 1 using account testnet"

---

## Alternative: run without installing

```bash
# From the repo root, no pip install required
python -m btse_mcp start
```

---

## Tool list

| Tool | Description |
|------|-------------|
| `btse_get_market_summary` | Market summary for one or all symbols |
| `btse_get_price` | Mark / index / last price |
| `btse_get_orderbook` | L2 orderbook snapshot |
| `btse_get_trades` | Recent public trade fills |
| `btse_get_ohlcv` | OHLCV candlestick data |
| `btse_get_funding_history` | Historical funding rates |
| `btse_get_wallet_balance` | Futures wallet balance |
| `btse_get_positions` | Open positions |
| `btse_get_account_fees` | Maker / taker fee rates |
| `btse_get_leverage` | Current leverage for a market |
| `btse_create_order` | Place LIMIT / MARKET / OCO order (supports TP/SL) |
| `btse_cancel_order` | Cancel by order ID, or cancel all for a symbol |
| `btse_get_open_orders` | List open orders |
| `btse_get_order` | Single order detail |
| `btse_get_trade_history` | User trade history |
| `btse_amend_order` | Amend price / size / trigger price |
| `btse_close_position` | Close position at market or limit |
| `btse_set_leverage` | Set leverage (isolated or cross) |
| `btse_get_risk_limit` | Get risk limit tier |

All tools accept an optional `account_id` parameter (defaults to `"default"`).
Pass `"account_id": "testnet"` to route to your testnet account.

---

## Multi-account usage

```bash
btse-mcp list           # list all configured accounts
btse-mcp test main      # test a specific account
```

In prompts, specify the account explicitly:
> "Using account testnet, show my BTC-PERP position"

---

## Symbol naming

Use new-style perpetual names: `BTC-PERP`, `ETH-PERP`, `SOL-PERP`, etc.

---

## Auth

BTSE uses **HMAC-SHA384**. The signature is:

```
HMAC-SHA384(api_secret, url_path + nonce + request_body)
```

Sent via headers: `request-api`, `request-nonce`, `request-sign`.
See `docs/integration.md` for full details and worked examples.

---

## Running tests

```bash
pip install pytest
pytest -v
```

Auth signature tests run against the worked examples in the BTSE docs — no live API connection needed.

---

## Troubleshooting

| Problem | Fix |
|---------|-----|
| `btse-mcp: command not found` | Use full path or activate your virtualenv |
| `401 Unauthorized` | Check API key and secret are copied correctly |
| `Connection failed` | Confirm testnet flag matches the account you created on |
| Tools icon missing in Claude Desktop | Check JSON syntax in config file, restart Claude Desktop |
| `ModuleNotFoundError: mcp` | Run `pip install -e .` again from the repo root |
| `33000001: Unsupported API` | Your account uses the Unified Futures Wallet — the server auto-retries on v2.2, restart Claude Desktop |
| `btse-mcp test` works but account tools fail | Restart Claude Desktop after any config or code change |

---

## Disclaimer

Futures trading involves significant risk of loss. Always test on testnet before using live credentials.
Never commit API keys to version control — they are stored encrypted locally and excluded via `.gitignore`.
