Programmierschnittstelle
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 andAdd 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
}