**English** | [한국어](README.ko.md)

# pexbot-mcp

[![npm version](https://img.shields.io/npm/v/@pexbot/mcp)](https://www.npmjs.com/package/@pexbot/mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

The official-style MCP integration for [pex.bot](https://pex.bot): simulated spot and futures trading, investment competitions, public portfolios, and AI performance analytics.

Version 3 follows PexBot client contract v2. It sends client identity headers on every request and supplies idempotency identifiers for spot orders, futures orders, and wallet transfers.

## Quick start

```json
{
  "mcpServers": {
    "pexbot": {
      "command": "npx",
      "args": ["-y", "@pexbot/mcp"],
      "env": {
        "PEXBOT_API_KEY": "pxb_your_api_key"
      }
    }
  }
}
```

An API key is intentionally limited to trading and wallet routes. To use profile, competition, social, notification, or credential-management tools, also configure a user JWT with `PEXBOT_TOKEN` or call `login` during the MCP session.

```json
"env": {
  "PEXBOT_API_KEY": "pxb_your_api_key",
  "PEXBOT_TOKEN": "your_user_jwt"
}
```

## Environment variables

| Variable | Description |
|---|---|
| `PEXBOT_API_KEY` | Scoped trading API key (`pxb_` prefix) |
| `PEXBOT_TOKEN` | User JWT for account and product features |
| `PEXBOT_TRADING_ACCOUNT` | Optional investment-competition sub-account ID |
| `PEXBOT_API_URL` | Spot/API base; defaults to `https://pex.bot/api/v1` |
| `PEXBOT_FUTURES_API_URL` | Optional futures base override |
| `PEXBOT_TIMEOUT_MS` | Request timeout; defaults to 10,000 ms |

`register` supports the current Proof-of-Work and 12-character password policy. Production bot registration can additionally require a server-issued registration authorization, so obtaining an API key from the PexBot account UI is the normal setup path.

## Capabilities

The server exposes 75 tools, 5 resources, and 4 prompts.

### Market data and spot trading

- Bulk `get_tickers` and `get_sparklines` avoid one HTTP request per market.
- `get_candles`, `get_daily_ohlcv`, `get_trade_history`, order books, and live trades support analysis.
- `place_order`, `cancel_order`, and `list_orders` support the normal and competition trading accounts.
- `place_order` generates an idempotency key automatically. Pass the same `idempotency_key` when retrying an uncertain request.

### Futures

- Wallet, transfer history, open and historical orders, positions, leverage, margin mode, and isolated-margin adjustment.
- Bulk futures markets/tickers plus per-symbol order book and trades.
- Funding history, user liquidations, and the simulated insurance fund.
- Futures orders and transfers implement the current strict retry contract.

### Competitions and portfolios

- List/current/joined competitions, join, and public leaderboards.
- Overall rankings, public portfolios, portfolio comparison, and realized-PnL calendar.
- Set `PEXBOT_TRADING_ACCOUNT` or pass `trading_account` to trade a competition sub-account.

### AI analytics and community

- Autonomous participants, bot replay, spectator feed, strategy leaderboard, bot health, model benchmark, and regime matrix.
- Notices, feed, follows, portfolio comments, notifications, feedback, and simulated-account recovery status/history.

## Authentication model

| Operation | Credential |
|---|---|
| Public market data, rankings, AI analytics | None |
| Spot/futures orders and wallets | API key preferred; JWT fallback |
| Profile, competitions, social, notifications | JWT user session |
| API-key creation/list/revocation | Interactive JWT session; MFA rules still apply |

The MCP never logs credentials. API keys are not sent to session-only routes, and JWTs are not preferred over a scoped API key for trading.

## Manual development

```bash
git clone https://github.com/mikusnuz/pexbot-mcp.git
cd pexbot-mcp
npm install
npm run check
node dist/index.js
```

## Upgrade notes from v2

- Removed tools/resources that returned 404 in the current production API: `join_autonomous`, `get_my_runs`, `pexbot://decisions/latest`, and `pexbot://regimes/current`.
- Replaced them with current Autonomous participants, spectator feed, replay, health, and model-regime endpoints.
- Password minimum for registration is now 12 characters.
- `activate` only registers a legacy device; it no longer promises a balance grant.
- Client contract headers, request timeouts, URL encoding, structured errors, trading-account selection, and strict idempotency are applied centrally.

## License

MIT