# Bit2Me MCP Server - Technical Documentation

> Generated on 2026-05-13T14:23:08.115Z


==================================================
FILE: README.md (README / Documentation)
==================================================

# Bit2Me MCP Server

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server to interact with the [Bit2Me](https://bit2me.com/) ecosystem. This server allows AI assistants like Claude to access real-time market data, manage wallets, execute trading operations, and query products like Earn and Loans.

For more information, visit: **[https://mcp.bit2me.com](https://mcp.bit2me.com)**

**Bit2Me** is a leading cryptocurrency exchange based in Spain, offering a wide range of services including trading, staking (Earn), and loans. This MCP server acts as a bridge, enabling LLMs to perform actions and retrieve data securely from your Bit2Me account.

## 🚀 Features

- **General**: Asset information, account details, portfolio valuation, and self-introspection (`general_describe_tool` returns description, schema, and examples for any tool — useful for LLMs encountering a tool for the first time).
- **Wallet Management**: Query balances, transactions, and wallet (Pockets) details.
- **Pro Trading**: Manage orders (Limit, Market, Stop), query open orders, and transfer funds between Wallet and Pro.
- **Earn & Loans**: Manage Earn (Staking) strategies and collateralized loans.
- **Operations**: Execute trades, transfers, and withdrawals securely.
- **Idempotency & Retries**: Every write tool auto-generates an idempotency key; failed POST/DELETE calls retry with exponential backoff + jitter, making operations safe to retry without duplicates.
- **Decimal Precision**: Portfolio valuation uses `decimal.js` — no floating-point drift on large balances or high-precision assets.
- **Expanded PII Redaction**: Logs automatically scrub email addresses, IBANs, phone numbers, KYC fields, JWT-shaped tokens, and long base64 blobs, in addition to API keys and signatures.
- **Monotonic Nonces**: API-key signing uses a strictly-increasing nonce counter, preventing replay attacks even under high concurrency.
- **Audit Log**: Every write tool (order creation, withdrawals, earn deposits, loan operations, …) appends a tamper-evident JSON line on both success and failure. Set `AUDIT_LOG_PATH` to write to a dedicated file; otherwise audit lines are emitted via the logger with `audit: true`.
- **Parametrized Prompts**: `analyze_portfolio` and `market_summary` accept arguments. Three new prompts ship out of the box: `tax_report`, `dca_plan`, and `loan_health_check`.

## 🛠️ Available Tools & API Endpoints

The server currently exposes **48 tools** grouped as follows:

- 4 General tools (including `general_describe_tool` for self-introspection)
- 8 Broker (Simple Trading) tools
- 4 Wallet tools
- 14 Pro Trading tools
- 11 Earn (Staking) tools
- 7 Loan tools

Full descriptions, response schemas, Bit2Me REST endpoints and usage notes live in [`TOOLS_DOCUMENTATION.md`](./TOOLS_DOCUMENTATION.md).

## 📋 Documentation & Schemas

All tool responses are normalised for LLM consumption (consistent naming, flattened payloads, concise metadata). Use the following references when developing new tooling:

- **[`TOOLS_DOCUMENTATION.md`](./TOOLS_DOCUMENTATION.md)** – Auto-generated catalogue with descriptions, Bit2Me endpoints and response schemas for each tool.
- **[`data/tools.json`](./data/tools.json)** – Source metadata powering the landing page (includes request/response schemas and examples for each tool).

## ⚙️ Installation and Configuration

### Prerequisites

- **Node.js**: v20 or higher.
- **Bit2Me Account**: You need a verified Bit2Me account.

### 🔑 Authentication Methods

#### API Keys (Recommended)

The recommended way to authenticate is using API Keys. This method is secure, granular, and designed for programmatic access.

1. Go to your **[Bit2Me API Dashboard](https://app.bit2me.com/profile/api)**.
2. Click on **"New Key"**.
3. Select the permissions you need (e.g., Wallets, Trading, Earn, Loans).
    > **⚠️ Security Note:** This MCP server does **NOT** support crypto withdrawals to external blockchain addresses or transfers to other users. For security best practices, please **DO NOT** enable "Withdrawal" permissions on your API Key. Internal transfers between your own Bit2Me wallets (Wallet ↔ Pro ↔ Earn) are fully supported.

#### JWT Session Token (Alternative)

All tools support an optional `jwt` parameter for session-based authentication. This is useful for:

- **Multi-tenant applications**: Where each request is made on behalf of a different user.
- **Web integrations**: Where users are already authenticated via the Bit2Me web interface.

When the `jwt` parameter is provided, the server will use cookie-based authentication instead of API Keys.

```typescript
// Example: Using JWT session token
const result = await mcpClient.callTool("wallet_get_pockets", {
    symbol: "BTC",
    jwt: "user_session_token_here", // Optional - uses API keys if omitted
});
```

> **📝 Note:** API Keys are recommended for most use cases. The `jwt` parameter should only be used when building multi-tenant applications or web integrations where users have existing Bit2Me sessions.

### Steps

1. **Clone the repository:**

    ```bash
    git clone https://github.com/bit2me-devs/bit2me-mcp.git
    cd bit2me-mcp
    ```

2. **Install dependencies:**

    ```bash
    npm install
    ```

3. **Configure environment variables:**
   Create a `.env` file in the root directory:

    ```bash
    cp .env.example .env
    ```

    Edit `.env` and add your keys:

    ```env
    BIT2ME_API_KEY=YOUR_BIT2ME_ACCOUNT_API_KEY
    BIT2ME_API_SECRET=YOUR_BIT2ME_ACCOUNT_API_SECRET

    # Optional Configuration
    BIT2ME_GATEWAY_URL=https://gateway.bit2me.com  # Must be HTTPS (localhost/127.x are exempt)
    BIT2ME_REQUEST_TIMEOUT=30000     # Request timeout in ms (default: 30000)
    BIT2ME_MAX_RETRIES=3             # Max retries for rate limits (default: 3)
    BIT2ME_RETRY_BASE_DELAY=1000     # Base delay for backoff in ms (default: 1000)
    BIT2ME_LOG_LEVEL=info            # Log level: debug, info, warn, error (default: info)
    LOG_FORMAT=json                  # Optional: "json" for log aggregators; default is human-readable
    # AUDIT_LOG_PATH=/var/log/bit2me-mcp/audit.log  # Append-only write-tool audit log
    ```

    > **💡 QA/Staging:** Use `BIT2ME_GATEWAY_URL` to point to different environments (e.g., `https://qa-gateway.bit2me.com` for QA testing).

    > **🔒 File permissions:** The `.env` file holds API credentials. Restrict it to the owner only:
    >
    > ```bash
    > chmod 600 .env
    > ```
    >
    > A pre-commit hook (`.husky/check-env-perms.sh`) prints a warning when the local `.env` mode is more permissive than `600`.

4. **Build the project:**
    ```bash
    npm run build
    ```

## 🖥️ Usage with Claude Desktop

To use this server with the Claude Desktop application, add the following configuration to your `claude_desktop_config.json` file:

### MacOS

`~/Library/Application Support/Claude/claude_desktop_config.json`

### Windows

`%APPDATA%\Claude\claude_desktop_config.json`

```json
{
    "mcpServers": {
        "bit2me": {
            "command": "node",
            "args": ["/absolute/path/to/bit2me-mcp/build/index.js"],
            "env": {
                "BIT2ME_API_KEY": "YOUR_BIT2ME_ACCOUNT_API_KEY",
                "BIT2ME_API_SECRET": "YOUR_BIT2ME_ACCOUNT_API_SECRET"
            }
        }
    }
}
```

> **Note:** Replace `/absolute/path/to/...` with the actual full path to your project.

#### Using a Custom Gateway (QA/Staging)

For testing against different environments, add the `BIT2ME_GATEWAY_URL` variable:

```json
{
    "mcpServers": {
        "bit2me": {
            "command": "node",
            "args": ["/absolute/path/to/bit2me-mcp/build/index.js"],
            "env": {
                "BIT2ME_API_KEY": "YOUR_BIT2ME_ACCOUNT_API_KEY",
                "BIT2ME_API_SECRET": "YOUR_BIT2ME_ACCOUNT_API_SECRET",
                "BIT2ME_GATEWAY_URL": "https://qa-gateway.bit2me.com"
            }
        }
    }
}
```

## 🛡️ Security

### Security Policy

For detailed information about reporting vulnerabilities and our security policy, please see [SECURITY.md](./SECURITY.md).

### Best Practices

- **API Keys**: Never commit API keys to version control. The pre-commit hook runs `gitleaks` (if installed) to block accidental secret commits.
- **Permissions**: Use minimal permissions. Avoid "Withdrawal" permissions for MCP usage.
- **HTTPS Gateway**: `BIT2ME_GATEWAY_URL` is validated at startup — only `https://` URLs are accepted. Plain `http://` is rejected except for `localhost` / `127.x` addresses (local development only).
- **Monotonic Nonces**: API-key signing uses a strictly-increasing nonce counter so concurrent requests cannot generate replay-vulnerable signatures.
- **Expanded PII Redaction**: The logger scrubs API keys, signatures, JWTs, emails, IBANs, phone numbers, KYC fields, and long base64 blobs before writing any line to stderr.
- **Audit Log**: Every write tool appends an append-only JSON entry (tool name, sanitised args, outcome, correlation ID, SHA-256 fingerprint of the session token — never the token itself). Set `AUDIT_LOG_PATH` to persist to a file.

## ⚠️ Rate Limits & Error Handling

The Bit2Me API enforces rate limits to ensure stability.

- **429 Too Many Requests**: If the server hits a rate limit, it will **automatically retry** the request after a 1-second delay (up to 3 retries).
- **Console Warnings**: You may see warnings in the logs if rate limits are hit.
- **Best Practice**: Avoid asking for massive amounts of data in a very short loop.
- **Exponential Backoff**: The server now uses exponential backoff with jitter for retries to handle rate limits more gracefully.

## 📊 Logging

The server implements a structured logging system that automatically sanitizes sensitive data (API keys, signatures, JWTs, emails, IBANs, and other PII).
You can control the verbosity using the `BIT2ME_LOG_LEVEL` environment variable:

- `debug`: Detailed request/response logs (useful for development)
- `info`: Startup and operational events (default)
- `warn`: Rate limits and non-critical issues
- `error`: API errors and failures

Set `LOG_FORMAT=json` to switch the logger to a single-JSON-object-per-line format suitable for log aggregators (Loki, Datadog, CloudWatch, etc.). The default is human-readable.

All logs are written to **stderr**; stdout is reserved for the MCP JSON-RPC frame.

## 🧵 Concurrency Model

Each incoming tool call runs inside its own [`AsyncLocalStorage`](https://nodejs.org/api/async_context.html#class-asynclocalstorage) boundary. The store carries:

- `correlationId`: a UUID generated per request, included in every log line
- `sessionToken` (`jwt`): the optional per-call session token, never logged in the clear
- `toolName`, `startTime`: useful for metrics / audit

Two requests that arrive concurrently — for example two different users hitting the HTTP transport with their own JWTs — never share state. The legacy global-context fallbacks remain for unit tests that run outside a `runWithContext` boundary, but production code paths always create a context. See `tests/concurrency.test.ts` and `tests/http-transport.test.ts` for the regression coverage.

Per-request state stored via `memoizePerRequest()` (e.g. wallet pockets fetched multiple times during a single broker quote) is keyed by `correlationId` and cleared in the `finally` block of `executeTool()` so the cache cannot grow unbounded.

## 🚢 Operating in Production

Two binaries ship with this package:

- `bit2me-mcp-server` — the original stdio transport, designed to be spawned by a single LLM client (Claude Desktop, Cursor, …).
- `bit2me-mcp-http` — the multi-tenant HTTP/SSE transport (`src/index-http.ts`). Each request supplies its own credentials in headers (`X-Bit2Me-Api-Key` + `X-Bit2Me-Api-Secret` or `Authorization: Bearer <jwt>`). TLS termination is delegated to a reverse proxy.

Recommended environment variables for the HTTP binary:

- `MCP_HTTP_HOST` / `MCP_HTTP_PORT` (default `127.0.0.1:3000`)
- `MCP_HTTP_AUTH_MODE`: `api_key` (default), `jwt`, or `both`
- `LOG_FORMAT=json` for structured logs
- `AUDIT_LOG_PATH=/var/log/bit2me-mcp/audit.log` to ship audit lines to a file

### Choosing an auth mode (HTTP transport)

The HTTP transport accepts API-key credentials and Bit2Me session JWTs. Both
modes are first-class — the right choice depends on **where the server is
bound and who is calling it**, not on a one-size-fits-all rule. The full
threat model and rationale live in [`docs/adr/0001-valet-key-http-credentials.md`](./docs/adr/0001-valet-key-http-credentials.md).

| Topology                                                               | Recommended `MCP_HTTP_AUTH_MODE`                           | Why                                                                                    |
| ---------------------------------------------------------------------- | ---------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| stdio (Cursor, Claude Desktop, local CLI)                              | n/a — use `BIT2ME_API_KEY` / `BIT2ME_API_SECRET` in `.env` | Single-process, no network hop; scopes are enforced by the Bit2Me dashboard.           |
| HTTP bound to loopback (`127.0.0.1`, `::1`, `localhost`)               | `api_key`                                                  | Credentials never leave the host.                                                      |
| HTTP on a private network / VPN behind a TLS-terminating reverse proxy | `api_key`                                                  | Encrypted hop; scopes enforced by the Bit2Me dashboard; operator owns the proxy chain. |
| HTTP exposed on the public internet for a single operator              | `jwt`                                                      | Bit2Me JWTs auto-expire (~15 min); the leak window is shorter.                         |
| HTTP shared by multiple third-party integrators                        | `jwt`                                                      | Independent revocation per integrator without rotating the master credentials.         |

Hard rules that apply regardless of the mode you pick:

- **Mint API keys with the smallest scope** that satisfies the caller's use
  case. Read-only when possible. **Never enable Withdrawal scopes for MCP
  usage** — the MCP server intentionally does not support external withdrawals,
  so granting that permission only widens the blast radius of a leak.
- **Always put the HTTP transport behind TLS** on any non-loopback bind.
  Plain HTTP on `0.0.0.0` is a misconfiguration regardless of the auth mode.
- The server emits a startup `WARN` log if `api_key`/`both` is active on a
  non-loopback host so operators are nudged toward a TLS-terminating proxy or
  the JWT mode.
- Credential headers (`X-Bit2Me-Api-Key`, `X-Bit2Me-Api-Secret`,
  `Authorization`) are scrubbed from every structured log line before it
  reaches stderr.

Built-in observability endpoints (HTTP transport only):

- `GET /health` — liveness + Bit2Me reachability + cache/circuit-breaker/rate-limiter snapshot. Cached for 30s.
- `GET /metrics` — Prometheus text-format counters (`bit2me_mcp_tool_calls_total`, `bit2me_mcp_tool_errors_total`, `bit2me_mcp_tool_duration_avg_ms`).

Reliability features active by default:

- Circuit breaker on the upstream Bit2Me API (`src/utils/circuit-breaker.ts`).
- Per-endpoint rate limiter with exponential backoff + jitter.
- Idempotency keys on every write tool (`pro_create_order`, `loan_create`, `earn_deposit`, …) — the SDK auto-generates one if the caller doesn't supply `idempotency_key`.
- Monotonic request nonces for API-key signing (replay-safe even under high concurrency).
- Append-only audit log for every successful **and** failed write operation.

## ❓ Troubleshooting

### Error: "Connection refused"

- Ensure the MCP server is running.
- Check that the path in `claude_desktop_config.json` points correctly to the `build/index.js` file.

### Error: "API Key invalid" or "Unauthorized"

- Verify your keys in `.env` or the Claude config.
- Ensure your API keys have the necessary permissions (Wallet, Trade, Earn, etc.) enabled in the Bit2Me dashboard.
- Check that there are no extra spaces or quotes around the API key values.

### Error: "Rate limit exceeded" or 429 responses

- The Bit2Me API has rate limits. The server automatically retries with exponential backoff.
- If you're hitting rate limits frequently, reduce the number of concurrent requests.
- Consider adding delays between operations in your workflows.

### Tools not showing up in Claude

- Restart Claude Desktop completely (quit and reopen).
- Check the Claude Desktop logs for initialization errors.
- Verify the configuration file syntax is valid JSON.

### Error: "Request timeout"

- Check your internet connection.
- Increase `BIT2ME_REQUEST_TIMEOUT` in your environment variables (default: 30000ms).
- Some Bit2Me API endpoints may be temporarily slow.

### Environment variables not loading

- When using `npx`, environment variables must be set in the config file's `env` section.
- For local development, ensure the `.env` file is in the project root.
- The server prioritizes config-provided credentials over `.env` file values.

### Error: "Network error" or CORS issues

- The MCP server runs server-side and doesn't have CORS restrictions.
- Network errors usually indicate connectivity problems or API downtime.
- Check the Bit2Me status page or try again later.

### Debugging

- Run the server manually to see logs:
    ```bash
    npm run dev
    ```
- Set `BIT2ME_LOG_LEVEL=debug` for detailed logging.
- Check Claude Desktop logs:
    - macOS: `~/Library/Logs/Claude/mcp*.log`
    - Windows: `%APPDATA%\Claude\logs\mcp*.log`

## 🔍 Testing with MCP Inspector

[MCP Inspector](https://github.com/modelcontextprotocol/inspector) is the official debugging tool for MCP servers. It provides a web interface to test your tools, view responses, and debug issues.

### Installation

```bash
npm install -g @modelcontextprotocol/inspector
```

### Running the Inspector

You have two options to run the inspector:

#### Option A: Using NPM Package (Recommended)

Use the published package from npm - no build required:

```bash
export BIT2ME_API_KEY=YOUR_BIT2ME_ACCOUNT_API_KEY
export BIT2ME_API_SECRET=YOUR_BIT2ME_ACCOUNT_API_SECRET
npx -y @modelcontextprotocol/inspector npx @bit2me/mcp-server
```

#### Option B: Using Local Repository

For development or testing unreleased changes:

```bash
# 1. Clone and build the project
git clone https://github.com/bit2me-devs/bit2me-mcp.git
cd bit2me-mcp
npm install
npm run build

# 2. Run the inspector
export BIT2ME_API_KEY=YOUR_BIT2ME_ACCOUNT_API_KEY
export BIT2ME_API_SECRET=YOUR_BIT2ME_ACCOUNT_API_SECRET
npx @modelcontextprotocol/inspector node build/index.js
```

**Note:** The inspector will automatically open at `http://localhost:5173`

### Using the Inspector

The web interface provides:

1. **Tools Tab:**
    - View all 48 available tools
    - See input schemas for each tool
    - Test tools with custom parameters
    - View formatted responses

2. **Resources Tab:**
    - Explore available resources (if any)

3. **Prompts Tab:**
    - Test prompt templates (if configured)

4. **Request/Response Logs:**
    - See all MCP protocol messages
    - Debug communication issues
    - View timing information

### Example: Testing a Tool

1. Navigate to the **Tools** tab
2. Select a tool (e.g., `market_get_ticker`)
3. Fill in the required parameters:
    ```json
    {
        "base_symbol": "BTC",
        "quote_symbol": "EUR"
    }
    ```
4. Click **Run** to execute the tool
5. View the formatted response in the output panel

## 🌐 Landing Page Deployment

The project's landing page is located in the `/landing` directory.
Deployment is automated using GitHub Actions.

**How to update the website:**

1. Edit the HTML/CSS files in `/landing`.
2. Push your changes to the `main` branch.
3. The `.github/workflows/deploy.yml` action will automatically publish the changes.

**Domain:**
The `/landing/CNAME` file manages the custom domain configuration.

## 🤝 Contributing

We welcome contributions to improve this MCP server! Whether it's fixing bugs, adding new tools, or improving documentation, your help is appreciated.

Please read our **[Contributing Guidelines](./CONTRIBUTING.md)** for details on:

- Setting up your development environment
- Running tests
- Commit conventions (Conventional Commits)
- Pull Request process

### Quick Start

1.  **Fork and Clone**:
    ```bash
    git clone https://github.com/bit2me-devs/bit2me-mcp.git
    ```
2.  **Install Dependencies**:
    ```bash
    npm install
    ```
3.  **Create a Branch**:
    ```bash
    git checkout -b feat/amazing-feature
    ```

For full details, check the [CONTRIBUTING.md](./CONTRIBUTING.md) file.

### Code of Conduct

Be respectful, inclusive, and constructive. We're all here to learn and build together.

## 📄 License

[MIT License](./LICENSE)


==================================================
FILE: CHANGELOG.md (Changelog)
==================================================

## [4.1.4](https://github.com/bit2me-devs/bit2me-mcp/compare/v4.1.3...v4.1.4) (2026-01-24)

### Bug Fixes

- **ci:** remove registry-url to allow npm OIDC authentication ([1e636eb](https://github.com/bit2me-devs/bit2me-mcp/commit/1e636ebc449999f44b1c8953572e19415c2733cd))

## [4.1.3](https://github.com/bit2me-devs/bit2me-mcp/compare/v4.1.2...v4.1.3) (2026-01-24)

### Bug Fixes

- **ci:** manually obtain OIDC token for npm publish ([09340f6](https://github.com/bit2me-devs/bit2me-mcp/commit/09340f6e65f71ba5fb06e879d1b46a3f715aa177))

## [4.1.2](https://github.com/bit2me-devs/bit2me-mcp/compare/v4.1.1...v4.1.2) (2026-01-24)

### Bug Fixes

- **ci:** enable npm provenance for OIDC authentication ([6bb59fc](https://github.com/bit2me-devs/bit2me-mcp/commit/6bb59fca0d67376f2083c2f6da350c7fc2ba0473))

## [4.1.1](https://github.com/bit2me-devs/bit2me-mcp/compare/v4.1.0...v4.1.1) (2026-01-24)

### Bug Fixes

- **ci:** switch to npm OIDC trusted publisher for secure publishing ([4c479aa](https://github.com/bit2me-devs/bit2me-mcp/commit/4c479aa6487e0852ddb1494ab1639e93d70c8ace))

# [4.1.0](https://github.com/bit2me-devs/bit2me-mcp/compare/v4.0.0...v4.1.0) (2026-01-24)

### Features

- switch package manager from npm to pnpm ([ecb273d](https://github.com/bit2me-devs/bit2me-mcp/commit/ecb273d1751ef4de0ddb5a9a80c2545fb253ae3c))

### BREAKING CHANGES

- Project now requires pnpm >= 10.0.0 as the package manager.
  Users should install pnpm globally with `npm install -g pnpm` before contributing.

# [4.0.0](https://github.com/bit2me-devs/bit2me-mcp/compare/v3.2.3...v4.0.0) (2026-01-24)

### Build System

- migrate from npm to pnpm ([b34b5d0](https://github.com/bit2me-devs/bit2me-mcp/commit/b34b5d0f88167b6b5b3b6aa3466e3509e5a3770c))

### BREAKING CHANGES

- Project now requires pnpm >= 10.0.0

## [3.2.3](https://github.com/bit2me-devs/bit2me-mcp/compare/v3.2.2...v3.2.3) (2025-12-16)

### Bug Fixes

- resolve all eslint warnings ([1e493a0](https://github.com/bit2me-devs/bit2me-mcp/commit/1e493a0a097db6eb9b567d710d8c12e369e723da))

## [3.2.2](https://github.com/bit2me-devs/bit2me-mcp/compare/v3.2.1...v3.2.2) (2025-12-07)

### Bug Fixes

- correct broker proforma response mapping ([1a27d2b](https://github.com/bit2me-devs/bit2me-mcp/commit/1a27d2b771319ff9a7cd3b3ba884026f4e4bd0f9))

## [3.2.1](https://github.com/bit2me-devs/bit2me-mcp/compare/v3.2.0...v3.2.1) (2025-12-07)

### Bug Fixes

- inject jwt parameter only in tools that require authentication ([db0e191](https://github.com/bit2me-devs/bit2me-mcp/commit/db0e19119571143dd7428d21341e265d2d665c08))

# [3.2.0](https://github.com/bit2me-devs/bit2me-mcp/compare/v3.1.2...v3.2.0) (2025-12-07)

### Bug Fixes

- improve error messages for authentication and API failures ([9452ba5](https://github.com/bit2me-devs/bit2me-mcp/commit/9452ba522816c3ae128976106c6ba87f0fa0b3c7))
- resolve TypeScript error in auth test ([4d40d49](https://github.com/bit2me-devs/bit2me-mcp/commit/4d40d49531709fd6506f57d45080a410a9b90ff6))

### Features

- add JWT session authentication support ([d2bbae1](https://github.com/bit2me-devs/bit2me-mcp/commit/d2bbae189eefd66b186fee0445c74950acc35436))

## [3.1.2](https://github.com/bit2me-devs/bit2me-mcp/compare/v3.1.1...v3.1.2) (2025-12-06)

### Bug Fixes

- **ci:** add TOOLS_DOCUMENTATION.md to release doc regeneration ([895d70e](https://github.com/bit2me-devs/bit2me-mcp/commit/895d70ef1650fdd79bf2968118f93bab1c14e3ba))

## [3.1.1](https://github.com/bit2me-devs/bit2me-mcp/compare/v3.1.0...v3.1.1) (2025-12-06)

### Bug Fixes

- **ci:** fix shell quoting in release workflow ([077fdb6](https://github.com/bit2me-devs/bit2me-mcp/commit/077fdb6769bc165872fbe1ff0114e0fc6a79283d))

# [3.1.0](https://github.com/bit2me-devs/bit2me-mcp/compare/v3.0.3...v3.1.0) (2025-12-06)

### Features

- **config:** add configurable BIT2ME_GATEWAY_URL for QA/staging ([30a0408](https://github.com/bit2me-devs/bit2me-mcp/commit/30a0408542bd1bcd8ac28c7ab69e09c9d824ba3f))

## [3.0.3](https://github.com/bit2me-devs/bit2me-mcp/compare/v3.0.2...v3.0.3) (2025-12-06)

### Bug Fixes

- **docs:** add missing table header in Pro Trading Operations section ([91cec60](https://github.com/bit2me-devs/bit2me-mcp/commit/91cec606d87a274c2ef4c164ca6ce82feab5b2dc))

## [3.0.2](https://github.com/bit2me-devs/bit2me-mcp/compare/v3.0.1...v3.0.2) (2025-12-06)

### Bug Fixes

- remove unused imports (CodeQL alert [#84](https://github.com/bit2me-devs/bit2me-mcp/issues/84)) ([274a34b](https://github.com/bit2me-devs/bit2me-mcp/commit/274a34b9c36102a581494ed30ae42d50432361b4))

## [3.0.1](https://github.com/bit2me-devs/bit2me-mcp/compare/v3.0.0...v3.0.1) (2025-12-06)

### Bug Fixes

- resolve CodeQL warnings for unused variables and imports ([b1b2d20](https://github.com/bit2me-devs/bit2me-mcp/commit/b1b2d2046dc9d055adf0a3edaed6af6946ad64f2))

# [3.0.0](https://github.com/bit2me-devs/bit2me-mcp/compare/v2.0.0...v3.0.0) (2025-12-06)

- feat!: release v3.0 with major API restructuring ([0d32844](https://github.com/bit2me-devs/bit2me-mcp/commit/0d32844e8beb7ac1f33fe78425cb6fdc06d3366b))

### Bug Fixes

- **broker:** round fiat values to 2 decimals in broker_get_asset_data ([e254397](https://github.com/bit2me-devs/bit2me-mcp/commit/e25439753f25ab06d4660e454c6ccbf6bc6d877d))
- **loan:** handle data wrapper in loan_get_movements response ([8a2a601](https://github.com/bit2me-devs/bit2me-mcp/commit/8a2a601bae737499ff925bc836fd9a3482b7a2f5))
- **mappers:** round all fiat-converted values to 2 decimals ([5850e41](https://github.com/bit2me-devs/bit2me-mcp/commit/5850e41314b994dc846a09e0fa99a143d50092c4))
- **pro:** correct symbol format for pro_get_public_trades API call ([c9da828](https://github.com/bit2me-devs/bit2me-mcp/commit/c9da8280d0d2f5229aad82d9a93f3e5e352ef6e0))
- **pro:** update order book symbol format and response mapping ([04fa6b6](https://github.com/bit2me-devs/bit2me-mcp/commit/04fa6b6e86682a661e7e0d0954e7db24a5c7d119))

### Code Refactoring

- **tools:** consolidate list and detail tools into unified tools with ID filters ([7c4b772](https://github.com/bit2me-devs/bit2me-mcp/commit/7c4b772ae4869685a7b0eba720c253e9fe56ade0))

### Features

- update tools, landing page and code improvements ([643516f](https://github.com/bit2me-devs/bit2me-mcp/commit/643516f61ab6c136a0d4348ec3f830cff89b0993))
- add new features (health, circuit-breaker, rate-limiter) ([71cbbe5](https://github.com/bit2me-devs/bit2me-mcp/commit/71cbbe5df84a8c75809dea731c6f57a1cfd6ab8c))
- **earn:** enrich earn_get_assets with full asset details ([9394e99](https://github.com/bit2me-devs/bit2me-mcp/commit/9394e993008f8c76295264655741b83f63eb206f))
- **landing:** improve interactive examples ([29e573a](https://github.com/bit2me-devs/bit2me-mcp/commit/29e573aaf0a2f89eab074c348fe34dd3d328f6d0))
- **landing:** improve sidebar UI and dark mode ([c3514b1](https://github.com/bit2me-devs/bit2me-mcp/commit/c3514b168f7d47e2e77ba73ca4316584e7b41a49))
- **loan:** completely rewrite loan_get_movements mapper ([a57541a](https://github.com/bit2me-devs/bit2me-mcp/commit/a57541aea341310214707c2b503845a8d8d7d93c))
- **loan:** enrich loan_get_orders with full loan details ([bfdbe1e](https://github.com/bit2me-devs/bit2me-mcp/commit/bfdbe1ebbbbdc538759cbe34f5c35ebcf623711f))
- **pro:** enrich pro_get_market_config with full trading parameters ([49a003a](https://github.com/bit2me-devs/bit2me-mcp/commit/49a003a4294a26f47349249874adf8bf0cc6fcf0))
- **schema:** comprehensive improvements to tools.json schema ([535edc6](https://github.com/bit2me-devs/bit2me-mcp/commit/535edc6f4d1f7016100155ffff726da16a342a07))

### BREAKING CHANGES

- This release contains multiple breaking changes:

## Tool Renaming

- All market*\* tools renamed to broker*\* tools for consistency
- broker_get_asset_data replaces market_get_asset_data
- broker_get_chart replaces market_get_chart
- broker_get_info replaces market_get_info
- broker_get_price replaces market_get_price

## Removed Modules

- account.ts module removed (consolidated into wallet)
- market.ts module removed (replaced by broker.ts)

## Tool Consolidation

- List and detail tools unified with optional ID filters
- wallet_get_cards now supports optional card_id filter
- earn_get_assets returns comprehensive asset information
- pro_get_market_config includes full trading parameters

## Response Format Changes

- All fiat values now rounded to 2 decimals
- loan_get_movements completely rewritten with correct field mapping
- loan_get_orders enriched with LTV, APR, and interest details
- earn_get_positions includes lock_period and converted_balance

## New Features

- Circuit breaker pattern for API resilience
- Health check endpoint (server_health_check)
- Rate limiter configuration
- Enhanced metrics collection

* **tools:** Detail tools removed, use list tools with ID filter instead.

## [Unreleased]

### Breaking Changes

- **reorganization:** Major reorganization of tool categories to improve semantic clarity for AI models:
    - **New category `broker` (Simple Trading):** Created new category consolidating broker market data and trading operations:
        - `market_get_ticker` → `broker_get_assets_price`
        - `market_get_data` → `broker_get_asset_data` (previously renamed to `broker_get_price_info`)
        - `market_get_chart` → `broker_get_asset_chart`
        - `wallet_buy_crypto` → `broker_quote_buy`
        - `wallet_sell_crypto` → `broker_quote_sell`
        - `wallet_swap_crypto` → `broker_quote_swap`
        - `wallet_confirm_operation` → `broker_confirm_quote`
    - **Category `general`:** Contains `general_get_assets_config` (asset information, previously `get_assets_details`)
    - **Category `wallet`:** Now only contains storage/balance tools (pockets, movements, addresses, cards)

    This reorganization provides clearer semantic separation: "Wallet" for storage/balances, "Broker" for simple trading and broker prices, and "Pro" for advanced trading. This prevents AI models from confusing Broker prices (which include spread) with Pro Trading prices when making trading decisions.

- **earn:** Rename Earn tools to use "position" terminology instead of "wallet" for better clarity:
    - `earn_get_wallets` → `earn_get_positions`
    - `earn_get_wallet_details` → `earn_get_position_details`
    - `earn_get_wallet_movements` → `earn_get_position_movements`
    - `earn_get_wallet_rewards_config` → `earn_get_position_rewards_config`
    - `earn_get_wallet_rewards_summary` → `earn_get_position_rewards_summary`
    - Parameter `wallet_id` → `position_id` in all Earn tools
    - Response fields `wallet_id` → `position_id` (backward compatibility: `wallet_id` still included in responses)

    This change clarifies that Earn "positions" represent money that is locked or generating yield (invested money), different from Wallet "pockets" which represent liquid available funds.

- **timeframes:** Standardize timeframe notation to trading standard and migrate validations to strict enums:
    - **Unified notation:** Changed `broker_get_asset_chart` timeframe from natural language ("one-hour", "one-day", "one-week", "one-month", "one-year") to trading notation ("1h", "1d", "1w", "1M", "1y") to match `pro_get_candles` and industry standards (TradingView, CCXT)
    - **Strict validation:** Added `enum` arrays to `inputSchema` for `broker_get_asset_chart` and `pro_get_candles` timeframe parameters, preventing LLM hallucinations and ensuring server-side validation
    - **Internal conversion:** Added `convertBrokerTimeframe()` function to map trading notation to API format internally, maintaining backward compatibility with API expectations

    This improvement reduces ambiguity for LLMs, saves tokens, unifies logic between Broker and Pro Trading tools, and provides robust validation at the schema level.

## [1.8.4](https://github.com/bit2me-devs/bit2me-mcp/compare/v1.8.3...v1.8.4) (2025-12-04)

### Bug Fixes

- **tests:** require explicit RUN_E2E=true to run E2E tests ([1eeda55](https://github.com/bit2me-devs/bit2me-mcp/commit/1eeda5573742a7f680e3013667e2f04ce40512d4))

## [1.8.3](https://github.com/bit2me-devs/bit2me-mcp/compare/v1.8.2...v1.8.3) (2025-12-04)

### Bug Fixes

- **tests:** read version dynamically from package.json ([61e0603](https://github.com/bit2me-devs/bit2me-mcp/commit/61e0603c462f07d879063ef31a711848cf40d438))

## [1.8.2](https://github.com/bit2me-devs/bit2me-mcp/compare/v1.8.1...v1.8.2) (2025-12-04)

### Bug Fixes

- **ci:** correct github/codeql-action SHA to valid v4 commit ([1cbc342](https://github.com/bit2me-devs/bit2me-mcp/commit/1cbc34296dfc93f96895c2a2488d16f47e39ad97))
- **tests:** update expected version to 1.8.1 in index.test.ts ([d778298](https://github.com/bit2me-devs/bit2me-mcp/commit/d778298d537844e1bdeb31f9088537e6fadb37a3))

## [1.8.1](https://github.com/bit2me-devs/bit2me-mcp/compare/v1.8.0...v1.8.1) (2025-12-04)

### Bug Fixes

- **ci:** correct ossf/scorecard-action SHA to valid v2.4.0 commit ([234d06e](https://github.com/bit2me-devs/bit2me-mcp/commit/234d06ea494868e5638d3f466813d62403e5836a))
- **tests:** update expected version to 1.8.0 in index.test.ts ([d6f1d8c](https://github.com/bit2me-devs/bit2me-mcp/commit/d6f1d8c92ba99d3c5d3a614ce914f3096293adb0))

# [1.8.0](https://github.com/bit2me-devs/bit2me-mcp/compare/v1.7.0...v1.8.0) (2025-12-04)

### Bug Fixes

- **ci:** update codecov action to valid version ([6b6d4e5](https://github.com/bit2me-devs/bit2me-mcp/commit/6b6d4e5c374d5445fa51ae16efad84eb0d9b8731))
- correct API endpoints for wallet and earn tools ([ef1f892](https://github.com/bit2me-devs/bit2me-mcp/commit/ef1f892e1f9d920dbba5f2272329098cb4a4d0b5))
- correct mapCurrencyRateResponse for actual API structure ([262e376](https://github.com/bit2me-devs/bit2me-mcp/commit/262e37655f39264adb45c7057f67a1d3068ab155))
- earn_get_summary response format and remove apy ([75ab614](https://github.com/bit2me-devs/bit2me-mcp/commit/75ab614578909961a7d631d13a31ba852da832a8))
- extract transactions array from v2 API response ([8454b89](https://github.com/bit2me-devs/bit2me-mcp/commit/8454b8955b3b108a568d3cab565e7a8a0cb87567))
- handle nested array response in earn_get_summary ([5f95bd9](https://github.com/bit2me-devs/bit2me-mcp/commit/5f95bd91744e285c4c74661af051f2fe2f32a567))
- handle nested data structure in earn_get_wallets and ignore docs/ ([b75cbad](https://github.com/bit2me-devs/bit2me-mcp/commit/b75cbad56d7f38c4814357bb1003c1073bb837f8))
- **market:** remove chart data limit and rename ticker parameter to pair ([b58308b](https://github.com/bit2me-devs/bit2me-mcp/commit/b58308b0c3ab42af5f958e56eead4c7bfbbb0675))
- pin all GitHub Actions to specific commit SHAs ([b2c9db4](https://github.com/bit2me-devs/bit2me-mcp/commit/b2c9db42bb9e0eb3f786e8a5642774fd4b5341fa))
- remove redundant null check in mapEarnSummaryResponse ([2ca291e](https://github.com/bit2me-devs/bit2me-mcp/commit/2ca291e76edd657250594f9ef869ea718befe700))
- remove unused imports and improve type checking ([f11b881](https://github.com/bit2me-devs/bit2me-mcp/commit/f11b881763b497ba36ffbfae53b7ada6445aab1b))
- remove unused type imports from market.ts ([f87d39c](https://github.com/bit2me-devs/bit2me-mcp/commit/f87d39c5ebc4258d757322e1f3064565ee684dd5))
- resolve CodeQL warnings ([b155ee8](https://github.com/bit2me-devs/bit2me-mcp/commit/b155ee87bd80b71623e88eb9084ccdd0ea9eb8dc)), closes [#59](https://github.com/bit2me-devs/bit2me-mcp/issues/59) [#70](https://github.com/bit2me-devs/bit2me-mcp/issues/70) [#77](https://github.com/bit2me-devs/bit2me-mcp/issues/77)
- resolve security and code quality issues ([9346c46](https://github.com/bit2me-devs/bit2me-mcp/commit/9346c46a3c39b48c199d0ec269bb4ec773711d85))
- **tests:** add config mock to edge-cases and portfolio tests ([ff406a4](https://github.com/bit2me-devs/bit2me-mcp/commit/ff406a41a04a672981c3835fc533dda63a4d6589))
- update codeql-action SHA in gitleaks workflow for consistency ([e94075d](https://github.com/bit2me-devs/bit2me-mcp/commit/e94075dad7165e2a24dc2bd00377cae4d7ed8a27))
- update portfolio_get_valuation to use v2 earn endpoint and fix pro balance calculation ([acab884](https://github.com/bit2me-devs/bit2me-mcp/commit/acab884c154f7960973974d953c37a8934e412f5))
- update wallet_get_transactions to match correct API schema ([25ec140](https://github.com/bit2me-devs/bit2me-mcp/commit/25ec1401b84923bb39092af51f7e4254655a6a04))

### Features

- add CurrencyRateResponse schema interface ([44df338](https://github.com/bit2me-devs/bit2me-mcp/commit/44df338a0cff53fc5156521b9ce1d58b6b8729d8))
- apply smartRound formatting to all price-returning tools ([32162bd](https://github.com/bit2me-devs/bit2me-mcp/commit/32162bdc004edaeebc101d9d993869bc88f3796e))
- implement market_get_currency_rate tool ([bce4955](https://github.com/bit2me-devs/bit2me-mcp/commit/bce4955034a835c8c8db79d0c9eca8eef6de2aae))
- **loan:** revamp loan tools and terminology ([aa3b48e](https://github.com/bit2me-devs/bit2me-mcp/commit/aa3b48efb623810d5b3e9d2d1feeb30158b0ce61))
- **wallet/earn:** add cards support and improve rewards ([f9fd3a9](https://github.com/bit2me-devs/bit2me-mcp/commit/f9fd3a9bde3bc643d32580d08e05e2793197f232))

# [1.7.0](https://github.com/bit2me-devs/bit2me-mcp/compare/v1.6.3...v1.7.0) (2025-11-29)

### Bug Fixes

- add attestations write permission for build provenance ([b9dc332](https://github.com/bit2me-devs/bit2me-mcp/commit/b9dc33261707f21a71b892b8fc2f5c7eee00f0ce))
- **build:** use html-minifier-terser for robust minification ([4bb1ac3](https://github.com/bit2me-devs/bit2me-mcp/commit/4bb1ac36c5fdeb7e654853117021fb2096fdc742))
- correct wallet transaction confirmation and add currency filter to pockets ([0d2cf82](https://github.com/bit2me-devs/bit2me-mcp/commit/0d2cf8277b94b121a189afdeafd5a61967ee46a2))
- pin upload-pages-artifact action by commit hash to resolve security alert ([70ea476](https://github.com/bit2me-devs/bit2me-mcp/commit/70ea476cc175f32a46be525371b14b358e298c11))
- return full ISO date time in market_get_chart tool instead of date only ([7c13998](https://github.com/bit2me-devs/bit2me-mcp/commit/7c13998e4f9a41611513e9b3b6144a4844442d33))
- **tests:** remove unused import expect from vitest ([2aba1bf](https://github.com/bit2me-devs/bit2me-mcp/commit/2aba1bf4ea378b2a7f23afbecae38bcd3af6f51f))
- update attest-build-provenance action to v2 ([673a9af](https://github.com/bit2me-devs/bit2me-mcp/commit/673a9afeb84bdc1bdee26ba4b406933837f90408))

### Features

- **build:** add HTML minification for production only ([5fe4559](https://github.com/bit2me-devs/bit2me-mcp/commit/5fe45591ff154796e138f30837dabc8b4f4b5e14))
- **landing:** improve usage examples with all parameters and responses ([14dcac3](https://github.com/bit2me-devs/bit2me-mcp/commit/14dcac36b6a37bff56f6cf84672495ed8175828d))

## [1.6.3](https://github.com/bit2me-devs/bit2me-mcp/compare/v1.6.2...v1.6.3) (2025-11-28)

### Bug Fixes

- address incomplete sanitization alert using replacement loop ([f020b6e](https://github.com/bit2me-devs/bit2me-mcp/commit/f020b6e75446778416dc6705c2d0b8b45f002b08))

## [1.6.2](https://github.com/bit2me-devs/bit2me-mcp/compare/v1.6.1...v1.6.2) (2025-11-28)

### Bug Fixes

- address remaining security scanning alerts ([730dab4](https://github.com/bit2me-devs/bit2me-mcp/commit/730dab4b3c66d2bc416c20f000dac444a606da71))

## [1.6.1](https://github.com/bit2me-devs/bit2me-mcp/compare/v1.6.0...v1.6.1) (2025-11-28)

### Bug Fixes

- resolve high severity security alerts ([fcaa6f0](https://github.com/bit2me-devs/bit2me-mcp/commit/fcaa6f07ae0d4535c79ddf3b730055ca47c4f0f5))

# [1.6.0](https://github.com/bit2me-devs/bit2me-mcp/compare/v1.5.0...v1.6.0) (2025-11-28)

### Features

- add robots.txt to landing page ([f13294b](https://github.com/bit2me-devs/bit2me-mcp/commit/f13294bb0a6182bff892d7e763b721a787dd43e1))

# [1.5.0](https://github.com/bit2me-devs/bit2me-mcp/compare/v1.4.1...v1.5.0) (2025-11-28)

### Features

- implement automatic generation of llms.txt and llms-full.txt ([9b95992](https://github.com/bit2me-devs/bit2me-mcp/commit/9b959924d235ef440c11704be4286c782f015fa8))

## [1.4.1](https://github.com/bit2me-devs/bit2me-mcp/compare/v1.4.0...v1.4.1) (2025-11-27)

### Bug Fixes

- resolve CodeQL security scanning alerts ([dc432e7](https://github.com/bit2me-devs/bit2me-mcp/commit/dc432e769c7373e3981b6b541b734717bf7d1b31))

# [1.4.0](https://github.com/bit2me-devs/bit2me-mcp/compare/v1.3.1...v1.4.0) (2025-11-27)

### Features

- add Google Analytics to landing page ([ec61650](https://github.com/bit2me-devs/bit2me-mcp/commit/ec616502fcf21206b45f2b2becd4c8e416353af4))

## [1.3.1](https://github.com/bit2me-devs/bit2me-mcp/compare/v1.3.0...v1.3.1) (2025-11-27)

### Bug Fixes

- reorganize imports in wallet.ts to match export order ([969cf5b](https://github.com/bit2me-devs/bit2me-mcp/commit/969cf5b9562a84753c516f0ddf627b3e12b1b7f3))

# [1.3.0](https://github.com/bit2me-devs/bit2me-mcp/compare/v1.2.0...v1.3.0) (2025-11-27)

### Bug Fixes

- remove deprecated husky lines ([545c3eb](https://github.com/bit2me-devs/bit2me-mcp/commit/545c3eba36fbe3d2bf4577b66479f083961f2730))
- remove currency parameter from wallet_get_pockets ([0c74d73](https://github.com/bit2me-devs/bit2me-mcp/commit/0c74d73b6b967e14bf7375ae46fb83ca5e515585))

### Features

- update tools, mappers and documentation ([34af228](https://github.com/bit2me-devs/bit2me-mcp/commit/34af228ca9acfeb0f6b33c77b7c26f23aaccbe02))

# [1.2.0](https://github.com/bit2me-devs/bit2me-mcp/compare/v1.1.1...v1.2.0) (2025-11-27)

### Bug Fixes

- add config mock to wallet tests ([84048b4](https://github.com/bit2me-devs/bit2me-mcp/commit/84048b49d24e74200803429edfb254372445b707))
- configure npm registry authentication before semantic-release ([15fe81f](https://github.com/bit2me-devs/bit2me-mcp/commit/15fe81f8bebe146c5bbec932333b36694bf4adb0))
- configure semantic-release workflow with proper credentials ([235d49c](https://github.com/bit2me-devs/bit2me-mcp/commit/235d49c0bda41e08b5c7bb1ea651f6502e8e1e6d))
- correct wallet address mapper and add pocket details mapper ([b392a69](https://github.com/bit2me-devs/bit2me-mcp/commit/b392a6968a80d6f59c76e0e3936088a2bf2fd016))
- improve npm token verification in release workflow ([1e89869](https://github.com/bit2me-devs/bit2me-mcp/commit/1e89869d850c8e2c307102c624a53e5e9e0a2071))
- improve semantic-release configuration ([88ea71c](https://github.com/bit2me-devs/bit2me-mcp/commit/88ea71c4ff0b0e753f6806ded20a9532097af6f0))
- **landing:** update github link in sidebar ([d11afe1](https://github.com/bit2me-devs/bit2me-mcp/commit/d11afe1d52e5cc66d5c18151726c45fe7ef7cae2))
- remove workaround from semantic-release workflow ([0043544](https://github.com/bit2me-devs/bit2me-mcp/commit/00435447f72dd6986215b175f078de4c6e256a5c))
- resolve all eslint warnings and improve type safety ([823d262](https://github.com/bit2me-devs/bit2me-mcp/commit/823d26293d5dda49a2f5b3eb8ef7351aed5005a0))
- update Node.js version to 22 for semantic-release compatibility ([f78f88f](https://github.com/bit2me-devs/bit2me-mcp/commit/f78f88f2b292290abc5910dfdfeffc5e013e0e56))

### Features

- add optional raw_response support in mapped responses ([623413b](https://github.com/bit2me-devs/bit2me-mcp/commit/623413b5b69cbd7629ea96e1f3aae381d5bfb871))
- improve landing page and git hooks management ([bbb1364](https://github.com/bit2me-devs/bit2me-mcp/commit/bbb1364b5d3bff5ca8ad8809dedb8da30493787c))

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

## [1.1.2] - 2025-11-26

### Added

- **Landing Page Improvements**:
    - New "Prerequisites" section explaining how to obtain API Keys.
    - Tabbed installation instructions for **Claude Desktop**, **Cursor IDE**, **Windsurf**, **Gemini CLI**, and **VS Code**.
    - Detailed `mcp_config.json` examples for each platform.
    - Explicit warning about Cursor's environment variable limitations (requires `.env` file).

### Fixed

- **Documentation Accuracy**:
    - Corrected total tool count from 48 to **47** in both `landing/index.html` and `README.md`.
    - Updated tool breakdown list in `README.md` to match the actual implementation (8 Market, 7 Wallet, 11 Earn, 9 Loan, 10 Pro, 1 Account, 1 Aggregation).

## [1.1.1] - 2025-11-26

### Fixed

- Added missing `repository` field to `package.json` for NPM metadata.

## [1.1.0] - 2025-11-26

### Added

- **Landing Page Enhancements**:
    - Predictive search with suggestions and auto-scroll.
    - New "Tools Reference" section name (previously API Reference).
    - Added "Parameters & Validation" and "Server & Maintenance" troubleshooting guides.
    - Improved JSON example indentation and visualization.
    - Updated footer links (GitHub, Bit2Me Website, API Docs).
- **Documentation**:
    - Added GitHub repository button with logo in Hero section.
    - Updated all repository references to `bit2me-devs/bit2me-mcp`.

### Changed

- **Code Refactoring**:
    - Flattened `src/tools` directory structure (removed `assets`, `market`, `aggregation` subfolders).
    - Moved `schemas.ts` from `src/types/` to `src/utils/`.
    - Updated import paths across the project to reflect new structure.
- **Tool Logic**:
    - Unified return types in tool handlers (replaced `null` returns with explicit Errors for MCP SDK compatibility).

### Fixed

- Corrected argument definitions in landing page examples for `wallet_create_proforma`, `earn_create_transaction`, `loan_get_ltv`, and others.
- Fixed build errors related to strict type checking in tool handlers.
- Resolved test import path issues after directory restructuring.

### Added (Previous)

- Complete mapper coverage (47/47 tools with optimized responses)
- TypeScript strict mode enforcement
- ESLint configuration with TypeScript rules
- Prettier code formatting
- Pre-commit hooks with Husky
- Comprehensive CI/CD workflows
- Code quality badges in README
- Barrel exports for utilities
- Pull request template
- Dependabot configuration
- Semantic release automation
- Code coverage reporting

### Changed

- Consolidated API service layer (merged `api.ts` and `auth.ts` into `services/bit2me.ts`)
- Internationalized all code comments and documentation to English
- Enhanced error handling with custom error classes
- Improved logging with structured logger and data sanitization
- Updated deployment workflow with pre-deployment validation

### Fixed

- Missing mapper for `pro_get_order_details` tool
- Exponential backoff implementation with configurable limits
- Rate limit handling with proper retry logic

### Security

- Sanitized sensitive data in logs (API keys, signatures)
- Strict TypeScript type checking
- Input validation with type guards on all mappers

---

## [1.0.0] - 2025-11-25

### Added

- Initial release of Bit2Me MCP Server
- 47 tools across 8 categories:
    - 8 Market tools (public data)
    - 7 Wallet tools (private)
    - 12 Earn/Staking tools
    - 11 Loan tools
    - 8 Pro Trading tools
    - 1 Account tool
    - 1 Portfolio aggregation tool
    - 11 Operation tools (write actions)
- Automatic retry mechanism for rate-limited requests
- Exponential backoff with jitter
- Comprehensive test suite (31 tests)
- Documentation:
    - README quick-start guide
    - TOOLS_DOCUMENTATION.md with descriptions, endpoints and response schemas
    - TypeScript schema coverage documentation
    - Product marketing documentation
- Landing page with GitHub Pages deployment
- Environment-based configuration
- MCP SDK integration

### Security

- Secure API authentication with signature generation
- Environment variable validation with Zod
- No hardcoded credentials

---

## Release Notes

### Version Numbering

This project follows [Semantic Versioning](https://semver.org/):

- **MAJOR** version for incompatible API changes
- **MINOR** version for new functionality in a backwards compatible manner
- **PATCH** version for backwards compatible bug fixes

### Automated Releases

Releases are automated using [semantic-release](https://github.com/semantic-release/semantic-release).
Version bumps are determined by commit message conventions.

### Commit Convention

We follow [Conventional Commits](https://www.conventionalcommits.org/):

- `feat:` - New features (minor version bump)
- `fix:` - Bug fixes (patch version bump)
- `docs:` - Documentation changes (no version bump)
- `style:` - Code style changes (no version bump)
- `refactor:` - Code refactoring (no version bump)
- `perf:` - Performance improvements (patch version bump)
- `test:` - Test changes (no version bump)
- `chore:` - Build/dependency changes (no version bump)
- `ci:` - CI/CD changes (no version bump)

Add `BREAKING CHANGE:` in commit body for major version bumps.

---

## [Links]

- [Repository](https://github.com/bit2me-devs/bit2me-mcp)
- [Issues](https://github.com/bit2me-devs/bit2me-mcp/issues)
- [Pull Requests](https://github.com/bit2me-devs/bit2me-mcp/pulls)
- [Releases](https://github.com/bit2me-devs/bit2me-mcp/releases)