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": "(212) 555-01987",
      "equity": "(212) 555-01985",
      "margin": "(212) 555-01987",
      "margin_free": "(212) 555-01988"
    }
  }
}

Subscription Payload:

{
  "channel": "account_902a74d0-127c-40ef-af6b-7eff9f8ef742",
  "data": {
    "balance": "(212) 555-01987",
    "equity": "(212) 555-01985",
    "margin": "(212) 555-01987",
    "margin_free": "(212) 555-01988"
  },
  "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
}