Quickstart - TakeProfit

This guide takes you from an API key to live candles in three requests.

Before you start

An API key. See Authentication.
curl for REST requests and any WebSocket client that can send headers, for example websocat.

Keep the key in an environment variable so it does not end up in your shell history or code:

export TAKEPROFIT_API_KEY="your-api-key"

1. Find a security

Every data request needs an exchange and a symbol. Look them up with search:

curl -G "https://public-api.takeprofit.com/api/v1/marketdata/search" \
  -H "x-api-key: $TAKEPROFIT_API_KEY" \
  --data-urlencode "query=BTC/USDT" \
  --data-urlencode "limit=3"

Each hit contains an exchange and symbol pair you can pass to the other endpoints. Always take the pair from here: exchange codes are TakeProfit’s own, not the MIC of the listing venue, so Apple comes back as exchange=BATS, not XNAS. The same symbol usually trades on several exchanges, so pick the one you want:

{
  "hits": [
    {
      "symbol": "BTC/USDT",
      "exchange": "CXBNCE",
      "name": "Bitcoin / Tether",
      "type": "Crypto",
      "baseAsset": "BTC",
      "quoteAsset": "USDT"
    },
    {
      "symbol": "BTC/USDT",
      "exchange": "CXBPOT",
      "name": "Bitcoin / Tether",
      "type": "Crypto",
      "baseAsset": "BTC",
      "quoteAsset": "USDT"
    },
    {
      "symbol": "BTC/USDT.P",
      "exchange": "CXBNF8",
      "name": "Bitcoin / Tether Perpetual",
      "type": "Crypto",
      "baseAsset": "BTC",
      "quoteAsset": "USDT"
    }
  ]
}

2. Load historical candles

Ask for hourly candles from a given timestamp. The range is optional — without it you get the most recent 1000 candles — so from, to, period and limit are there to narrow the window. Note that period counts seconds (86400), it is not a timeframe id:

curl -G "https://public-api.takeprofit.com/api/v1/marketdata/candles" \
  -H "x-api-key: $TAKEPROFIT_API_KEY" \
  --data-urlencode "exchange=CXBNCE" \
  --data-urlencode "symbol=BTC/USDT" \
  --data-urlencode "timeframe=1h" \
  --data-urlencode "from=2026-09-01T00:00:00Z" \
  --data-urlencode "limit=3"

Prices and volumes come as decimal strings, so no precision is lost:

{
  "meta": { "exchange": "CXBNCE", "symbol": "BTC/USDT", "timeframe": "1h" },
  "candles": [
    {
      "timestamp": "2026-09-01T00:00:00Z",
      "open": "78581.3",
      "high": "78900.01",
      "low": "78562",
      "close": "78652",
      "volume": "522.70913",
      "sessionType": "MAINSESSION"
    },
    {
      "timestamp": "2026-09-01T01:00:00Z",
      "open": "78652",
      "high": "78797.99",
      "low": "78375.83",
      "close": "78410.62",
      "volume": "440.9443",
      "sessionType": "MAINSESSION"
    }
  ]
}

Trailing zeros are trimmed, so a price can come back as 78562 rather than 78562.00. Parse the strings with a decimal type, never a float. Valid timeframe ids come from GET /api/v1/marketdata/timeframes. Open a WebSocket connection with the subscription parameters in the query string and the key in the handshake header:

websocat -H "x-api-key: $TAKEPROFIT_API_KEY" \
  "wss://public-api.takeprofit.com/api/v1/marketdata/candles/stream?exchange=CXBNCE&symbol=BTC%2FUSDT&timeframe=1m"

The server first sends the latest candle, then an update every time the forming candle changes. You send nothing after the handshake:

{
  "type": "candle",
  "meta": { "exchange": "CXBNCE", "symbol": "BTC/USDT", "timeframe": "1m" },
  "tag": 1,
  "isLast": true,
  "candle": {
    "timestamp": "2026-09-24T02:38:00Z",
    "open": "84194.63",
    "high": "84242.01",
    "low": "84194.62",
    "close": "84242.01",
    "volume": "5.09024",
    "sessionType": "MAINSESSION"
  }
}

The first frame carries "isLast": true — it closes the history the stream starts from. Every later frame for the forming candle arrives with "isLast": false and the same timestamp, so update the candle in place instead of appending it.

Errors

A REST error, or a rejected WebSocket handshake, comes back as an HTTP status with a JSON body:

{ "error": { "code": "invalid_argument", "message": "unknown query parameter \"limit\"" } }

Every error uses that shape, and code is stable enough to branch on: invalid_argument for a bad or unknown parameter, unauthenticated for a missing or rejected key, not_found for an exchange or symbol that is not served.

Status	Meaning
`400`	Invalid or unknown query parameter
`401`	Missing or invalid API key
`403`	The key has no access to this data
`404`	Security or data not found
`429`	Credit quota exhausted
`502`, `503`, `504`	Temporary upstream problem, retry later

Next steps

Browse the endpoints in the REST API and WebSocket API groups of this tab.
Read the Overview for what each group returns and how credits are charged.

​Before you start

​1. Find a security

​2. Load historical candles

​3. Subscribe to live candles

​Errors

​Next steps

Before you start

1. Find a security

2. Load historical candles

3. Subscribe to live candles

Errors

Next steps