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 marketplace@bws.ninja for more information.

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:

The contract, operation and parameters attributes are used to call any of the Blockchain Web Services available Smart Contracts.
version is used to call a specific Smart Contract implementation.
network is the network you want to use (e.g. ropsten network can be used to test without requiring any funds).
Method parameters must be passed in the Body part of the POST request message using JSON format (Content-Type header attribute must be set to application/json)

‘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

Blockchain Web Services is free, but 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).

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

BWS Credits

Remember Blockchain Web Services is free and funds are spent when calling smart contracts.

Product Services

Are you a Smart Contract developer?

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

Contact marketplace@bws.ninja for more information.

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:

Ethereum.Database.Immutable
Ethereum.Database.Mutable

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:

insertString to save data to Ethereum blockchain,
selectString to get encrypted data from the blockchain, and
fetch to fetch API calls status.

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

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