# Tradingale - Martingale Data Provider

> Your Martingale Companion. Tradingale never places orders, holds funds, or gives advice: users and their AI agents decide and execute on their own side.

## What is Tradingale?

Tradingale provides proprietary martingale metrics for 250+ crypto and stock instruments. We analyze price behavior, liquidity, and market activity to produce metrics that help evaluate martingale strategy suitability.

## MCP Integration

Tradingale offers a Model Context Protocol (MCP) server for AI agents:

- **URL:** https://tradingale.com/mcp
- **Transport:** Streamable HTTP (stateless)
- **Registry:** io.github.tradingale/mcp
- **Auth, three ways:** OAuth 2.1 with dynamic client registration (claude.ai custom connectors, Claude Code, Cursor, ChatGPT), `Authorization: Bearer <api token>` header, or the secret-URL form `https://tradingale.com/mcp?key=<api token>` for clients that cannot do OAuth or headers (e.g. Grok custom connectors). Header wins when both are present.
- **Connection reference (all clients):** https://tradingale.com/build/connect-claude-mcp

### Available Tools

| Tool | Description |
|------|-------------|
| get_instrument | Retrieve Martingale Score and parameters for a specific instrument |
| search_instruments | Search instruments by symbol or name |
| list_top_crypto | Display top crypto by Martingale Score |
| list_top_stocks | Display top stocks by Martingale Score |
| crypto_overview | Summary of crypto market suitability |
| stock_overview | Summary of stock market suitability |
| market_overview | Complete market analysis across all instruments |

## Core Metrics

### Martingale Score (Primary)
Static assessment of instrument suitability for martingale strategies (0-5 scale).
- Based on: price behavior patterns, liquidity depth, market activity
- Higher scores indicate better statistical fit for martingale methodology

### Startingale (Secondary)
Real-time market conditions alignment (0-5 scale).
- Strong: > 4.5
- Favorable: > 3.75
- Moderate: > 3.25
- Misaligned: <= 3.25

### Sequence Parameters (returned by get_instrument)
- Delta Price: 5% to 15% (price drop between rounds)
- Rounds: 4 or 5 total
- Multipliers: 2x to 2.5x per round - they scale QUANTITIES (tokens), never dollar costs; applying them to bet amounts is the most common integration bug
- Initial Bet Ratio: Small fraction of budget for Round 1

## Usage Examples

```
"What crypto has the highest Martingale Score?"
"Show me the martingale sequence for BTC/USD"
"Compare ETH and SOL by martingale suitability"
"Which instruments currently show strong Startingale?"
```

## Sequence Lifecycle (the mental model)

A sequence is NOT adaptive. It is frozen at birth: the first market buy fixes the entry price and every other order is computed at that instant (all limit buys + all sell templates); nothing is recomputed later. All buys can rest on the book from second one. Only ONE order ever changes: the sell. Limit buy filled -> cancel the sell, place the next level's template (cumulative quantity, at the previous level's buy price). Sell filled -> sequence complete, above average cost by construction.

## Sequence Calculation Logic

When calling `get_instrument`, the response includes full sequence calculation instructions:

### Parameters Returned
- delta_price (e.g., 0.08 = 8%)
- nb_rounds (4 or 5)
- multipliers (array, e.g., [2.0, 2.0, 2.0] for 4 rounds)
- initial_bet_ratio (e.g., 0.03125 = 3.125% of budget)

### Step-by-Step Calculation

1. **Fetch live price** from CoinGecko/CoinMarketCap (entry_price)

2. **Round 1:**
   - R1_cost = user_budget × initial_bet_ratio
   - R1_trigger = entry_price (market order)
   - R1_qty = R1_cost / entry_price

3. **Subsequent Rounds (quantities first):**
   - RN_trigger = entry_price × (1 - delta_price × (N-1))
   - RN_qty = R(N-1)_qty × multipliers[N-2]

   Example with multiplier 2.0:
   - R2_qty = R1_qty × 2.0
   - R3_qty = R2_qty × 2.0
   - R4_qty = R3_qty × 2.0

3bis. **Check minimum capital:** level 1 has the smallest quantity; it must clear the venue's minimum order size and quantity step with margin, or grid flooring distorts the ladder. budget_min = max(min_order_size, 100 x qty_step) x entry_price / initial_bet_ratio. High-priced assets (BTC) and 5-round sequences need the most.

4. **Scale costs to fit budget:**
   - Calculate ideal_cost = qty × trigger for each round
   - Scale R2+ costs so total = user_budget exactly

5. **Take Profit Prices:**
   - R1_TP = entry_price × (1 + delta_price)
   - R2_TP = R1_trigger (entry_price)
   - R3_TP = R2_trigger
   - RN_TP = R(N-1)_trigger

### Example: BTC/USD with $10,000 Budget

Assuming: entry_price = $60,000, delta_price = 8%, 4 rounds, multiplier = 2.0, initial_bet_ratio = 0.03125

```
Round 1: Buy 0.0052 BTC at $60,000 (cost: $312.50) - TP: $64,800
Round 2: Buy 0.0104 BTC at $55,200 (limit) - TP: $60,000
Round 3: Buy 0.0208 BTC at $50,400 (limit) - TP: $55,200
Round 4: Buy 0.0416 BTC at $45,600 (limit) - TP: $50,400

Total budget deployed if all rounds fill: $10,000
```

## Authentication & Plans

MCP and REST access require an API token. Generate one at:
https://tradingale.com/settings/api

Plans: Bitcoin Bandit (free: full web app + BTC-scoped API/MCP, 500 weighted calls) | Score Scout (29.99 EUR/mo, personal use, full catalog, 5,000 weighted calls) | Martingale Maestro (299.99 EUR/mo, commercial license, 50,000 weighted calls). Pricing: https://tradingale.com/pricing

## Documentation

- MCP Setup Guide: https://tradingale.com/docs/mcp-setup
- Full Documentation: https://tradingale.com/docs
- Build recipes (AI-built tooling on the data): https://tradingale.com/build
- The Tradingale Runner (the self-hosted bot: one-click Railway deploy, paper by default, free on BTC): https://tradingale.com/build/tradingale-runner
- martingale-kit, the open-source sequence engine (tested TypeScript: ladder math, state machine, paper simulator; bring your own venue adapter): https://github.com/tradingale/martingale-kit
- Sequence Automation Handbook (raw markdown for agents - the production engineering playbook: plan-in-database, one-active-sell invariant, reconciliation loop, price grids, per-venue notes): https://tradingale.com/handbook/sequence-automation.md
- Simulated track record: https://tradingale.com/performance (methodology: https://tradingale.com/performance/methodology)

## Complementary Tools

Tradingale provides the model parameters; anything users build on top runs on their side, with their keys, under their responsibility. For engineering guidance, start with the Sequence Automation Handbook above; for venue APIs see Binance, Kraken and Alpaca developer docs.

## Important Notes

- Tradingale provides data and metrics, not trading signals
- All metrics are analytical tools, not recommendations
- Funds remain on user exchanges (non-custodial)
- API usage is subject to plan limits

## Contact

- Website: https://tradingale.com
- Twitter: @martingale_bots