NAV Navbar
javascript

Welcome


Are you a Blockchain developer?

Publish your code on Blockchain Web Services Marketplace and
make it easy to find, test, consume and get rewarded for your work.

Contact us to start.

Blockchain Web Services is a powerful blockchain cloud developer platform offering a set of products to build your next blockchain project. We help bring the confidence you need to prototype, test, and ship products faster by getting all the trust you require from the most widely used blockchains like Ethereum or Polygon, and get ready for the next generation like Polkadot or Cardano.

Build with us the new Internet of Trust and bring to your customers the reliability and confidence they need using a simplified API-oriented approach to consume verified smart contracts or interact with private ledger databases for high-performance and cryptographically verifiable transactions.

How It Works

Registration

To start using Blockchain Web Services go to bws.ninja and sign-up. It’s free.

API Endpoint

$.ajax({
    method: 'POST',
    url: 'https://api.bws.ninja/v1/call',
   ...
  });

Blockchain Web Services API baseline endpoint is api.bws.ninja and current version is v1.

As an example, API operation call will use the following URL:

https://api.bws.ninja/v1/call

Authentication

$.ajax({
    ...
    headers: {
      'Content-Type': 'application/json',
      'X-Api-Key': 'my-api-key'
    },
    ...
  });

Calling Blockchain Web Services smart contracts requires a personal API Key to authenticate. To get your key, sign in at bws.ninja and go to My Account > API Key.


BWS Credits

You must include your Key in all of your API calls as a header attribute:

'X-Api-Key': 'my-api-key'

Main API Methods

Use ‘call’ to run a Smart Contract operation and ‘fetch’ to get Smart Contract call status (Smart Contracts execution can take a while to get confirmed from the Blockchain).

A smart contract is a computer program or a transaction protocol which is intended to automatically execute, control or document legally relevant events and actions according to the terms of a contract or an agreement.” The Wikipedia.

'call’ API Method

API call example.

var parameters = {
  "contractId": "Ethereum.Database.Immutable",
  "parameters": {
    ...
  }
};

$.ajax({
  method: 'POST',
  url: 'https://api.bws.ninja/v1/call',
  dataType: 'json',
  data: JSON.stringify(parameters),
  headers: {
    'Content-Type': 'application/json',
    'X-Api-Key': 'ExV0d92KzQ8QgsTVnevddpbB8cUaAfPs7ntVF8g0'
  },
  ...
  });

API call response example

{
  "statusCode": 200,
  "info": {
    "jobId": "543433243"
  }
}

https://api.bws.ninja/v1/call runs a Blockchain Web Services Smart Contract and must contain the following parameters:

Parameter Type Value(s) Description
contract string check Smart Contracts The contract id.
version number 1,2,3,… The contract version to use.
network string ropsten, ethereum The network id to save data to.
operation string check Smart Contracts The operation id to call.
parameters json check Smart Contracts The operation required parameters.

Please note:

‘call’ Response

API call response includes the ‘jobId’ to use to get Smart Contract results.

{ "jobId": "aacee908-3a85-4966-945c-ab8f09ebabf9" }

Check the response object you get when calling Blockchain Web Services API.

‘fetch’ API Method

API call example.

var parameters = {
  "jobId": "b064cc6b-f394-4ca4-9c51-be506e4cc59d",
};

$.ajax({
  method: 'POST',
  url: 'https://api.bws.ninja/v1/fetch',
  dataType: 'json',
  data: JSON.stringify(parameters),
  headers: {
    'Content-Type': 'application/json',
    'X-Api-Key': 'ExV0d92KzQ8QgsTVnevddpbB8cUaAfPs7ntVF8g0'
  },
  ...
  });

Fetch API call response example

{
    "statusCode": 200,
    "statusMessage": "",
    "info": {
        "Status":{ "Value":"registered"},
        "TimestampInMillis":1674504952,
        "Request": {
            "contract": "Ethereum.Database.Immutable ",
            "version": 1,
            "network": "ropsten",
            "operation": "insertBytes32",
            "parameters": {
                "key": "a-key",
                "value": "Hello World!"
            },
            "Guid":"b064cc6b-f394-4ca4-9c51-be506e4cc59d"
        }
}

Use https://api.bws.ninja/v1/fetch to get a previously started Smart Contract call, indicating the jobId you get when running the ‘call’:

Parameter Type Value(s)
jobId string The jobId you get when running a Smart Contract

‘fetch’ Results

The fetch API method will return the status of your Smart Contract call as part of the info parameter:

Parameter Description
Status The current status of Smart Contract execution
TimestampInMillis The status timestamp in milliseconds
Request The original request you did to call the Smart Contract
Result When Status is ‘completed’ the smart contract results
Receipt The outcome of interaction with Ethereum Blockchain
‘fetch’ Status List

A Blockchain Web Services Smart Contract call status can be:

Status Description
registered The job has correctly been registered for execution
running The transaction is running on Blockchain Network
completed Smart Contract call has completed
failed Smart Contract execution has failed

API Calls Response

API success call response example

{
  "statusCode": 200,
  "info": {
    "jobId": "543433243"
  }
}

API call error response example

{
  "statusCode": 404,
  "statusMessage": "incorrect parameters"
}

When calling the API, you can get an HTTP layer transport error, that is, an error that has ocurried before the related API code is executed (e.g. 503, Service Unavailable), or a controlled error, meaning an error that is related to the parameters values you send (e.g. 404, not found - when no data is found for your query).

When no transport layer error is detected, all the API calls will include the next message in the BODY part of the response:

Parameter Type Description
statusCode number The api call result code (e.g. 200 indicates no error).
statusMessage string The status code related message.
info object The requested information

Error Status Codes

The Blockchain Web Services API uses the following error Status Codes:

Status Code Meaning
400 Bad Request – Check your request parameters.
401 Unauthorized – Check your API key
403 Forbidden / Too Many Requests – Slow down!
404 Not Found – Your API key is valid but there is no related user on our servers.
405 Method Not Allowed – You tried to access with an invalid method
406 Not Acceptable – You requested a format that isn’t json
410 Gone – The requested object has been removed
418 I’m a teapot
429 Too Many Requests – Slow down!
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarially offline for maintanance. Please try again later.

Transactions Overview

Go to Blockchain Web Services Management Console and select Jobs List menu option to get the list of executed calls.

Megalock.ninja

For each of the service API calls you execute, select actions menu option to check for the status or the available related information.

Megalock.ninja

Required Funds

Calling Smart Contracts requires funds: “It is the fuel that allows it to operate” (you can check how Gas and Fuel works for Ethereum here). When using Blockchain Web Services you don’t have to worry about buying Cryptos as everytime you call a Smart Contract we will convert your USD credits into the required crypto currency.

To get your account funded go to My Account > Credits and complete your credits purchase.


BWS Credits

Remember funds are only spent when calling smart contracts and there is no extra fee for having a Blockchain Web Services account.

Solutions

BWS Database

A Blockchain is essentially a distributed database that runs on a peer-to-peer network. You can use Blockchain Web Services to insert or select data to/from Blockchain(s) using the following services:

Check the documentation provided by the Author to call those services.

Service

Ethereum.Database.Immutable

An immutable object is an object whose state cannot be modified after it is created

Author

Blockchain Web Services

Description

You can use Ethereum.Database.Immutable operation to save immutable data to blockchain and certify written data will never change.

Contract

Click on Contract Address to check verified contract at etherscan.io.

Network Id Contract Address Version
ethereum 0x58ca3f44cf5c84c1c29591a483be3288d0a01b7c 2
ropsten 0x81D575b53239BcB4332bb1608a21F1A17035deeA 2

Operations

insertBytes32

insertBytes32 operation call example.

var parameters = {
  contract: "Ethereum.Database.Immutable",
  version: 2,
  network: "ropsten",
  operation: "insertBytes32",
  parameters: {
    key: "a-key",
    value: "Hello World!",
  },
};

$.ajax({
  method: "POST",
  url: "https://api.bws.ninja/v1/call",
  data: JSON.stringify(parameters),
  headers: {
    "Content-Type": "application/json",
    "X-Api-Key": "ExV0d92KzQ8QgsTVnevddpbB8cUaAfPs7ntVF8g0",
  },
  dataType: "json",
  success: function (response) {
    console.log(response);
  },
  error: function (xhr, textStatus, errorThrown) {
    console.log(xhr);
  },
});

If successfull, the call will return the related Job Id to fetch for results.

{
  "statusCode": 200,
  "info": {
    "jobId": "543433243"
  }
}

Saves up to 32 characters string value in Ethereum database (check Passing Parameters for other required parameters).

Parameter Value
contract Ethereum.Database.Immutable
operation insertBytes32
parameters check Parameters

Parameters

The following operation parameters can be used to save a string you can later query by using the keyvalue.

Parameter Type Value(s) Description
key string 32 characters string The key for data to save.
value string 32 characters string The value to save on database.
Response

The operation call will return the jobId of the job running on Blochchain Web Services to execute your command (remember blockchain operations are asynchronous and can take a while to finish).

{ "statusCode": 200, "info": { "jobId": "543433243" } }

selectBytes32

selectBytes32 operation parameters call example.

var parameters = {
  contract: "Ethereum.Database.Immutable",
  version: 2,
  network: "ropsten",
  operation: "selectBytes32",
  parameters: {
    key: "a-key",
  },
};

...

Gets a value you previously stored on Ethereum using insertBytes32 (check Passing Parameters for other required parameters).

Parameter Value
contract Ethereum.Database.Immutable
operation selectBytes32
parameters check Parameters
Parameters

Set the key value to get the data you previously saved.

Parameter Type Value(s) Description
key string 32 characters string The key for data to save.
Response

The operation call will return the jobId of the job running on Blochchain Web Services to execute your command (remember blockchain operations are asynchronous and can take a while to finish).

{ "statusCode": 200, "info": { "jobId": "543433243" } }

insertString

insertString operation parameters call example.

var parameters = {
  contract: "Ethereum.Database.Immutable",
  version: 2,
  network: "ropsten",
  operation: "insertString",
  parameters: {
    key: "a-key",
    value: "Hello World!",
  },
};

...

Saves a string value in Ethereum database.

Parameter Value
contract Ethereum.Database.Immutable
operation insertBytes32
parameters check Parameters

Check Passing Parameters for other required parameters.

Parameters

The following operation parameters can be used to save a string you can later query by using the keyvalue.

Parameter Type Description
key string The key for data to save.
value string The value to save on database.
Response

The operation call will return the jobId of the job running on Blochchain Web Services to execute your command (remember blockchain operations are asynchronous and can take a while to finish).

{ "statusCode": 200, "info": { "jobId": "5434323243" } }

selectString

selectString operation parameters call example.

var parameters = {
  contract: "Ethereum.Database.Immutable",
  version: 2,
  network: "ropsten",
  operation: "selectString",
  parameters: {
    key: "a-key",
  },
};

...

Gets a value you previously stored on Ethereum using insertString.

Parameter Value
contract Ethereum.Database.Immutable
operation selectString
parameters check Parameters

Check Passing Parameters for other required parameters.

Parameters

Set the key value to get the data you previously saved.

Parameter Type Description
key string The key for data to save.
Response

The operation call will return the jobId of the job running on Blochchain Web Services to execute your command (remember blockchain operations are asynchronous and can take a while to finish).

{ "statusCode": 200, "info": { "jobId": "5423433243" } }

Service

Ethereum.Database.Mutable

This is in contrast to a mutable object (changeable object), which can be modified after it is created.

Mutable insertString operation parameters call example.

var parameters = {
  contract: "Ethereum.Database.Mutable",
  version: 1,
  network: "ropsten",
  operation: "insertString",
  parameters: {
    key: "a-key",
    value: "Hello World!",
  },
};

Author

Blockchain Web Services

Description

Mutable insert operations can overwrite previously saved data and the same insert/select operations are available for Ethereum.Database.Mutable contract (you just need to replace contract and version parameter to use Mutable or Immutable contract).

Contract

Click on Contract Address to check verified contract at etherscan.io.

Network Id Contract Address Version
ethereum 0x1aFEe6DD9A1D4af90c39CD8B09296FC505beA00d 1
ropsten 0x9089Db83F0590EC2eD01A5Eb4F8584Dd6F4bDaC7 1

Operations

You can use the same operations as for Ethereum.Database.Immuutable service, changing the parameter contract to Ethereum.Database.Mutable.

Use Cases (demos)

MegaLock.ninja

  

MegaLock.ninja is a website anyone can use to securely save data in Ethereum Blockchain.

The website only needs 3 calls to Blockchain Web Services API to save data into Ropsten Network with no need to create any Blockchain account:

Before data is sent to Blockchain Web Services MegaLock.ninja creates RSA key pairs for each user to encrypt and secure data at REST on Ethereum distributed database.

crypto.generateKeyPairSync("rsa", { modulusLength: 2048, });

Saving Data in Ethereum

async function callInsertStringBWSAPI(endpoint, key, value, apiKey) {
  var body = {
    contract: "Ethereum.Database.Mutable",
    version: 1,
    network: "ropsten",
    operation: "insertString",
    parameters: {
      key: key,
      value: value,
    },
  };

  const response = await fetch(endpoint + "/call", {
    method: "post",
    body: JSON.stringify(body),
    headers: {
      "Content-Type": "application/json",
      "X-Api-Key": apiKey,
    },
  });
  const result = await response.json();

  if (result.statusCode != 200) throw new Error(result.statusMessage);

  return result;
}

Fetch API call status and receipt

async function callFetchJobBWSAPI(endpoint, jobId, apiKey) {
  var body = {
    jobId: jobId,
  };

  const response = await fetch(endpoint + "/fetch", {
    method: "post",
    body: JSON.stringify(body),
    headers: { "Content-Type": "application/json", "X-Api-Key": apiKey },
  });
  const result = await response.json();

  if (result.statusCode != 200) throw new Error(result.statusMessage);

  return result;
}

Once the website validates your email address,

Megalock.ninja

enter the data you want to secure in Ethereum database and just click SAVE button.

Megalock.ninja

Megalock.ninja

Once finished, you can check Blockchain transaction on Etherscan (an example for the transaction used for creating those snapshots: https://ropsten.etherscan.io/tx/0x6a3d336dd1..).

Megalock.ninja

Your data is now secured in Blockchain for ever ;)

Getting Data from Ethereum

async function callSelectStringBWSAPI(endpoint, key, apiKey) {
  var body = {
    contract: "Ethereum.Database.Mutable",
    version: 1,
    network: "ropsten",
    operation: "selectString",
    parameters: {
      key: key,
    },
  };

  const response = await fetch(endpoint + "/call", {
    method: "post",
    body: JSON.stringify(body),
    headers: {
      "Content-Type": "application/json",
      "X-Api-Key": apiKey,
    },
  });
  const result = await response.json();

  if (result.statusCode != 200) throw new Error(result.statusMessage);

  return result;
}

Getting you password from Ethereum blockchain is similar to saving. You validate the email you used to save and MegaLock.ninja will call Blockchain Web services to fetch your data.

Megalock.ninja

As for saving, fetching data can take a while, but for reading data from Blockchain it usually goes much faster.

Megalock.ninja

You will get the password or any saved data, copy it to the clipboard and use it as required.

Megalock.ninja