API

Introduction

Welcome to PrimeBit API documentation. PrimeBit offers two types of API:

REST API - with trading functionality
WebSocket API - for realtime updates on public market data and private channels

How to start

Both WebSocket and REST API contain public and private sections.

Public API

Public API is available without any authorization.

Private API

Visit https://app.primebit.com
Sign in
Go to the menu and select Settings
Go to the API keys section and Add API Key

Now you can use api-key and api-secret to access private API functionality.

REST API

General

Version v1 is currently stable. Base REST API endpoint is https://app.primebit.com/api/v1. All available methods are described in Swagger Schema Definition. We also provide Postman Examples with ready-to-go templates (JS authorization script included). This is the simplest way to start using REST API.

Authorization

To access private methods Client must sign HTTP request with additional headers:

"api-key" - api key from PrimeBit Panel
"timestamp" - Unix time in seconds
"authorization" - Base16 encoded HMAC SHA256 signature. HMAC(api-secret, http-verb, request-body, request-path, request-query-string, timestamp).

Signature computation:

Javascript (Node)

const crypto = require("crypto");

function hmac(apiSecret, method, body, path, query, timestamp) {
  const hm = crypto.createHmac('sha256', apiSecret);
  hmac.update(method);
  hmac.update(body);
  hmac.update(path);
  hmac.update(query);
  hmac.update(timestamp);

  return hm.digest('hex');
}

// Cancel order request
// DELETE https://app.primebit.com/api/v1/trading/account/19e8c410-d446-4147-9002-ff7235b5a89f/order/5451233
hmac('api-secret', "DELETE", "", "/api/v1/trading/account/19e8c410-d446-4147-9002-ff7235b5a89f/order/5451233", "", "1570451830");

Request headers Example:

{
  "timestamp": "1570451830",
  "api-key": "dc93094f-393c-441a-8837-eccb7795b618",
  "authorization": "b613679a0814d9ec772f95d778c35fc5ff1697c493715653c6c712144292c5ad"
}

Rate Limits

Public and private API are limited to 5 requests per second. Rate Limiter returns 429 HTTP status code (Too Many Requests) if the rate limit is exceeded.

Error handling

Successful requests will have 2xx HTTP status code in response. Failed requests will have 4xx or 5xx HTTP status code in response.

Error response schema is defined as follows:

{
  "error": {
    "code": "error-code",
    "message": "Human readable error message"
  }
}

REST API SWAGGER

Web Socket API

The base endpoint is: wss://app.primebit.com/api/v0/websocket
There is no rate limiting

Correlation Id

To link together request and response Client should pass correlation_id field in the request. It will be returned in the response.

Ping with correlation_id - request:

{
  "method": "ping",
  "correlation_id": "527d3d2b-a94b-4bb9-a16e-d510923b6060"
}

Ping with correlation_id - response:

{
  "correlation_id": "527d3d2b-a94b-4bb9-a16e-d510923b6060",
  "response": {
    "success": true,
    "message": "pong",
    "data": null
  }
}

Subscriptions

PrimeBit WS API pushes public market data in realtime. To subscribe channel Client should send subscribe request.

Subscription request:

{
  "method": "subscribe",
  "params": ["channel name"]
}

Subscription response:

{
  "correlation_id": null,
  "response": {
    "message": "channel name",
    "success": true,
    "data": null
  }
}

data field in response contains initial state of subscribed channel.

Unsubscribe from channel

To unsubscribe from channel Client should send unsubscribe request.

Unsubscribe request:

{
  "method": "unsubscribe",
  "params": ["channel name"]
}

Unsubscribe response:

{
  "correlation_id": null,
  "response": {
    "message": "successfully unsubscribed channel name",
    "success": true,
    "data": null
  }
}

Public WS API

Raw Ping message

The simplest way to check out the connection.

Raw Ping request:

ping

Raw Ping response:

pong

Structured Ping

Ping message adjusted to WebSocket API schema.

Structured Ping request:

{
  "method": "ping"
}

Structured Ping response:

{
  "correlation_id": null,
  "response": {
    "success": true,
    "message": "pong",
    "data": null
  }
}

Order Book

Top 32 levels of the order book.

Available channels:

order_book_BTCUSD_live
order_book_ETHUSD_live
order_book_LTCUSD_live
order_book_BTCUSD_demo
order_book_ETHUSD_demo
order_book_LTCUSD_demo

Subscription request:

{
  "method": "subscribe",
  "params": ["order_book_BTCUSD_live"]
}

Subscription response:

{
  "correlation_id": null,
  "response": {
    "message": "successfully subscribed to order_book_BTCUSD_live",
    "success": true,
    "data": {
      "asks": [
        {"price":"8011.0","size":"16.9894"}
      ],
      "bids": [
        {"price":"8010.0","size":"2.14"}
      ]
    }
  }
}

Subscription Payload:

{
  {
    "channel": "order_book_BTCUSD_live",
    "data": {
      "bids": [
        {
          "price": "2.1",
          "size": "3"
        }
      ],
      "asks": [
        {
          "price": "2.2",
          "size": "5.1"
        }
      ]
    },
    "message_timestamp_ms": 1571912622664
  }
}

Tick

Ticks are available for BTCUSD, ETHUSD, LTCUSD symbols in market, fair, spot, funding and next-funding categories.

market ticks - last trade price fair ticks - fair price with best ask and best bid from order book

Available channels:

live channels:

BTCUSD:
- tick_BTCUSD_market_live
- tick_BTCUSD_fair_live
- tick_BTCUSD_spot_live
- tick_BTCUSD_funding_live
- tick_BTCUSD_next-funding_live
ETHUSD:
- tick_ETHUSD_market_live
- tick_ETHUSD_fair_live
- tick_ETHUSD_spot_live
- tick_ETHUSD_funding_live
- tick_ETHUSD_next-funding_live
LTCUSD:
- tick_LTCUSD_market_live
- tick_LTCUSD_fair_live
- tick_LTCUSD_spot_live
- tick_LTCUSD_funding_live
- tick_LTCUSD_next-funding_live

demo channels:

BTCUSD:
- tick_BTCUSD_market_demo
- tick_BTCUSD_fair_demo
- tick_BTCUSD_spot_demo
- tick_BTCUSD_funding_demo
- tick_BTCUSD_next-funding_demo
ETHUSD:
- tick_ETHUSD_market_demo
- tick_ETHUSD_fair_demo
- tick_ETHUSD_spot_demo
- tick_ETHUSD_funding_demo
- tick_ETHUSD_next-funding_demo
LTCUSD:
- tick_LTCUSD_market_demo
- tick_LTCUSD_fair_demo
- tick_LTCUSD_spot_demo
- tick_LTCUSD_funding_demo
- tick_LTCUSD_next-funding_demo

Subscription request:

{
  "method": "subscribe",
  "params": ["tick_BTCUSD_market_live"]
}

Subscription response:

{
  "correlation_id": null,
  "response": {
    "message": "successfully subscribed to tick_BTCUSD_market_live",
    "success": true,
    "data": null
  }
}

Subscription Payload:

{
  {
    "channel": "tick_BTCUSD_market_live",
    "data": {
      "ask": null,
      "bid": null,
      "last": "8521.00",
      "timestamp_ms": 1570704691400,
      "volume": "1.2003"
    },
    "message_timestamp_ms": 1571912622664
  }
}

Private WS API

WS Authorization

To authorize private channel subscription Client must append additional params to request:

"api-key" - api key from PrimeBit Panel
"timestamp" - Unix time in seconds
"signature" - HMAC(api-secret, timestamp). HMAC SHA256 signature. Base16 encoded.

Example of signature computation:

Javascript (Node)

const crypto = require("crypto");

function hmac(apiSecret, timestamp) {
  const hm = crypto.createHmac('sha256', apiSecret);
  hm.update(timestamp.toString());

  return hm.digest('hex');
}

Private API Request Example:

{
  "method": "subscribe",
  "params": ["order_902a74d0-127c-40ef-af6b-7eff9f8ef742"],
  "timestamp": "1570451830",
  "api-key": "dc93094f-393c-441a-8837-eccb7795b618",
  "signature": "b613679a0814d9ec772f95d778c35fc5ff1697c493715653c6c712144292c5ad"
}

Order channel

Client can subscribe all changes of orders related to the specific account. Channel name is order_YOUR_ACCOUNT_ID. Authorization fields are required.

Subscription request:

{
  "method": "subscribe",
  "params": ["order_902a74d0-127c-40ef-af6b-7eff9f8ef742"]
}

Where 902a74d0-127c-40ef-af6b-7eff9f8ef742 is the exemplary account id.

Subscription response:

{
  "correlation_id": null,
  "response": {
    "message": "successfully subscribed to order_902a74d0-127c-40ef-af6b-7eff9f8ef742",
    "success": true,
    "data": [
      {
        "login": "3034201",
        "comment: "",
        "contract_size": "0.001",
        "expiration_time": 0,
        "fill_type": "immediate-or-cancel",
        "side": "buy",
        "limit_price": "53.3",
        "order_id": 5075919,
        "stop_price": "0.0",
        "symbol": "LTCUSD",
        "volume": "0.0"
      }
    ]
  }
}

Subscription Payload:

{
  "channel": "order_902a74d0-127c-40ef-af6b-7eff9f8ef742",
  "data": {
    "event_type": "new",
    "order": {
      "login": "3034201",
      "comment: "",
      "contract_size": "0.001",
      "expiration_time": 0,
      "fill_type": "immediate-or-cancel",
      "side": "buy",
      "limit_price": "53.3",
      "order_id": 5075919,
      "stop_price": "0.0",
      "symbol": "LTCUSD",
      "volume": "2.0"
    }
  },
  "message_timestamp_ms": 1571912622664
}

Where event_type can be one of:

new_request
new
fill
partial_fill
reject
modify
modify_reject
cancel
cancel_reject

Where fill_type can be one of:

normal
immediate-or-cancel
fill-or-kill

Where side can be one of:

buy
sell

Account channel

Client can subscribe account balance and margin changes. Channel name is account_YOUR_ACCOUNT_ID. Authorization fields are required.

Subscription request:

{
  "method": "subscribe",
  "params": ["account_902a74d0-127c-40ef-af6b-7eff9f8ef742"]
}

Where 902a74d0-127c-40ef-af6b-7eff9f8ef742 is the exemplary account id.

Subscription response:

{
  "correlation_id": null,
  "response": {
    "message": "successfully subscribed to account_902a74d0-127c-40ef-af6b-7eff9f8ef742",
    "success": true,
    "data": {
      "balance": "1506.93744527",
      "equity": "1506.95849405",
      "margin": "229.35394987",
      "margin_free": "1277.60454418"
    }
  }
}

Subscription Payload:

{
  "channel": "account_902a74d0-127c-40ef-af6b-7eff9f8ef742",
  "data": {
    "balance": "1506.93744527",
    "equity": "1506.95849405",
    "margin": "229.35394987",
    "margin_free": "1277.60454418"
  },
  "message_timestamp_ms": 1571912622664
}

Positions channel

Client can watch all positions on particular account. Channel name is `positions_YOUR_ACCOUNT_ID. Authorization fields are required.

Subscription request:

{
  "method": "subscribe",
  "params": ["positions_902a74d0-127c-40ef-af6b-7eff9f8ef742"]
}

Where 902a74d0-127c-40ef-af6b-7eff9f8ef742 is the exemplary account id.

Subscription response:

{
  "correlation_id": null,
  "response": {
    "message": "successfully subscribed to positions_902a74d0-127c-40ef-af6b-7eff9f8ef742",
    "success": true,
    "data": [
      {
        "price_current": "8272.5",
        "price_open": "8268.5",
        "profit": "0.0000126",
        "volume": "0.0315",
        "side": "sell",
        "position_id": 44421321,
        "symbol": "BTCUSD"
      },
      {
        "price_current": "201.5",
        "price_open": "196.5",
        "profit": "0.2000126",
        "volume": "0.5315",
        "side": "buy",
        "position_id": 53252,
        "symbol": "ETHUSD"
      }
    ]
  }
}

Subscription Payload:

{
  "channel": "positions_902a74d0-127c-40ef-af6b-7eff9f8ef742",
  "data": {
   "event_type":"new",
   "position": {
      "position_id":50148892,
      "price_current":"9293.5",
      "price_open":"9292.5",
      "profit":"1.0",
      "side":"buy",
      "symbol":"BTCUSD",
      "volume":"1.0"
    }
  },
  "message_timestamp_ms": 1571912622664
}

{
  "channel": "positions_902a74d0-127c-40ef-af6b-7eff9f8ef742",
  "data": {
   "event_type":"modified",
   "position": {
      "position_id":50148892,
      "price_current":"9293.5",
      "price_open":"9292.5",
      "profit":"1.0",
      "side":"buy",
      "symbol":"BTCUSD",
      "volume":"3.0"
    }
  },
  "message_timestamp_ms": 1571912622664
}

{
  "channel": "positions_902a74d0-127c-40ef-af6b-7eff9f8ef742",
  "data": {
   "event_type":"closed",
   "position": {
      "position_id":50148892,
      "symbol":"BTCUSD"
    }
  },
  "message_timestamp_ms": 1571912622664
}

Программный интерфейс приложения

Introduction

How to start

Public API

Private API

REST API

General

Authorization

Rate Limits

Error handling

REST API SWAGGER

Web Socket API

Correlation Id

Subscriptions

Unsubscribe from channel

Public WS API

Raw Ping message

Structured Ping

Order Book

Tick

Private WS API

WS Authorization

Order channel

Account channel

Positions channel