> ## Documentation Index
> Fetch the complete documentation index at: https://cryptorobot.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Exchanges

> Connect exchanges, fetch market data, and manage balances

## Overview

Exchanges are the foundation of Cryptorobot.ai. By connecting your exchange accounts, you unlock:

* Real-time balance tracking across all connected exchanges
* Live market data (OHLCV, order books, tickers)
* Trade execution through trading bots
* Automatic pair blacklist/whitelist management

Cryptorobot.ai supports **50+ cryptocurrency exchanges** via CCXT.

<CardGroup cols={4}>
  <Card title="Binance" icon="b" />

  <Card title="Bybit" icon="circle" />

  <Card title="OKX" icon="circle" />

  <Card title="Coinbase" icon="c" />

  <Card title="Kraken" icon="k" />

  <Card title="KuCoin" icon="k" />

  <Card title="Gate.io" icon="g" />

  <Card title="+ 50 more" icon="ellipsis" />
</CardGroup>

## Connection Flow

Connecting an exchange follows a 3-step process:

<Steps>
  <Step title="Create an empty exchange">
    Creates an exchange record with defaults (empty whitelist/blacklist, `connected: false`).
  </Step>

  <Step title="Select the exchange type">
    Patch with `which` (e.g. `binance`). This triggers market data download and sets `requiredCredentials`, `stakeCurrencies`, and `popularStakeCurrency`.
  </Step>

  <Step title="Provide API credentials">
    Patch with `apiKey` and `secret`. The platform validates connectivity and sets `connected: true`.
  </Step>
</Steps>

### Step 1: Create Exchange

```bash theme={null}
curl -X POST https://api.cryptorobot.ai/exchanges \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
```

```json Response theme={null}
{
  "_id": "683a1f...",
  "userId": "682e0a...",
  "connected": false,
  "avatar": "",
  "whitelist": [],
  "blacklist": [],
  "ccxt_config": {},
  "ccxt_async_config": {},
  "createdAt": "2024-01-15T10:00:00.000Z",
  "updatedAt": "2024-01-15T10:00:00.000Z"
}
```

### Step 2: Set Exchange Type

```bash theme={null}
curl -X PATCH https://api.cryptorobot.ai/exchanges/683a1f... \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"which": "binance"}'
```

```json Response theme={null}
{
  "_id": "683a1f...",
  "which": "binance",
  "requiredCredentials": { "apiKey": true, "secret": true },
  "stakeCurrencies": ["BTC", "ETH", "USDT", "BUSD", "BNB"],
  "popularStakeCurrency": "USDT",
  "blacklist": [
    { "left": "BNB", "right": "BTC" },
    { "left": "BNB", "right": "USDT" },
    { "left": "WBTC", "right": "BTC" }
  ]
}
```

<Note>
  Setting `which` triggers an automatic download of all available markets for that exchange. The `blacklist` is populated with known problematic pairs (e.g., wrapped assets, exchange tokens).
</Note>

### Step 3: Connect with Credentials

```bash theme={null}
curl -X PATCH https://api.cryptorobot.ai/exchanges/683a1f... \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"apiKey": "your-api-key", "secret": "your-api-secret"}'
```

```json Response theme={null}
{
  "_id": "683a1f...",
  "which": "binance",
  "connected": true,
  "error": null
}
```

<Warning>
  API credentials are encrypted at rest and **never returned** in subsequent API responses. The `apiKey`, `secret`, `password`, `uid`, `privateKey`, `twofa`, and `token` fields are all redacted from external responses.
</Warning>

## Market Data

Once an exchange is connected, you can fetch live market data.

### Ticker

Get current price and 24h stats for a symbol:

```bash theme={null}
curl -X POST https://api.cryptorobot.ai/exchanges/ticker \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"exchangeId": "683a1f...", "symbol": "BTC/USDT"}'
```

```json Response theme={null}
{
  "exchange": "binance",
  "symbol": "BTC/USDT",
  "close": 42400.00,
  "timestamp": 1705316400000,
  "info": { "symbol": "BTCUSDT" },
  "createdAt": "2024-01-15T12:00:00.000Z"
}
```

### Balance

Fetch current holdings for a specific stake currency:

```bash theme={null}
curl -X POST https://api.cryptorobot.ai/exchanges/balance \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"exchangeId": "683a1f...", "currency": "EUR"}'
```

```json Response theme={null}
{
  "exchangeId": "683a1f...",
  "balances": {
    "items": [...],
    "updatedAt": "2024-01-15T12:01:00.000Z"
  }
}
```

### OHLCV Candles

```bash theme={null}
curl -X POST https://api.cryptorobot.ai/exchanges/ohlcv \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"exchangeId": "683a1f...", "symbol": "BTC/USDT", "timeframe": "1h", "limit": 100}'
```

**Available timeframes:** `1m`, `5m`, `15m`, `30m`, `1h`, `4h`, `1d`, `1w`

### Order Book

```bash theme={null}
curl -X POST https://api.cryptorobot.ai/exchanges/orderbook \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"exchangeId": "683a1f...", "symbol": "BTC/USDT", "limit": 10}'
```

## Managing Exchanges

### List Connected Exchanges

```bash theme={null}
curl https://api.cryptorobot.ai/exchanges \
  -H "Authorization: Bearer $TOKEN"
```

### Configure Whitelist

Control which trading pairs your bots can use:

```bash theme={null}
curl -X PATCH https://api.cryptorobot.ai/exchanges/683a1f... \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "whitelist": [
      {"left": "BTC", "right": "USDT"},
      {"left": "ETH", "right": "USDT"},
      {"left": "SOL", "right": "USDT"}
    ]
  }'
```

<Note>
  If `whitelist` is empty, all pairs are allowed except those in the `blacklist`. If `whitelist` has entries, **only** those pairs are tradeable.
</Note>

### Delete Exchange

```bash theme={null}
curl -X DELETE https://api.cryptorobot.ai/exchanges/683a1f... \
  -H "Authorization: Bearer $TOKEN"
```

Deleting an exchange connection does **not** affect your actual exchange account or any open orders. It only removes the connection from Cryptorobot.ai.

## Key Fields

| Field                         | Type      | Description                                          |
| ----------------------------- | --------- | ---------------------------------------------------- |
| `which`                       | string    | Exchange identifier (e.g. `binance`, `bybit`, `okx`) |
| `connected`                   | boolean   | Whether API credentials were validated               |
| `requiredCredentials`         | object    | Which credential fields the exchange needs           |
| `stakeCurrencies`             | string\[] | Available quote currencies                           |
| `popularStakeCurrency`        | string    | Most traded quote currency by volume                 |
| `whitelist`                   | array     | Allowed trading pairs (empty = all allowed)          |
| `blacklist`                   | array     | Blocked trading pairs                                |
| `ccxt_config`                 | object    | Custom CCXT configuration overrides                  |
| `notifyAboutWhitelistByEmail` | boolean   | Email alerts for new pairs                           |