NAV Navbar
javascript shell
  • Introduction
  • Authentication
  • Response structure
  • Wallet
  • Errors
  • 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

    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.