API Miner (1.0.6)

This document describes the specification for the API Miner public API.

Download Swagger 2.0 Specification

Open Source

We've begun to release sample code on GitHub, starting with:

Quickstart

There are two options for quickstart:

  1. Using the curl command line tool, which is commonly already installed on many systems.
  2. (WIP) Using the Postman HTTP client.

Access token

You'll need an API Miner access token to go through the quickstarts.

We're giving out access tokens on the Blockwell Spout environment for our Win 10 ETH in 10 Mins competition. Follow the link for details.

curl

Prerequisites

curl is used in a terminal, so some familiarity with running a command line terminal is needed. All commands in this curl section are intended to be typed into a terminal. Most of them will also need some values inserted, and those are marked with <value>. For example, if you see:

    "<address>"

You should replace it with the proper address like this:

    "0x4a4f61b39873b96429a261ba04fd0d8c5368d2c7"

You'll need curl itself installed. You can test to see if it's already installed by running:

curl --version

If it's not installed, install it using the appropriate installation method for your system:

  • Linux
    • Debian and derivatives: sudo apt-get install curl
    • Arch and derivatives: pacman -S curl
    • Fedora: yum install curl
  • Mac OS X
    • If you don't have it, first install Homebrew
    • Then run brew install curl
  • Windows
    • NOTE! The curl commands in this quickstart won't work in Windows' cmd or PowerShell terminals without modification. We recommend using Postman, or some other REST client.
    • Download the curl binary here and add it to your PATH.

1. List accounts

You should've already received the address of your first Ethereum account on API Miner, but as the first step we'll go ahead and list all of our accounts.

First, edit the following curl command:

  • replace <token> with your access token.
curl -X GET \
https://spout.apiminer.com/accounts \
-H 'Authorization: Bearer <token>'

As mentioned earlier, copy and paste the curl command to your terminal. Make sure you get the whole command, as it's split on multiple lines for easier reading.

The response will look like this, except it will be unformatted:

{
    "data": [
        {
            "id": "9a5d68bd-84d7-4ec0-8b11-642de45b1d5d",
            "address": "0x897a705d4ae51e66f9e64a0ff446e65b55c47385",
            "owner": "df9dd7fc-9007-49f2-b92a-e7952d4d9ca3",
            "defaultAccount": true
        }
    ]
}

The id is the globally unique identifier of this account, and the address is the Ethereum address of the account. You'll need the address for some of the quickstart steps.

2. Getting Pump tokens

Next, call the mint function on the Pump token smart contract to get yourself some tokens.

Use the following with:

  • <token> replaced with your access token.
  • <address> replaced with your account address.
curl -X POST \
https://spout.apiminer.com/contracts/e2e5d13a-5db6-44c9-8767-a2e9eaf90e6f/send/mint \
-H 'Authorization: Bearer <token>' \
-H 'Content-Type: application/json' \
-d '{
    "arg": [
    "<address>", 
    "100000000000000000000"
    ]
}'

The response will look like this:

{
    "data": {
        "id": "fffc6603-490f-4797-aa1f-394a696fe4be",
        "status": "new",
        "created": "2018-08-14T21:42:55.968Z"
    }
}

Since transactions on the blockchain take some time, the API doesn't wait for it to finish, it just gives you an ID that you can use to refer to it later.

3. Getting the status of a transaction

To see what happened to the transaction from the previous step, use the following with:

  • <id> replaced with the transaction ID you received in the previous step.
  • <token> replaced with your access token.
curl -X GET \
https://spout.apiminer.com/transactions/<id> \
-H 'Authorization: Bearer <token>'

The transfer should be completed within 15 seconds, after which you'll see the following response:

{
    "data": {
        "id": "fffc6603-490f-4797-aa1f-394a696fe4be",
        "status": "completed",
        "created": "2018-08-14T21:42:55.968Z",
        "submitted": "2018-08-14T21:42:56.598Z",
        "ended": "2018-08-14T21:43:07.613Z",
        "transactionHash": "0x8d9fb9f1e21ea30ab04e2ab17009e2b6af0e9498ed488ae974d7d4d59ee9f781"
    }
}

The status showing completed means the call was successful.

4. Getting your token balance

To double check that you did actually get the Pump tokens, use:

  • <token> replaced with your access token.
curl -X GET \
https://spout.apiminer.com/tokens/e2e5d13a-5db6-44c9-8767-a2e9eaf90e6f/balances/default \
-H 'Authorization: Bearer <token>'

This will get the token balance for token ID e2e5d13a-5db6-44c9-8767-a2e9eaf90e6f - which is the Pump token - for your default account.

The response is as follows:

{"data":"100000000000000000000"}

5. Creating an Ethereum account

To create a second Ethereum account, use:

  • <token> replaced with your access token.
curl -X POST \
https://spout.apiminer.com/accounts \
-H 'Authorization: Bearer <token>'

The response is as follows:

{
    "data": {
        "id": "8afe086b-2cb8-4feb-bfbe-064a996e137a",
        "address": "0x632777aeb73f955a660817d5f1ab1a36365485aa",
        "owner": "36731315-1ec0-4ad2-99a9-c7c3e22dce9f",
        "defaultAccount": false
    }
}

Note that this new account is not your default account, so it will only be used if you specify it in the API calls. We'll look at how to do that below.

6. Transferring tokens

To transfer 2 PMP tokens from your default account to the newly created one, use:

  • <token> replaced with your access token.
  • <address> replaced with the address of your second account.
curl -X POST \
https://spout.apiminer.com/tokens/e2e5d13a-5db6-44c9-8767-a2e9eaf90e6f/transfers \
-H 'Authorization: Bearer <token>' \
-H 'Content-Type: application/json' \
-d '{
    "to": "<address>",
    "value": "2000000000000000000"
}'

The response is as follows:

{
    "data": {
        "id": "1be96ada-4b5c-4edc-8d3b-f79ee222e586",
        "status": "new",
        "created": "2018-08-15T19:20:46.576Z"
    }
}

As before, the response refers to a transaction, rather than the result of the transfer. Refer to step 3 to check on the status of the transaction.

7. Get the token balance of another account

In step 4 we retrieved the balance of your default account, but you can also query the balance of any other account by their address.

To check the balance of your second account, use:

  • <token> replaced with your access token.
  • <address> replaced with the address of your second account.
curl -X GET \
https://spout.apiminer.com/tokens/e2e5d13a-5db6-44c9-8767-a2e9eaf90e6f/balances/<address> \
-H 'Authorization: Bearer <token>'

The response is as follows:

{
    "data": "2000000000000000000"
}

8. Return half of the tokens

To demonstrate sending tokens from a non-default account, we'll send half of the tokens back:

  • <token> replaced with your access token.
  • <new-address> replaced with the address of your second account.
  • <default-address> replaced with the address of your default account.
curl -X POST \
https://spout.apiminer.com/tokens/e2e5d13a-5db6-44c9-8767-a2e9eaf90e6f/transfers \
-H 'Authorization: Bearer <token>' \
-H 'Content-Type: application/json' \
-d '{
    "from": "<new-address>",
    "to": "<default-address>",
    "value": "1000000000000000000"
}'

The response is as follows:

{
    "data": {
        "id": "e3981e4b-d31e-47f4-862e-ccdb3b39ccce",
        "status": "new",
        "created": "2018-08-15T19:32:33.153Z"
    }
}

As before, refer to step 3 to get the status of the transaction.

Postman

Prerequisites

You'll need Postman installed, follow their documentation for installation.

At the top of this document is a link to the Swagger 2.0 specification for the API. Download the spec and import it into Postman.

import

Then edit the API Miner collection:

edit

Go to the Authorization tab, change the TYPE to Bearer Token, and type in {{token}} into the Token field.

edit auth

Next, create a new Postman environment by clicking the gear icon:

gear

In the top-right corner. Click the Add button, and configure the new environment as follows:

environment

  • host: spout.apiminer.com
  • token: Your access token
  • contractId: e2e5d13a-5db6-44c9-8767-a2e9eaf90e6f

You can now use the API Miner collection to make calls to the API.

1. List accounts

You should've already received the address of your first Ethereum account on API Miner, but as the first step we'll go ahead and list all of our accounts.

list accounts

Find the "GET List accounts" endpoint, and click Send.

You'll see a response like this:

{
    "data": [
        {
            "id": "9a5d68bd-84d7-4ec0-8b11-642de45b1d5d",
            "address": "0x897a705d4ae51e66f9e64a0ff446e65b55c47385",
            "owner": "df9dd7fc-9007-49f2-b92a-e7952d4d9ca3",
            "defaultAccount": true
        }
    ]
}

The id is the globally unique identifier of this account, and the address is the Ethereum address of the account. You'll need the address for some of the quickstart steps.

2. Getting Pump tokens

contract send

Next, use the "POST Contract send call" endpoint to call the token contract with the token minting function.

Click "Params" and replace {{method}} with mint.

Use the following Body with:

  • <address> replaced with your account address from the first step.
{
    "arg": [
    "<address>", 
    "100000000000000000000"
    ]
}

Like this:

mint parameters

The response will look like this:

{
    "data": {
        "id": "fffc6603-490f-4797-aa1f-394a696fe4be",
        "status": "new",
        "created": "2018-08-14T21:42:55.968Z"
    }
}

Since transactions on the blockchain take some time, the API doesn't wait for it to finish, it just gives you an ID that you can use to refer to it later.

3. Getting the status of a transaction

get a transaction

To see what happened to the transaction from the previous step, use the "POST Get a transaction" endpoint. Simply change the id in Params to match the ID from the response in the previous step.

The transfer should be completed within 15 seconds, after which you'll see the following response:

{
    "data": {
        "id": "fffc6603-490f-4797-aa1f-394a696fe4be",
        "status": "completed",
        "created": "2018-08-14T21:42:55.968Z",
        "submitted": "2018-08-14T21:42:56.598Z",
        "ended": "2018-08-14T21:43:07.613Z",
        "transactionHash": "0x8d9fb9f1e21ea30ab04e2ab17009e2b6af0e9498ed488ae974d7d4d59ee9f781"
    }
}

The status showing completed means the call was successful.

4. Getting your token balance

To double check that you did actually get the Pump tokens, use the "GET Default account balance" endpoint.

default account balance

No parameter changes are needed, just hit Send.

The response is as follows:

{"data":"100000000000000000000"}

5. Creating an Ethereum account

create account

To create a second Ethereum account, use the "POST Create account" endpoint.

No parameter changes are needed, just hit Send, and you'll see a response like this:

{
    "data": {
        "id": "8afe086b-2cb8-4feb-bfbe-064a996e137a",
        "address": "0x632777aeb73f955a660817d5f1ab1a36365485aa",
        "owner": "36731315-1ec0-4ad2-99a9-c7c3e22dce9f",
        "defaultAccount": false
    }
}

Note that this new account is not your default account, so it will only be used if you specify it in the API calls. We'll look at how to do that below.

6. Transferring tokens

transfer tokens

To transfer 2 PMP tokens from your default account to the newly created one, use the "POST Transfer tokens" endpoint.

In Body, change the to address to match the second account's address you created in the previous step:

transfer body

Then hit Send. The response is as follows:

{
    "data": {
        "id": "1be96ada-4b5c-4edc-8d3b-f79ee222e586",
        "status": "new",
        "created": "2018-08-15T19:20:46.576Z"
    }
}

As before, the response refers to a transaction, rather than the result of the transfer. Refer to Step 3 to check on the status of the transaction.

7. Get the token balance of another account

In Step 5 we retrieved the balance of your default account, but you can also query the balance of any other account by their address.

To check the balance of your second account, use the "GET Token balance" endpoint.

token balance

In Params, change the address value to match your second account's address.

Hit Send. The response is as follows:

{
    "data": "2000000000000000000"
}

8. Return half of the tokens

To demonstrate sending tokens from a non-default account, we'll send half of the tokens back, again using "POST Transfer tokens".

transfer tokens

This time, replace the Body with the following:

  • <new-address> replaced with the address of your second account.
  • <default-address> replaced with the address of your default account.
{
    "from": "<new-address>",
    "to": "<default-address>",
    "value": "1000000000000000000"
}

Like this:

transfer from body

Hit Send. The response is as follows:

{
    "data": {
        "id": "e3981e4b-d31e-47f4-862e-ccdb3b39ccce",
        "status": "new",
        "created": "2018-08-15T19:32:33.153Z"
    }
}

As before, refer to step 3 to get the status of the transaction.

Conventions

JSON response format

JSON responses always have either data or error as a top-level property. Any actual response data will be accessible under the data property to ensure there are no naming conflicts with top-level errors.

Error details

Error details are only displayed on testing environments. When present, the error response contains a details property with more information, for example:

{
    "error": {
        "error": "bad_query",
        "message": "Invalid query format",
        "details": {
            "validation": ["'limit' must be a positive integer"]
        }
    }
}

Datetime

Dates and times are always displayed according to RFC 3339 5.6, in UTC.

Ether and Token amounts

All amounts are specified in the smallest unit available. For example, Ether uses wei.

The amounts are expected as strings, because number formats usually don't have enough precision.

Callbacks

Some endpoints allow specifying callbacks that get called when the action completes. Most notably all actions that create Ethereum transactions.

Callbacks are always expected as full URLs, either http or https, and as an array. If only one callback is desired, simply provide it as a single-item array.

Callbacks are always POST request with a JSON payload. The URL specified will be called verbatim, without any changes to the request path or query string.

The callback will be attempted 4 times, or until a 2xx response is given, with an increasing delay between attempts.

Callback data

Callback-enabled endpoints can optionally be called with a callbackData body parameter, which will be added to the actual callback request. This can be used to identify specific callbacks, or pass data around.

There are certain restrictions on this data to avoid security concerns:

  • callbackData itself has to be an object.
  • Keys in the object can only be alphanumeric.
  • Values can only be a string, number, boolean or array. No objects.
  • Arrays can only contain strings or numbers.
  • The size is limited to 5 kB.

Note that you shouldn't blindly trust the contents of callbackData without ensuring that the transaction is actually legitimate. If an attacker knows the callback URL of your application, they can have API Miner make callbacks to your server as well.

Callback security

Callback payloads are signed using public-key cryptography, with the signature given in the Apiminer-Signature header of the request.

The format for the header is as follows (white-space added for clarity):

Apiminer-Signature: keyid=<key-id>;
                    algorithm=SHA256;
                    signature=<signature>

The signature is made with the entire POST body of the request. The signing algorithm depends on the key being used, but would typically be RSA. The hash algorithm is specified in the header, currently SHA-256. The signature itself is hex-encoded.

The callback body contains two fields that can be used to improve security further.

Timestamp contains the millisecond timestamp for when API Miner initiated the callback network request. This can be used to verify the timing of the callback isn't off.

Owner contains the ID of the user account that triggered the callback. Use this to ensure that it was really your application that made the original request.

In addition, feel free to add your own signing schemes to the callbackData fields to ensure they are not tampered with.

Public keys

The public keys can be retrieved from the API, but it's not recommended to do this automatically in production applications. The default key should be fetched manually.

In all but the most extreme circumstances, the default key will continue to work, and ample warning will be given before expiration.

Callback examples

Callbacks can have slightly different data depending on what they were created from, but they all have the same basic format:

{
    "timestamp": 1532552777448,
    "owner": "",
    "payload": { },
    "callbackData": { },
}
  • timestamp is just the timestamp when API Miner initiated the callback request. Since it is signed data, it can be used as additional verification.
  • owner is the ID of the account that initiated the work leading to the callback.
  • payload is the actual data of the event, typically a transaction.
  • callbackData contains the data given to API Miner in the original API call that initiated the action.

Token transfer succeeded

{
    "timestamp": 1532552777448,
    "owner": "4b17b28b-2409-54b6-bf43-f36fe8bced4e",
    "payload": {
        "id": "8c9a4558-93cb-4d6a-821c-77ea1ca9adad",
        "status": "completed",
        "created": "2018-06-08T19:04:14.216Z",
        "submitted": "2018-06-08T19:04:14.980Z",
        "ended": "2018-06-08T19:04:29.050Z",
        "transactionHash": "0xe1eabd59aea1857bc5eb52d42415b76cfe539e9d650903d85accd3cd9c3d36c0"
    }
}

Token transfer failed

{
    "timestamp": 1532552777448,
    "owner": "4b17b28b-2409-54b6-bf43-f36fe8bced4e",
    "payload": {
        "id": "8c9a4558-93cb-4d6a-821c-77ea1ca9adad",
        "status": "error",
        "created": "2018-06-08T19:04:14.216Z",
        "submitted": "2018-06-08T19:04:14.980Z",
        "ended": "2018-06-08T19:04:29.050Z",
        "error": "Transaction ran out of gas. Please provide more gas",
        "transactionHash": "0xe1eabd59aea1857bc5eb52d42415b76cfe539e9d650903d85accd3cd9c3d36c0"
    }
}

Token transfer succeeded with user ID in callback data

{
    "timestamp": 1532552777448,
    "owner": "4b17b28b-2409-54b6-bf43-f36fe8bced4e",
    "payload": {
        "id": "8c9a4558-93cb-4d6a-821c-77ea1ca9adad",
        "status": "completed",
        "created": "2018-06-08T19:04:14.216Z",
        "submitted": "2018-06-08T19:04:14.980Z",
        "ended": "2018-06-08T19:04:29.050Z",
        "transactionHash": "0xe1eabd59aea1857bc5eb52d42415b76cfe539e9d650903d85accd3cd9c3d36c0"
    },
    "callbackData": {
        "userId": 123
    }
}

Contract deployment succeeded

{
    "timestamp": 1532552777448,
    "owner": "4b17b28b-2409-54b6-bf43-f36fe8bced4e",
    "payload": {
        "id": "8c9a4558-93cb-4d6a-821c-77ea1ca9adad",
        "status": "completed",
        "created": "2018-06-08T19:04:14.216Z",
        "submitted": "2018-06-08T19:04:14.980Z",
        "ended": "2018-06-08T19:04:29.050Z",
        "transactionHash": "0xe1eabd59aea1857bc5eb52d42415b76cfe539e9d650903d85accd3cd9c3d36c0",
        "contract": {
            "id": "6ab34922-0561-48b7-9e11-ce1581e100f2",
            "address": "0x418f8020b48731ffd2a99afe0aa5e7d66ca263d8"
        }
    }
}

Ethereum networks

API Miner can interact with any arbitrary Ethereum network as long as a connection to it has been made. This means that sometimes a request needs to specify which network it's operating on.

When a network needs to be specified, it's typically specified using the system name for that network, although chain ID is also accepted. For example, to use the main Ethereum network, you'd specify either "main" or 1 - the two are equivalent.

Current networks

The following networks are currently known to API Miner.

pictor

Beta API Miner network, Clique Proof of Authority.

spout

Spout network, only available on the Spout environment, and it's the only network on that environment.

main

The main Ethereum network.

Smart Contract Types

The following contract types are currently available in API Miner. If a different contract is needed, contact us.

ERC-20

Type code: erc20

Standard ERC-20 token, with the Human Standard Token additions for name, decimals and symbol.

  • Does not allow minting new tokens, only the initial supply exists.
  • Has approve, transferFrom, and allowance.
  • No admins, or owner special powers.

Accepts the following additional parameters:

  • symbol Token symbol.
  • decimals Number of decimals for the token.
  • holder Address to hold the initial supply of tokens.
  • supply Total supply of tokens that will be given to the holder address.

ERC-20 Security

Type code: erc20_security

This is not legal advice, consult a securities lawyer in your jurisdiction to ensure compliance with disclosure, filing, and trading regulations. Blockwell is a development platform and makes no representation of legal advice or advocation in default settings. All fields are configurable and decided by the policy you input and enforced onchain. Blockwell makes no warranties over use of this API Call, is not a custodian of these assets, and will require founder KYC and terms acceptance prior to usage of this feature in production networks.

This is an ERC-20 token with additional functionality for representing and trading potential securities. By default tokens are locked for 12 months to comply with all Reg D offerings but lockup periods are configurable. Lockups are set upon initial token transfer from the token owner to the recipients wallet for the transferred amount.

This token supports variable lockup amounts even in the same wallet (such as advisors with 3 and 6 month lockups) by using setLockTime and sending the new batch to be locked for that period. This can support token lockups for Founders Tokens, Foundation Pools, Bounties, Syndicates, Market Makers, etc. Implementation details:

  • transferAndLock(address, uint256) will lock the transferred tokens from being used. The lock expires in current time plus lockTime, which defaults to 366 days. The extra day is to account for leap years.
  • When receiving locked tokens, both a Transfer and a Locked event will be emitted.
  • Calling unlock() will unlock all expired locks on the sender account (vested, now liquid tokens). Note that calling unlock() is only necessary if you want to unlock tokens without also transferring them, as transfer unlocks them automatically.
  • Unlocking through any means will always emit an Unlock event.
  • totalLocked(address) returns the total amount of tokens locked for the given account.
  • totalUnlockable(address) returns the amount of tokens that could be unlocked right now.
  • balanceOf(address) reflects all tokens, including locked ones. This is to ensure people see token balances change in various wallet software.
  • unlockedBalanceOf(address) returns token balances excluding any locked tokens.
  • transfer(address, uint256) functions mostly the same as with ERC-20, except it will also unlock funds if there are any to be unlocked.
  • locksOf(address) returns an array representing all the locks on the given account, in the following format: [value1, expiration1, value2, expiration2, ...]
  • setLockTime(uint) lets the contract owner set a new lockTime to change the default 366 day expiration. This will emit a LockTimeChange event for transparency. The time needs to be specified in seconds, so for example the 366 days is specified as 31622400.
  • Note that changing lockTime does not affect existing locks, only ones that are made after setLockTime is called. When transferAndLock is called, the expiration is set to a specific time (default is 366 days in the future), and it cannot be changed through any means.
  • The unlock command marks all vested tokens as unlocked. It is optional as receiver trying to transfer a vested token updates the status for vested tokens. Not calling unlock has the side benefit of being able to track exactly when and how your token behaves after a lockup ends by analyzing timestamps and wallets of Unlock events.

Accepts the following additional parameters:

  • symbol Token symbol.
  • decimals Number of decimals for the token.
  • holder Address to hold the initial supply of tokens.
  • supply Total supply of tokens that will be given to the holder address.

Ego Coin

Type code: ego

An ERC-20 compatible token with the following special properties:

  • No initial supply of tokens.
  • No decimals.
  • Role-based access control, with the owner given admin status.
  • Tokens are given using the reward method, callable by admins.

Accepts no additional parameters.

Rate limiting

All users are limited to 5 requests per second, and each user can have at most 5 pending transactions.

Contact us if you need higher limits.

Contact

Contact us at:

Where Why
blockwell@blockwell.ai General inquiries
devhelp@blockwell.ai Assistance with API Miner development issues
Blockwell Telegram General Blockwell chat

Changelog

1.0.6

  • Transactions now output additional data, including contract ID, method, parameters and events.
  • New endpoint GET /transactions for retrieving a list of past transactions.

1.0.5

  • ERC-20 Security contract type.

1.0.4

  • Postman quick start.

1.0.3

  • Added curl quickstart.
  • Added the Spout environment.
  • Added spout Ethereum network.

1.0.2

  • Added auth and ownerless flags to creating new users.
  • Added auth token to POST user response.
  • Added account flag to creating new users.
  • Added account to POST user response.

1.0.1

  • Changed /contracts/{contractId}/send/{method} to accept any type in the arg parameter to allow for array arguments to methods.
  • Fixed some links in the descriptions.

Authentication

ApiKeyAuth

API key must be given as a Bearer token.

Security scheme type: API Key
header parameter name: Authorization: Bearer <token>

Generic responses

This describes the generic responses that are not specific to an endpoint.

Authorizations:

Responses

400

Unable to process request due to client error

401

Authorization refused

403

Missing authorization

404

Resource not found

500

Generic server error

502

Upstream service error

get /
Blockwell Spout
https://spout.apiminer.com/
Debug environment
https://debug.apiminer.com/

Response samples

application/json
Copy
Expand all Collapse all
{
  • "error":
    {
    }
}

tokens

List tokens

List Token contracts belonging to the current user.

Authorizations:
query Parameters
network
string

Optional. Filter by network, see Ethereum networks.

name
string

Optional. Filter by Token name.

symbol
string

Optional. Filter by Token symbol.

Responses

200

Success

Response Schema: application/json
data
Array of object
get /tokens
Blockwell Spout
https://spout.apiminer.com/tokens
Debug environment
https://debug.apiminer.com/tokens

Response samples

application/json
Copy
Expand all Collapse all
{
  • "data":
    [
    ]
}

Token by ID

Get a specific token by its unique identifier.

Authorizations:
path Parameters
contractId
required
string

ID of the token

Responses

200

Success

Response Schema: application/json
data
object (Token contract)
404

Not found

get /tokens/{contractId}
Blockwell Spout
https://spout.apiminer.com/tokens/{contractId}
Debug environment
https://debug.apiminer.com/tokens/{contractId}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "data":
    {
    }
}

Default account balance

Get the specified token balance for the current user's default account.

Authorizations:
path Parameters
contractId
required
string

ID of the token.

Responses

200

Success

Response Schema: application/json
data
string

Token balance of the address in the smallest unit.

404

Not found

get /tokens/{contractId}/balances/default
Blockwell Spout
https://spout.apiminer.com/tokens/{contractId}/balances/default
Debug environment
https://debug.apiminer.com/tokens/{contractId}/balances/default

Response samples

application/json
Copy
Expand all Collapse all
{
  • "data": "1000000000000000000"
}

Token balance

Get the specified token balance for a specific account.

Authorizations:
path Parameters
contractId
required
string

ID of the token.

address
required
string

Address to get balance for.

Responses

200

Success

Response Schema: application/json
data
string

Token balance of the address in the smallest unit.

404

Not found

get /tokens/{contractId}/balances/{address}
Blockwell Spout
https://spout.apiminer.com/tokens/{contractId}/balances/{address}
Debug environment
https://debug.apiminer.com/tokens/{contractId}/balances/{address}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "data": "1000000000000000000"
}

Token transfer history

Gets the transfer history for the specified token.

Authorizations:
query Parameters
from
string

Filter transfers by the from address.

to
string

Filter transfers by the to address.

address
string

Filter transfers where this address is either the sender or recipient.

Responses

200

Success

Response Schema: application/json
data
Array of object
get /tokens/{contractId}/transfers
Blockwell Spout
https://spout.apiminer.com/tokens/{contractId}/transfers
Debug environment
https://debug.apiminer.com/tokens/{contractId}/transfers

Response samples

application/json
Copy
Expand all Collapse all
{
  • "data":
    [
    ]
}

Transfer tokens

Submit a Token transfer to the blockchain.

Success means the transfer was accepted for processing, but there are no guarantees as to when the processing will be done. Processing happens on first-come-first-served basis.

A successful response contains a unique ID for the transaction, which can then be used to query its status.

Passing the optional callbacks parameter in the body will add a web callback that gets called once the transaction completes.

The callback payload is {"transaction": Transaction}, with the same formatting as with getting a transaction.

Authorizations:
path Parameters
contractId
required
string

ID of the token.

Request Body schema: application/json
to
required
string

Ethereum address to send Tokens to.

value
required
string^[0-9]$

Amount of Tokens to transfer, in the Token's smallest unit.

from
string

Address to send from, as either an Ethereum address, or an account ID.

If not specified, the current user's default account will be used.

callbacks
Array of string

Callback URL(s) to be notified when the Token transfer completes. See Callbacks for more details.

callbackData
object

An object holding data that the callbacks will contain.

Responses

202

Transfer accepted

Response Schema: application/json
data
object (Transaction)
post /tokens/{contractId}/transfers
Blockwell Spout
https://spout.apiminer.com/tokens/{contractId}/transfers
Debug environment
https://debug.apiminer.com/tokens/{contractId}/transfers

Request samples

application/json
Copy
Expand all Collapse all
{
  • "to": "0x98c4A022C1492Cc8a59F75295FBCf4a9F1Bc7cE8",
  • "value": "1000000000000000000",
  • "from": "bf15bdb2-0574-5982-a199-08fab9ac59f1",
  • "callbackData": "{ "userId": "12345" "data": "foo" } "
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "data":
    {
    }
}

contracts

List Contracts

List Contracts belonging to the current user.

Authorizations:
query Parameters
network
string

Optional. Filter by network, see Ethereum networks.

name
string

Optional. Filter by Contract name.

Responses

200

Success

Response Schema: application/json
data
Array of object
get /contracts
Blockwell Spout
https://spout.apiminer.com/contracts
Debug environment
https://debug.apiminer.com/contracts

Response samples

application/json
Copy
Expand all Collapse all
{
  • "data":
    [
    ]
}

Deploy contract

Deploy a new smart contract.

This endpoint allows you to create a new deployment of a smart contract "template" in the system. For more details, see Smart Contract Types.

Success means the deployment was accepted for processing, but there are no guarantees as to when the processing will be done. Processing happens on first-come-first-served basis.

Contract deployments are basically just like regular Ethereum transactions, so a successful response will contain a transaction ID. That ID can then be used to query its status.

Passing the optional callbacks parameter in the body will add a web callback that gets called once the transaction completes. See Callbacks for more details.

Authorizations:
Request Body schema: application/json
name
required
string

Full name for the Contract.

network
required
string

The network the contract should be deployed on, see Ethereum networks.

type
required
string

Type of contract to deploy. See Smart Contract Types for details.

account
string

ID of the account to deploy under. If not specified, the user's default account will be used.

parameters
object

Parameters to be used when creating the contract. The different possible parameters are described under Smart Contract Types.

callbacks
Array of string

Callback URL(s) to be notified when the deployment completes. See Callbacks for more details.

callbackData
object

An object holding data that the callbacks will contain.

Responses

202

Contract deployment accepted

Response Schema: application/json
data
object (Transaction)
post /contracts
Blockwell Spout
https://spout.apiminer.com/contracts
Debug environment
https://debug.apiminer.com/contracts

Request samples

application/json
Copy
Expand all Collapse all
{
  • "name": "API Miner Coin",
  • "network": "spout",
  • "type": "erc20",
  • "parameters":
    {
    }
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "data":
    {
    }
}

Contract by ID

Get a specific Contract by its unique identifier.

Authorizations:
path Parameters
contractId
required
string

ID of the Contract

Responses

200

Success

Response Schema: application/json
data
object (Smart contract)
404

Not found

get /contracts/{contractId}
Blockwell Spout
https://spout.apiminer.com/contracts/{contractId}
Debug environment
https://debug.apiminer.com/contracts/{contractId}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "data":
    {
    }
}

Contract view call

Make a view-only Contract call that isn't a transaction.

As an example, an ERC-20 token's balanceOf method is view-only.

Authorizations:
path Parameters
contractId
required
string

ID of the Contract.

method
required
string

Contract method to call.

query Parameters
arg
Array of any

Method arguments.

The server expects the 'arg' query string variable to repeat for multiple array elements, eg. arg=argument1&arg=argument2

Responses

200

Success

Response Schema: application/json
data
any

Return value of the Contract call.

404

Not found

get /contracts/{contractId}/call/{method}
Blockwell Spout
https://spout.apiminer.com/contracts/{contractId}/call/{method}
Debug environment
https://debug.apiminer.com/contracts/{contractId}/call/{method}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "data": "1000000000000000000"
}

Contract send call

Submit a Contract method transaction to the blockchain.

This is required for making smart Contract method calls that change state, such as the ERC-20 token's transfer method.

Success means the transaction was accepted for processing, but there are no guarantees as to when the processing will be done. Processing happens on first-come-first-served basis.

A successful response contains a unique ID for the transaction, which can then be used to query its status.

Passing the optional callbacks parameter in the body will add a web callback that gets called once the transaction completes.

The callback payload is {"transaction": Transaction}, with the same formatting as with getting a transaction.

Authorizations:
path Parameters
contractId
required
string

ID of the Contract.

method
required
string

Contract method to call.

Request Body schema: application/json
from
string

Address to send from, as either an Ethereum address, or an account ID.

If not specified, the current user's default account will be used.

arg
Array of any

Array of arguments to pass to the contract method call.

callbacks
Array of string

Callback URL(s) to be notified when the Token transfer completes. See Callbacks for more details.

callbackData
object

An object holding data that the callbacks will contain.

Responses

202

Contract transaction accepted

Response Schema: application/json
data
object (Transaction)
post /contracts/{contractId}/send/{method}
Blockwell Spout
https://spout.apiminer.com/contracts/{contractId}/send/{method}
Debug environment
https://debug.apiminer.com/contracts/{contractId}/send/{method}

Request samples

application/json
Copy
Expand all Collapse all
{
  • "from": "bf15bdb2-0574-5982-a199-08fab9ac59f1",
  • "arg":
    [
    ],
  • "callbackData": "{ "userId": "12345" "data": "foo" } "
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "data":
    {
    }
}

Contract event history

Gets the log history for a specific event for a specific Contract.

All query parameters will be passed as filters to event parameters. This lets you filter on indexed event parameters. For example, to get all token transfer events from a particular address, you could use:

?from=0x9A83706D363e2Fd14103f587EA4bb27B2b2f3Ae6

Multiple entries of a parameter will be added as an OR to the filter, for example to get all transfers from two different addresses:

?from=0x9A83706D363e2Fd14103f587EA4bb27B2b2f3Ae6&from=0x418F8020b48731FfD2a99Afe0Aa5E7d66Ca263d8
Authorizations:
path Parameters
contractId
required
string

ID of the Contract.

event
required
string

Name of the event.

Responses

200

Success

Response Schema: application/json
data
Array of object
get /contracts/{contractId}/events/{event}
Blockwell Spout
https://spout.apiminer.com/contracts/{contractId}/events/{event}
Debug environment
https://debug.apiminer.com/contracts/{contractId}/events/{event}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "data":
    [
    ]
}

transactions

Get a transaction

Get the status of a pending transaction.

Authorizations:
path Parameters
id
required
string

Transaction ID.

Responses

200

Success

Response Schema: application/json
data
object (Transaction)
404

Transaction not found

get /transactions/{id}
Blockwell Spout
https://spout.apiminer.com/transactions/{id}
Debug environment
https://debug.apiminer.com/transactions/{id}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "data":
    {
    }
}

Transaction history

Get the current user's transaction history.

Authorizations:
query Parameters
contractId
string

Filter by contract ID.

from
string

Filter by 'from'. Can be either the account ID, or Ethereum address.

method
string

Filter by contract method used.

status
string

Filter by transaction status.

Responses

200

Success

Response Schema: application/json
data
Array of object
get /transactions
Blockwell Spout
https://spout.apiminer.com/transactions
Debug environment
https://debug.apiminer.com/transactions

Response samples

application/json
Copy
Expand all Collapse all
{
  • "data":
    [
    ]
}

Submit a new transaction

Submit a new Ether transaction to the specified network.

Success means the transaction was accepted for processing, but there are no guarantees as to when the processing will be done. Processing happens on first-come-first-served basis.

A successful response contains a unique ID for the transaction, which can then be used to query its status.

Authorizations:
Request Body schema: application/json
network
required
string or number

The network to use, see Ethereum networks.

to
required
string

Ethereum address to send Ether to.

value
required
string^[0-9]$

Amount of Ether to transfer, in wei.

from
string

Address to send from, as either an Ethereum address, or an account ID.

If not specified, the current user's default account will be used.

callbacks
Array of string

Callback URL(s) to be notified when the Token transfer completes. See Callbacks for more details.

callbackData
object

An object holding data that the callbacks will contain.

Responses

202

Transaction accepted

Response Schema: application/json
data
object (Transaction)
post /transactions
Blockwell Spout
https://spout.apiminer.com/transactions
Debug environment
https://debug.apiminer.com/transactions

Request samples

application/json
Copy
Expand all Collapse all
{
  • "network": "spout",
  • "to": "0x98c4A022C1492Cc8a59F75295FBCf4a9F1Bc7cE8",
  • "value": "1000000000000000000",
  • "from": "bf15bdb2-0574-5982-a199-08fab9ac59f1",
  • "callbackData": "{ "userId": "12345" "data": "foo" } "
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "data":
    {
    }
}

Get a public key

Get a public key used for web callback request signing.

The ID can be given as default, in which case the current default key is used.

Responses always contain the Key-Id header for identifying public keys. See Callbacks for more details.

Authorizations:
path Parameters
id
required
string

Public key ID.

Responses

200

Success

Response Headers
Key-Id
string

Public key ID.

Response Schema: text/plain
string <binary>
404

Transaction not found

get /transactions/keys/{id}
Blockwell Spout
https://spout.apiminer.com/transactions/keys/{id}
Debug environment
https://debug.apiminer.com/transactions/keys/{id}

Response samples

text/plain
Copy
-----BEGIN PUBLIC KEY-----
MIICIjAN...
-----END PUBLIC KEY-----

accounts

List accounts

List Accounts belonging to the current user.

Authorizations:

Responses

200

Success

Response Schema: application/json
data
Array of object
get /accounts
Blockwell Spout
https://spout.apiminer.com/accounts
Debug environment
https://debug.apiminer.com/accounts

Response samples

application/json
Copy
Expand all Collapse all
{
  • "data":
    [
    ]
}

Create account

Generates a new Ethereum account.

If an owner ID is specified, the account will be created for that user. Otherwise, the account will belong to the authenticated user.

Authorizations:
Request Body schema: application/json
owner
string

User ID for the owner of the new account.

If not specified, the current user will be used instead.

default
boolean

If this is set to true, the account will be made the user's default account.

Responses

201

Account created

Response Schema: application/json
data
object (Account)
403

Unauthorized

post /accounts
Blockwell Spout
https://spout.apiminer.com/accounts
Debug environment
https://debug.apiminer.com/accounts

Request samples

application/json
Copy
Expand all Collapse all
{
  • "owner": "4b17b28b-2409-54b6-bf43-f36fe8bced4e",
  • "default": false
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "data":
    {
    }
}

Account by ID

Get a specific Account by its ID.

Authorizations:
path Parameters
accountId
required
string

ID of the Account

Responses

200

Success

Response Schema: application/json
data
object (Account)
404

Not found

get /accounts/{accountId}
Blockwell Spout
https://spout.apiminer.com/accounts/{accountId}
Debug environment
https://debug.apiminer.com/accounts/{accountId}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "data":
    {
    }
}

users

Find users

Search for users based on parameters.

If an external ID is specified, the name parameter is ignored.

If no parameters are supplied, the endpoint returns all users the current user has created.

Authorizations:
query Parameters
externalId
string

User external ID.

name
string

User name.

Responses

200

Success

Response Schema: application/json
data
Array of object
get /users
Blockwell Spout
https://spout.apiminer.com/users
Debug environment
https://debug.apiminer.com/users

Response samples

application/json
Copy
Expand all Collapse all
{
  • "data":
    [
    ]
}

Create user

Creates a new user.

If an owner ID is specified, the account will be created for that user. Otherwise, the account will belong to the authenticated user.

Authorizations:
Request Body schema: application/json
name
string

A name for the user.

This does not have to be unique, it's simply for informational purposes.

externalId
string

An arbitrary identifier for external use.

Typically you would set this to an ID used in your application for the user.

externalData
object

Arbitrary data associated with this user.

There are certain restrictions on this data to avoid security issues. The restrictions are the same as for callback data.

auth
boolean

If set to true, a new authentication token for the user will be returned as well.

account
boolean

If set to true, a default Ethereum account will also be created for the user.

ownerless
boolean

If set to true, the user will be created without an owner.

In practice, not having an owner means the previous user cannot access the new user, or create auth tokens for the user.

Responses

201

User created

Response Schema: application/json
data
object (User)
auth
string

User auth token, if requested.

account
object (Account)
post /users
Blockwell Spout
https://spout.apiminer.com/users
Debug environment
https://debug.apiminer.com/users

Request samples

application/json
Copy
Expand all Collapse all
{
  • "name": "user1",
  • "externalId": "123abc",
  • "externalData": { },
  • "auth": true,
  • "account": true,
  • "ownerless": true
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "data":
    {
    }
}

User by ID

Get a user by its ID.

Authorizations:
path Parameters
userId
required
string

User ID.

Responses

200

Success

Response Schema: application/json
data
object (User)
get /users/{userId}
Blockwell Spout
https://spout.apiminer.com/users/{userId}
Debug environment
https://debug.apiminer.com/users/{userId}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "data":
    {
    }
}

Update user

Update data associated with the user.

Note that this endpoint does allow you to change the user's externalId, even though that should rarely be needed.

If a field is not present in the request body, its value is left unchanged. To clear the value of an existing field, use null.

Authorizations:
path Parameters
userId
required
string

User ID.

Request Body schema: application/json
name
string

A name for the user.

This does not have to be unique, it's simply for informational purposes.

externalId
string

An arbitrary identifier for external use.

Typically you would set this to an ID used in your application for the user.

externalData
object

Arbitrary data associated with this user.

There are certain restrictions on this data to avoid security issues. The restrictions are the same as for callback data.

Responses

204

Success

put /users/{userId}
Blockwell Spout
https://spout.apiminer.com/users/{userId}
Debug environment
https://debug.apiminer.com/users/{userId}

Request samples

application/json
Copy
Expand all Collapse all
{
  • "name": "user1",
  • "externalId": "123abc",
  • "externalData": { }
}

New access token

Generates a new access token for the current user.

Authorizations:
Request Body schema: application/json
revoke
boolean

If specified as true, all old access tokens will be revoked.

Responses

201

Access granted

Response Schema: application/json
data
string

New access token

post /users/me/authenticate
Blockwell Spout
https://spout.apiminer.com/users/me/authenticate
Debug environment
https://debug.apiminer.com/users/me/authenticate

Request samples

application/json
Copy
Expand all Collapse all
{
  • "revoke": false
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "data": "abcd1234"
}

User access token

Generates a new access token for the given user.

Note that you can only authenticate users you have ownership over.

Authorizations:
Request Body schema: application/json
revoke
boolean

If specified as true, all old access tokens will be revoked.

Responses

201

Access granted

Response Schema: application/json
data
string

New access token

post /users/{userId}/authenticate
Blockwell Spout
https://spout.apiminer.com/users/{userId}/authenticate
Debug environment
https://debug.apiminer.com/users/{userId}/authenticate

Request samples

application/json
Copy
Expand all Collapse all
{
  • "revoke": false
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "data": "abcd1234"
}