Skip to content

API Reference

Jump to bottom
Zane Witherspoon edited this page Jan 8, 2019 · 86 revisions

Check out our Postman Collection

We just released our new Postman API Documentation and strongly recommend using it for documentation.

The Disgo API is a modern HTTP interface that follows the REST architecture with a JSON format. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. We support cross-origin resource sharing, allowing you to interact securely with our API from a client-side web application. JSON is returned by all API responses, including errors, although our API libraries convert responses to appropriate language-specific objects.

HTTP Responses

Disgo uses conventional HTTP response codes to indicate the success or failure of an API request. Response codes in the 200-299 range indicate success, codes in the 400-499 range indicate an error that failed given the information provided, and codes in the 500-599 range indicate an error with the Dispatch node. When a request is valid but does not complete successfully, we return a 402 error code.

Status and Error Codes

Status Code. Summary
200 - OK Everything worked as expected.
400 - Bad Request The request was unacceptable, often due to missing a required parameter.
401 - Unauthorized No valid API key provided.
402 - Request Failed The parameters were valid but the request failed.
404 - Not Found The requested resource doesn't exist.
405 - Method Not Allowed The requested resource doesn't exist.
409 - Conflict The request conflicts with another request
418 - I'm a teapot The node is not a delegate. Please use a delegate when making this request.
429 - Too Many Requests Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500, 502, 503, 504 - Server Errors Something went wrong on Disgo's end. (These are rare.)

Example API Requests

Request Description
ListDelegates List delegates
ListTransactions List all transactions
ListTransactionsToAddress List transactions from an address
ListTransactionsFromAddress List transactions to an address
GetTransactionsFromHash Get transaction by hash
NewTransaction Send a hashed transaction
GetAccount Get account details for an address

List Delegates

This API call will return a list of all delegates on the Dispatch network. Please use the base URL http://seed.dispatchlabs.io:1975/ for this API call.

Example request

curl 'http://seed.dispatchlabs.io:1975/v1/delegates'

Example response

{
    "status": "Ok",
    "humanReadableStatus": "Ok",
    "data": [
        {
            "address": "fbaadf32f8fc1d33eed36e4125d4926b65cf6085",
            "grpcEndpoint": {
                "host": "35.203.147.207",
                "port": 1973
            },
            "httpEndpoint": {
                "host": "35.203.147.207",
                "port": 1975
            },
            "type": "Delegate"
        },
    ..... ],
    "created": "2018-09-05T22:30:28.845499275Z"
}

Transactions

This is an object representing your Disgo transfer of tokens, deployment of smart contract, and smart contract execution. These are currently 4 transactions types, 0, 1, 2, and 3. Type 0 is a token transfer. Type 1 is deploying a smart contract. Type 2 is executing a smart contract. Type 3 is reserved for transactions that push an update command to the delegates.

Note that Type 3 is currenty required to be signed by the genesis account. In the future, this TX will be reuqired to be signed by all of the delegates.

The transaction object

Attribute Type Description Used by types Example
hash string SHA3 hash of the object All "603378477301a29..."
type number The type of the transaction All 0
from string Address of from where the tokens came from Optional "7777f2b40aa..."
to string Address of where to the the transaction will go 0,1,2 "c296220327589..."
value string Number of tokens to transfer 0,1,2 999
code string Smart contract deployment code 1 "608060405234..."
abi string Smart contract guide 1 "5b7b0a202..."
method string Name of Method being called 2 "getVar5"
params stringified JSON array Parameters for Method (For Type 3: Version number of the update) 2,3 ["5555"] , or []
time string Time of the transfer formatted in ISO 1806 All 1528923572369
Signature string Hash owner's signature All "7b60acd9e8f972..."
hertz string Amount of bandwidth to use Optional 0

Get all transactions

Call to retrieve all transactions on a Dispatch delegate.

Example request

curl 'http://35.185.224.243:1975/v1/transactions/'

Example response

{
    "status": "Ok",
    "humanReadableStatus": "Ok",
    "data": [
        {
            "hash": "014ac414be6cff6db9d20e131418dae502a4e7d6efaa015b73cb8c2c05031f3b",
            "type": 0,
            "from": "6b728eb24434d31a3e7153f64da0a039bff307e4",
            "to": "9fdd1b96f5eda025ba2ff9f8201cb496af839d0f",
            "value": 5,
            "abi": "{}",
            "time": 1535527996533,
            "signature": "2190831ad6e28c9e664c03905ba9e82c1b208de14bfea9367ed3addc95ac03985a278d43ffd6bd33e28fd9d910116d6a7ea4e65efd781d787a53cfb94c9485e501",
            "hertz": 0,
            "receipt": {
                "transactionHash": "",
                "status": "",
                "created": "0001-01-01T00:00:00Z"
            }
        },.... {}
    ],
    "created": "2018-09-06T00:03:18.822716546Z"
}

Retrieving all transactions sent from an address.

Call to retrieve all transactions filtered using from parameter (or to).

Example request

curl 'http://35.185.224.243:1975/v1/transactions/from/{{address}}'

Example response

{
    "status": "Ok",
    "humanReadableStatus": "Ok",
    "data": [
        {
            "hash": "a39e21aa967120da95993a4a988e5009d72120bcbb3aad70da65ac0183512010",
            "type": 2,
            "from": "6b728eb24434d31a3e7153f64da0a039bff307e4",
            "to": "1a08733f2a9ebf6b33ea792f10a153364c406ff1",
            "abi": "5b7b22636f6e7374616e74223a747275652c22696e70757473223a5b7b226e616d65223a2279222c2274797065223a2275696e74323536227d5d2c226e616d65223a22706c75734f6e65222c226f757470757473223a5b7b226e616d65223a2278222c2274797065223a2275696e74323536227d5d2c2270617961626c65223a66616c73652c2273746174654d75746162696c697479223a2270757265222c2274797065223a2266756e6374696f6e227d5d",
            "method": "plusOne",
            "params": [
                1
            ],
            "time": 1535528027657,
            "signature": "25ac7d5afc36ef329d70a03feff833897f1ded26a3d10a888934dfcc76f5975e30b44d5f19722812831ea6d6c90fb0d0336a502a8b8c7d0a6adfac0e5e07b18100",
            "hertz": 2,
            "receipt": {
                "transactionHash": "a39e21aa967120da95993a4a988e5009d72120bcbb3aad70da65ac0183512010",
                "status": "Ok",
                "contractAddress": "1a08733f2a9ebf6b33ea792f10a153364c406ff1",
                "contractResult": [
                    2
                ],
                "created": "2018-08-29T07:33:52.918897036Z"
            },
            "gossip": [
                {
                    "hash": "5969084427bf52920f57ca7302e1cf92282ce5e1d3c52edd7181fb5c42669f99",
                    "address": "dea18bfabd1ebb0e2249652031a0f7c12c5f09ed",
                    "transactionHash": "a39e21aa967120da95993a4a988e5009d72120bcbb3aad70da65ac0183512010",
                    "time": 1535528027905,
                    "signature": "3e89fd88b53b0303e05f8b922dad9a5e9b7e759c60ef513079ab50d0883b620657f4e14d00a3df2854d68dc473ee8d1f0c4b8047eec2725f95c480c53468009501"
                },...
            ]
        },...
     ],
    "created": "2018-09-06T00:11:12.44461441Z"
}

Retrieving all transactions sent from an address.

Call to retrieve all transactions filtered using from parameter (or to).

Example request

curl 'http://35.185.224.243:1975/v1/transactions/to/{{address}}'

Example response

{
    "status": "Ok",
    "humanReadableStatus": "Ok",
    "data": [
          {
            "hash": "ebd595cfb1e8631ca5082f536def1936137294ba8156d2f277f183066cb23f00",
            "type": 0,
            "from": "3ed25f42484d517cdfc72cafb7ebc9e8baa52c2c",
            "to": "6b728eb24434d31a3e7153f64da0a039bff307e4",
            "value": 10000,
            "abi": "{}",
            "time": 1535498223380,
            "signature": "ac28060ac2dc0dfeb02a98a5232fb1b3ce8f35b5e9451a45d3f12b71761b50105ac4fba14b1c0dd21e5e1000edfc721767bf2233571db0185706fd8f83a4be3e00",
            "hertz": 0,
            "receipt": {
                "transactionHash": "ebd595cfb1e8631ca5082f536def1936137294ba8156d2f277f183066cb23f00",
                "status": "Ok",
                "created": "2018-08-28T23:17:08.548951261Z"
            },
            "gossip": [
                {
                    "hash": "f3656df55eecc1c7b2ae07a5e4c599d84c855813c6f40942f058705006f02827",
                    "address": "61f93e079669e5f0845bad36c77fdf29446c7f6d",
                    "transactionHash": "ebd595cfb1e8631ca5082f536def1936137294ba8156d2f277f183066cb23f00",
                    "time": 1535498223536,
                    "signature": "c6289954cbb1b003b48eac6832a0ad265c721c0918b2bf3690f8cd4876377c0911fa80b60d605db9af7f0778a189558f0bf6f6fac0f7d665fc72faf8a2d783a200"
                },... {}
            ],
            "fromName": "Dispatch Labs"
        }
    ],
    "created": "2018-09-06T00:14:51.938422497Z"
}

Retrieving all transactions sent from an address.

Call to retrieve a single transactions using the transaction hash.

Example request

curl 'http://35.185.224.243:1975/v1/transactions/{{hash}}'

Example response

{
    "status": "Ok",
    "humanReadableStatus": "Ok",
    "data": [
          {
            "hash": "ebd595cfb1e8631ca5082f536def1936137294ba8156d2f277f183066cb23f00",
            "type": 0,
            "from": "3ed25f42484d517cdfc72cafb7ebc9e8baa52c2c",
            "to": "6b728eb24434d31a3e7153f64da0a039bff307e4",
            "value": 10000,
            "abi": "{}",
            "time": 1535498223380,
            "signature": "ac28060ac2dc0dfeb02a98a5232fb1b3ce8f35b5e9451a45d3f12b71761b50105ac4fba14b1c0dd21e5e1000edfc721767bf2233571db0185706fd8f83a4be3e00",
            "hertz": 0,
            "receipt": {
                "transactionHash": "ebd595cfb1e8631ca5082f536def1936137294ba8156d2f277f183066cb23f00",
                "status": "Ok",
                "created": "2018-08-28T23:17:08.548951261Z"
            },
            "gossip": [
                {
                    "hash": "f3656df55eecc1c7b2ae07a5e4c599d84c855813c6f40942f058705006f02827",
                    "address": "61f93e079669e5f0845bad36c77fdf29446c7f6d",
                    "transactionHash": "ebd595cfb1e8631ca5082f536def1936137294ba8156d2f277f183066cb23f00",
                    "time": 1535498223536,
                    "signature": "c6289954cbb1b003b48eac6832a0ad265c721c0918b2bf3690f8cd4876377c0911fa80b60d605db9af7f0778a189558f0bf6f6fac0f7d665fc72faf8a2d783a200"
                },... {}
            ],
            "fromName": "Dispatch Labs"
        }
    ],
    "created": "2018-09-06T00:14:51.938422497Z"
}

Create a new transaction

This endpoint will allow you to send a transaction using the hash of the transaction. Note that any parameter that is optional you should include and send as an empty string or 0; with the exception of the parameter named "params" which should be "[]" if empty.

Example request

curl -X POST -d '{
        "hash": "{{hash}}",
        "type": 0,
        "from": "{{fromAddress}}",
        "to": "{{toAddress}}",
        "value": 5,
        "abi": "{}",
        "time": {{hash}},
        "signature": "{{signature}}",
        "hertz": 0,
        "fromName":"",
        "toName":""
}' 'http://35.185.224.243:1975/v1/transactions'

Example response

{
	{"id":"480fd9bc-4962-4e98-825e-387e5ea83c14","type":"NewTransaction","status":"Pending","created":"2018-06-26T21:22:46.229254106Z"}
}

Get Account details

This endpoint retrieves the detailed account information and balance of an address.

Example request

curl 'http://35.185.224.243:1975/v1/accounts/{{address}}'

Example response

{
    "status": "Ok",
    "humanReadableStatus": "Ok",
    "data": {
        "address": "2674ad19f8472a953b4b9eebf53e9fce4e9bf718",
        "name": "",
        "balance": 0,
        "transactionHash": "c0f53ec38a6dc04a632d45aa570cb77903ef1d302f547e4583bb7313400fda1a",
        "updated": "2018-08-28T21:20:41.192534758Z",
        "created": "2018-08-28T21:20:29.358826557Z",
        "nonce": 0
    },
    "created": "2018-09-05T23:57:13.958756313Z"
}
Clone this wiki locally