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
.
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
andparameters
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 toapplication/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.
For each of the service API calls you execute, select actions
menu option to check for the status or the available related information.
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.
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”
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 key
value.
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 key
value.
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!",
},
};
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,
enter the data you want to secure in Ethereum database and just click SAVE button.
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..).
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.
As for saving, fetching data can take a while, but for reading data from Blockchain it usually goes much faster.
You will get the password or any saved data, copy it to the clipboard and use it as required.