Introduction
API endpoint
https://api.bbs.money
BBS.money provides a simple and powerful REST API to integrate BBSCoin payments into your business or application.
Supported libraries
- Node.js: bbs-money-client
- PHP: bbs-money-client-php
Developer support
Please join the discord channel for any developer support: Discord development channel
Authentication
Generate and revoke App Key
Each wallet address can generate its own App Id and App Key in Maintance > API access
.
You can generate a new App Key by clicking Geneate a new App Key
.
Or, delete an existing App Key by clicking Revoke the App key
.
Please note the new App Key will replace the old one.
Signing the request
Suppose we have following App Id, App Key, request body and current timestamp:
App Id:123456
App Key:abcdef
Request body:{"hello":"world"}
Current timestamp:1526879890634
The signature paramter should be calculated as:
SHA256-HMAC('{"hello":"world"}1526879890634', 'abcdef')
The request should be sent to:
https://api.bbs.money/api/endpoint?appid=123456&sign=b55a18fa43da483fd6e624b222bed806c905c98d9a3b81b612b9ceebf154d2cf&ts=1526879890634
All request bodies should have content type application/json
and be valid JSON.
Requests must be signed and contain the following query parameters:
Parameter | Description |
---|---|
appid | App Id for the wallet address. |
sign | Signature of the request. |
ts | Current timestamp in milliseconds. |
The sign
parameter is generated by creating a sha256 HMAC using the App Key on string body + timestamp
(where +
represents string concatenation). The timestamp value is the same as the ts
parameter.
Your timestamp must be within 30 seconds of the api service time or your request will be considered expired and rejected.
Response structure
The API endpoints will always return result in following structure.
In the case when you are using a suppported client. The error message will be converted to an exception.
Success
{
"success": true,
"data": {
// reponse payload
}
}
Failure
{
"success": false,
"code": "VALIDATION_ERROR",
"message": "The length of password must be greater than 6"
}
Wallet
Get balance
Request example:
{}
Response example:
{
"address": "wallet address",
"available": "0",
"locked": "0",
"total": "0"
}
Client example:
curl \
-d '{}' \
-H "Content-Type: application/json" \
-X POST https://api.bbs.money/wallet/balance?appid=...&sign=...&ts=...
const { Client } = require('bbs-money-client');
const client = new Client({ "appId": "...", "appKey": "..."});
client.wallet.getBalance().then(data => {
console.log(data);
});
Retrieve the balance of current wallet address.
HTTP Request
POST /wallet/balance
Get transactions
Request example:
{
"offset": 0,
"limit": 10
}
Response example:
[
{
// Transaction hash
"hash": "9342f1c2db197f32ff861530ca6373b9ab9514948300b90db4199d0c30036d74",
// Block index
"height": 83011,
// Timestamp in milliseconds
"timestamp": 1526252697000,
// Amount transferred to this address
"in": "0",
// Amount transferred from this address
"out": "101",
// Transaction fee
"fee": "1",
// Fusion transaction is a special transcation that consolidates small transactions
"fusion": false,
// in - out - fee
"amount": "-101",
// The index of block when this transcations will be unlocked.
"unlockTime": 0,
// Status can be either "normal", "pending", "locked" or "cancelled"
"status": "normal"
}
]
Client example:
curl \
-d '{"offset":0,"limit":10}' \
-H "Content-Type: application/json" \
-X POST https://api.bbs.money/wallet/transactions?appid=...&sign=...&ts=...
const { Client } = require('bbs-money-client');
const client = new Client({ "appId": "...", "appKey": "..."});
client.wallet.getTransactions(0, 10).then(data => {
console.log(data);
});
HTTP Request
POST /wallet/transactions
Request body parameters
Parameter | Type | Default | Description |
---|---|---|---|
offset | integer | 0 | The endpoint will return all pending transactions when offset is set to 0. |
limit | integer | 10 | Defines how many results will be returned. |
Get details of a transcation
Request example:
{
"hash": "transaction hash"
}
Response example:
{
// Transaction hash
"hash": "e42a613ed6923fc02ecc7845b5eefd9110c4774b987ad897f054d9c52f069cad",
// in - out - fee
"amount": "-1288",
// True if this transcation is the mining reward
"coinbase": false,
// Transaction fee
"fee": "1",
// Block index
"height": 73257,
// Network confirmations
"confirmations": 10010,
// Status can be either "normal", "pending", "locked" or "cancelled"
"status": "normal",
// Timestamp in milliseconds
"timestamp": 1525074024000,
// The index of block when this transcations will be unlocked.
"unlockTime": 0,
// Payment id attached when sending the transaction
"paymentId": "",
// Destination address
"destinations": [
{
// Amount send to the address
"amount": "1287",
// Wallet address
"address": "wallet address"
}
]
}
Client example:
curl \
-d '{"hash":"..."}' \
-H "Content-Type: application/json" \
-X POST https://api.bbs.money/wallet/transaction-details?appid=...&sign=...&ts=...
const { Client } = require('bbs-money-client');
const client = new Client({ "appId": "...", "appKey": "..."});
client.wallet.getTransactionDetails("hash").then(data => {
console.log(data);
});
HTTP Request
POST /wallet/transaction-details
Request body parameters
Parameter | Type | Description |
---|---|---|
hash | string | The hash of the transaction. |
Send a transcation
Request example:
{
"mixin": 0,
"fee": "100",
"paymentId": "",
"transfers": [
{
"address": "wallet address",
"amount": "1000"
}
]
}
Response example:
{
"hash": "transaction hash"
}
Client example:
curl \
-d '{"mixin":0,"fee":"1","paymentId":"", "transfers":[{"address":"...","amount":"1000"}]}' \
-H "Content-Type: application/json" \
-X POST https://api.bbs.money/wallet/send?appid=...&sign=...&ts=...
const { Client } = require('bbs-money-client');
const client = new Client({ "appId": "...", "appKey": "..."});
client.wallet.send('address', 'amount', 'fee', 'paymentId', 'mixin').then(data => {
console.log(data);
});
HTTP Request
POST /wallet/send
Request body parameters
Parameter | Type | Default | Description |
---|---|---|---|
mixin | integer | 0 | Anonymity level. |
fee | string | required | Transaction fee. |
paymentId | string | "" | Transaction id to be attached to the transaction. |
transfers | Destination[] | require | Destinations |
Destionation
Parameter | Type | Default | Description |
---|---|---|---|
address | string | required | The destination address. |
amount | string | required | The amount to be sent. |
Errors
The BBS.money API uses the following error codes:
Error Code | Meaning |
---|---|
408 | Server is too busy. |
400 | Invalid parameters or json format. |
401 | App Id, App Key or signature is not correct. |
403 | Unsupported API endpoint. |
404 | Resource not Found. |
500 | Server error, please refer to the specific message. |