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

# API guide

# Gopher API Guide

Welcome to the Gopher API. This guide explains how to request API access, make authenticated calls, and interpret JSON responses.

***

<Steps>
  <Step title="Request an API Key">
    To begin using the Gopher API, request an API key from the Gopher team.

    ### How to Request

    Fill out the [API Key Request Form](https://docs.google.com/forms/d/e/1FAIpQLSc4tIzeDrV9La2DVx2ubX2fMabHp4T5OIXPuXBvdJr8pO0KGw/viewform?usp=publish-editor) to request access.

    The team will review your request and send you an API key.
  </Step>

  <Step title="Making API Requests">
    All requests require an `X-API-Key` header.

    ### cURL Request Template

    ```bash theme={null}
    curl -H "X-API-Key: <API_KEY>" \
    "https://<GOPHER_URL>/api/market-data/candles?symbol=<EXCHANGE:ASSET_PAIR>&timeframe=<TIMEFRAME>&limit=<ROWS>"
    ```

    ### Parameters

    | Field     | Description             | Example         |
    | --------- | ----------------------- | --------------- |
    | symbol    | Exchange + asset pair   | BINANCE:BTCUSDT |
    | timeframe | Candle interval         | 15m, 1h, 1d     |
    | limit     | Number of rows (1-1000) | 100             |

    ### Supported Exchanges

    * ✅ BINANCE
    * ✅ COINBASE

    ### Supported Timeframes

    Only the following timeframes are accepted:

    `1m`, `5m`, `15m`, `1h`, `4h`, `1d`

    ### Row Limit

    * Maximum: 1000
    * Requests above this return an error.

    ### Example Error Response

    ```json theme={null}
    {"status":"error","error":{"code":"INVALID_LIMIT","message":"Limit must be between 1 and 1000"}}
    ```
  </Step>

  <Step title="Understanding the JSON Response">
    ### Example Response

    ```json theme={null}
    {
      "status": "success",
      "data": {
        "symbol": "COINBASE:ETHUSDT",
        "timeframe": "4h",
        "count": 1,
        "candles": [
          {
            "timestamp": 1762329600,
            "open": 3331.06,
            "high": 3331.06,
            "low": 3282.84,
            "close": 3295.26,
            "volume": 1201.34418178
          }
        ]
      }
    }
    ```

    ### Response Fields

    | Field      | Meaning                   |
    | ---------- | ------------------------- |
    | status     | success/error             |
    | symbol     | Exchange + pair           |
    | timeframe  | Candle timeframe          |
    | count      | Total rows returned       |
    | candles\[] | OHLCV objects + timestamp |
  </Step>
</Steps>

***

## Example API Calls

Below are example calls using the development environment:

### Binance — 15m, 100 candles

```bash theme={null}
curl -H "X-API-Key: <API_KEY>" \
"https://gotrader.gopher-ai.com/api/market-data/candles?symbol=BINANCE:BTCUSDT&timeframe=15m&limit=100"
```

### Binance — 1h, 10 candles

```bash theme={null}
curl -H "X-API-Key: <API_KEY>" \
"https://gotrader.gopher-ai.com/api/market-data/candles?symbol=BINANCE:BTCUSDT&timeframe=1h&limit=10"
```

### Coinbase — 4h, 20 candles

```bash theme={null}
curl -H "X-API-Key: <API_KEY>" \
"https://gotrader.gopher-ai.com/api/market-data/candles?symbol=COINBASE:ETHUSDT&timeframe=4h&limit=20"
```

***

## Summary

* Request an API key from the Gopher team
* Authenticate using `X-API-Key`
* Query candles using `<EXCHANGE:PAIR>`
* Max 1000 rows per request