A revolutionary asset solution platform

Aspire API

Aspire is a revolutionary asset solution platform designed to allow users to easily create their own digital assets under a secure environment that is extremely affordable, secure and fast.

Explore: Aspire API

Explore

Aspire-Server API

Overview

aspire-lib provides a JSON RPC 2.0-based API based off of that of gAsp Core. It is the primary means by which other applications should interact with the Aspire network.

The API server is started either through the CLI interface or with the aspire-lib Python library. It listens on port 4000 by default (14000 for testnet) and requires HTTP Basic Authentication to connect.

The API includes numerous information retrieval methods, most of which begin with get_, as well as several create_ methods which create new Aspire transactions. While the get_ type methods simply return the requested information, the create_ methods return unsigned raw transactions which must then be signed and broadcast on the gAsp network. This means that while aspire-server requires gAsp Core and uses it for retieval and parsing of blockchain data, it and this API do not require gAsp Core’s wallet functionality for private key storage and transaction signing. Transaction signing and broadcast can thus be accomplished using whatever means the developer sees fit.

In addition to the JSON RPC API, aspireparty-lib provides a complementary RESTful API also based off of that of gAsp Core’s design. This REST API is still under development and will include more functionality in the future, and listens on the same port as JSON RPC one.

Aspire-Server API​

Getting Started

By default, the server will listen on port 4000 (if on mainnet) or port 14000 (on testnet) for API requests.

Note that the main API is built on JSON-RPC 2.0, not 1.1. JSON-RPC itself is pretty lightweight, and API requests are made via a HTTP POST request to /api/ (note the trailing slash), with JSON-encoded data passed as the POST body.

The requests to the secondary REST API are made via HTTP GET to /rest/, with request action and parameters encoded in the URL.

Aspire-Server API​

JSON-RPC

All requests must have POST data that is JSON encoded. Here’s an example of the POST data for a valid API request:

{
  "method": "get_sends",
  "params": {"order_by": "tx_hash",
             "order_dir": "asc",
             "start_block": 2000,
             "end_block": 2005},
  "jsonrpc": "2.0",
  "id": 0
}

The jsonrpc and id properties are requirements under the JSON-RPC 2.0 spec.

You should note that the data in params is a JSON object (e.g. mapping), not an array. In other words, the API only supports named arguments, not positional arguments (e.g. use {“argument1”: “value1”, “argument2”: “value2”} instead of [“value1”, “value2”]). This is the case for safety and bug-minimization reasons.

For more information on JSON RPC, please see the JSON RPC 2.0 specification.

Example Implementations for JSON RPC API

The following examples have authentication enabled and the user set to its default value of 'rpc'. The password is not set (default: 'rpc'). Ensure these values correspond to values in your aspire-server’s configuration file 'server.conf'.

Python

import json
import requests
from requests.auth import HTTPBasicAuth

url = "http://localhost:4000/api/"
headers = {'content-type': 'application/json'}
auth = HTTPBasicAuth('rpc', PASSWORD)

payload = {
  "method": "get_running_info",
  "params": {},
  "jsonrpc": "2.0",
  "id": 0
}
response = requests.post(url, data=json.dumps(payload), headers=headers, auth=auth)
print("Response: ", response.text)

PHP

With PHP, you use the JsonRPC library.

<?php
require 'JsonRPC/src/JsonRPC/Client.php';
use JsonRPC\Client;
$client = new Client('http://localhost:4000/api/');
$client->authentication('rpc', PASSWORD);

$result = $client->execute('get_balances', array('filters' => array('field' => 'address', 'op' => '==', 'value' => '1NFeBp9s5aQ1iZ26uWyiK2AYUXHxs7bFmB')));
print("get_balances result:\n");
var_dump($result);

$result2 = $client->execute('get_running_info');
print("get_running_info result:\n");
var_dump($result2);
?>

Curl

Remember to surround non-numeric parameter values with the double quotes, as per JSON-RPC 2.0 examples. For example, "order_by": "tx_hash" is correct and will work, "order_by": 'tx_hash' won’t.

Linux

curl -X POST http://127.0.0.1:4000/api/ --user rpc:$PASSWORD -H 'Content-Type: application/json; charset=UTF-8' -H 'Accept: application/json, text/javascript' --data-binary '{ "jsonrpc": "2.0", "id": 0, "method": "get_running_info" }'

Windows

On Windows, depending on implementation the above curl command may need to be formatted differently due to problems that Windows has with escapes. For example this particular format was found to work with curl 7.50.1 (x86_64-w64-mingw32) on Windows 10 (x64).

curl -X POST http://127.0.0.1:4000/api/ --user rpc:$PASSWORD -H "Content-Type: application/json; charset=UTF-8" -H "Accept: application/json, text/javascript" --data-binary "{ \"jsonrpc\": \"2.0\", \"id\": 0, \"method\": \"get_running_info\" }"

C# (RestSharp)

C# (RestSharp): Authorization string in the example below is based on the default username/password.

var client = new RestClient("http://127.0.0.1:4000/api/");
var request = new RestRequest(Method.POST);
request.AddHeader("cache-control", "no-cache");
request.AddHeader("authorization", "Basic cnBjOjEyMzQ=");
request.AddHeader("content-type", "application/json");
request.AddParameter("application/json", "{\r\n  \"method\": \"get_running_info\",\r\n  \"params\": {},\r\n  \"jsonrpc\": \"2.0\",\r\n  \"id\": 1\r\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Go

Go: Authorization string in the example below is based on the default username/password.

package main

import (
    "fmt"
    "strings"
    "net/http"
    "io/ioutil"
)

func main() {

    url := "http://127.0.0.1:4000/api/"

    payload := strings.NewReader("{\r\n  \"method\": \"get_running_info\",\r\n  \"params\": {},\r\n  \"jsonrpc\": \"2.0\",\r\n  \"id\": 1\r\n}")

    req, _ := http.NewRequest("POST", url, payload)

    req.Header.Add("content-type", "application/json")
    req.Header.Add("authorization", "Basic cnBjOjEyMzQ=")
    req.Header.Add("cache-control", "no-cache")

    res, _ := http.DefaultClient.Do(req)

    defer res.Body.Close()
    body, _ := ioutil.ReadAll(res.Body)

    fmt.Println(res)
    fmt.Println(string(body))

}

C# (RestSharp)

Ruby (Net:HTTP): Authorization string in the example below is based on the default username/password.

require 'uri'
require 'net/http'

url = URI("http://127.0.0.1:4000/api/")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["content-type"] = 'application/json'
request["authorization"] = 'Basic cnBjOjEyMzQ='
request["cache-control"] = 'no-cache'
request.body = "{\r\n  \"method\": \"get_running_info\",\r\n  \"params\": {},\r\n  \"jsonrpc\": \"2.0\",\r\n  \"id\": 1\r\n}"

response = http.request(request)
puts response.read_body
Aspire-Server API​

REST

For REST API all requests are made via GET where query-specific arguments are encoded as URL parameters. Moreover, the same requests can be passed via HTTP POST in order to encrypt the transaction parameters. There are only two methods supported: get and compose. The URL formats are as follows, respectively: /rest/<table_name>/get?<filters>&op=<operator> /rest/<message_type>/compose?<transaction arguments>

Example Implementations for REST API

The following examples don’t use authentication as with default settings.

Python

import requests

url = "http://localhost:4000/rest/"
headers = {'content-type': 'application/json'}

query = 'sends/get?source=mn6q3dS2EnDUx3bmyWc6D4szJNVGtaR7zc&destination=mtQheFaSfWELRB2MyMBaiWjdDm6ux9Ezns&op=AND'

response = requests.get(url + query, headers=headers)
print("Response: ", response.text)

Linux

curl "http://rpc:rpc@127.0.0.1:4000/rest/sends/get?source=1B6ahDHnKtZ5GXqytHSxfcXgNoxm1q1RsP&destination=14fAoS9FPD9jx36hjCNoAqFVLNHD1NQVN5&op=AND" -H "Content-Type: application/json; charset=UTF-8" -H "Accept: application/json"

Windows

This example was created with curl 7.50.1 (x86_64-w64-mingw32) on Windows 10. For POST encryption add '-X POST'.

curl "http://rpc:rpc@127.0.0.1:4000/rest/sends/get?source=1B6ahDHnKtZ5GXqytHSxfcXgNoxm1q1RsP&destination=14fAoS9FPD9jx36hjCNoAqFVLNHD1NQVN5&op=AND" -H "Content-Type: application/json; charset=UTF-8" -H "Accept: application/json"
Aspire-Server API​

Example Parameters

Fetch all balances for all assets for both of two addresses, using keyword-based arguments (just example address).

payload = {
           "method": "get_balances",
           "params": {
                      "filters": [{"field": "address", "op": "==", "value": "GZqa5iTfNkxdPRDPcRYvEbsNcet7WSngS4"},
                                  {"field": "address", "op": "==", "value": "GKLgKq5wogT54MKvL1GaTEkFDMn9xxFK8t"}],
                      "filterop": "or"
                     },
           "jsonrpc": "2.0",
           "id": 0
          }

Send 1 ASP (specified in bits) from one address to another.

payload = {
           "method": "create_send",
           "params": {
                      "source": "GZqa5iTfNkxdPRDPcRYvEbsNcet7WSngS4",
                      "destination": "GKLgKq5wogT54MKvL1GaTEkFDMn9xxFK8t",
                      "asset": "ASP",
                      "quantity": 100000000
                     },
           "jsonrpc": "2.0",
           "id": 0
          }

Issuance (indivisible)

payload = {
           "method": "create_issuance",
           "params": {
                      "source": "GZqa5iTfNkxdPRDPcRYvEbsNcet7WSngS4",
                      "asset": "MYASSET",
                      "quantity": 1000,
                      "description": "my asset is cool",
                      "divisible": False
                     },
           "jsonrpc": "2.0",
           "id": 0
          }

Transfer asset ownership

payload = {
           "method": "create_issuance",
           "params": {
                      "source": "GZqa5iTfNkxdPRDPcRYvEbsNcet7WSngS4",
                      "transfer_destination": "GKLgKq5wogT54MKvL1GaTEkFDMn9xxFK8t",
                      "asset": "MYASSET",
                      "quantity": 0
                     },
           "jsonrpc": "2.0",
           "id": 0
          }

Lock asset

payload = {
           "method": "create_issuance",
           "params": {
                      "source": "GZqa5iTfNkxdPRDPcRYvEbsNcet7WSngS4",
                      "asset": "MYASSET",
                      "quantity": 0,
                      "description": "LOCK"
                     },
           "jsonrpc": "2.0",
           "id": 0
          }
Aspire-Server API​

Signing Transactions Before Broadcasting

Note: Before v9.49.4, the aspire server API provided an interface to gAsp Core’s signing functionality through the do_*, sign_tx and broadcast_tx methods, which have all since been removed.

All create_ API calls return an unsigned raw transaction serialization as a hex-encoded string (i.e. the same format that bitcoind returns with its raw transaction API calls). This raw transaction’s inputs may be validated and then must be signed and broadcast on the gAsp network.

The process of signing and broadcasting a transaction, from start to finish, depends somewhat on the wallet software used. Below are examples of how one might use a wallet to sign and broadcast an unsigned Aspire transaction created with this API.

gAsp Core with Python

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
 
#! /usr/bin/env python3

from aspirelib.lib import util
from aspirelib.lib import config
from aspirelib.lib.backend import addrindex

config.TESTNET =
config.RPC =
config.BACKEND_URL =
config.BACKEND_SSL_NO_VERIFY =

def aspire_api(method, params):
    return util.api(method, params)

def gasp_api(method, params):
    return addrindex.rpc(method, params)

def do_send(source, destination, asset, quantity, fee, encoding):
    validateaddress = gasp_api('validateaddress', [source])
    assert validateaddress['ismine']
    pubkey = validateaddress['pubkey']
    unsigned_tx = aspire_api('create_send', {'source': source, 'destination': destination, 'asset': asset, 'quantity': quantity, 'pubkey': pubkey, 'allow_unconfirmed_inputs': True})
    signed_tx = gasp_api('signrawtransaction', [unsigned_tx])['hex']
    tx_hash = gasp_api('sendrawtransaction', [signed_tx])
    return tx_hash

gAsp Core with Javascript (Utilizing the Aspirewallet Bitcore wrapper code for brevity.)

<html>
    <script src="https://raw.githubusercontent.com/bitpay/bitcore-lib/f031e1ddfbf0064ef503a28aada86c4fbf9a414c/bitcore-lib.min.js"></script>
    <script src="https://raw.githubusercontent.com/AspireOrg/aspirewallet/init-aspire/src/js/util.bitcore.js"></script>
    <script src="https:///raw.githubusercontent.com/AspireOrg/aspirewallet/blob/init-aspire/src/js/external/mnemonic.js"></script>
    <script>
    aspire_api = function(method, params) {
        // call Aspire API method via your prefered method
    }

    gasp_api = function(method, params) {
        // call gAsp Core API method via your prefered method
    }

    // generate a passphrase
    var m = new Mnemonic(128); //128 bits of entropy (12 word passphrase)
    var words = m.toWords();
    var passphrase = words.join(' ')

    // generate private key, public key and address from the passphrase
    wallet = new CWHierarchicalKey(passphrase);
    var cwk = wallet.getAddressKey(i); // i the number of the address
    var source = key.getAddress();
    var pubkey = cwk.getPub()

    // generate unsigned transaction
    unsigned_hex = aspire_api('create_send', {'source': source, 'destination': destination, 'asset': asset, 'quantity': quantity, 'pubkey': pubkey})

    CWBitcore.signRawTransaction2(self.unsignedTx(), cwk, function(signedHex) {
        gasp_api('sendrawtransaction', signedHex)
    })
    </script>
</html>
Aspire-Server API​

Authentication

The API support HTTP basic authentication to use, which is enabled if and only if a password is set. The default user is 'rpc'.

Aspire-Server API​

Terms & Conventions

Note: Before v9.49.4, the aspire server API provided an interface to gAsp Core’s signing functionality through the do_*, sign_tx and broadcast_tx methods, which have all since been removed.

All create_ API calls return an unsigned raw transaction serialization as a hex-encoded string (i.e. the same format that bitcoind returns with its raw transaction API calls). This raw transaction’s inputs may be validated and then must be signed and broadcast on the gAsp network.

The process of signing and broadcasting a transaction, from start to finish, depends somewhat on the wallet software used. Below are examples of how one might use a wallet to sign and broadcast an unsigned Aspire transaction created with this API.

Assets

Everywhere in the API an asset is referenced by its name, not its ID. See the Aspire protocol specification for what constitutes a valid asset name. 

Examples:

  • “GASP”
  • “ASP”

Subassets

See the Aspire protocol specification for what constitutes a valid subasset name. Examples:

  • “PIZZA.X”
  • “PIZZA.REALLY-long-VALID-Subasset-NAME”

Quantities and balances

Anywhere where a quantity is specified, it is specified in bits (if a divisible asset), or as whole numbers (if an indivisible asset). To convert bits to floating-point, simply cast to float and divide by 100,000,000.

Examples:

  • 4381030000 = 43.8103 (if divisible asset)
  • 4381030000 = 4381030000 (if indivisible asset)

NOTE: ASP and GASP themselves are divisible assets.

Floats

Floats are ratios or floating point values with six decimal places of precision, used in dividends.

Memos

See the  Aspire protocol specification for what constitutes a valid memo. Examples:

  • “for pizza”
  • “1ca6”
Aspire-Server API​

Miscellaneous: Filtering Read API results

The Aspire API aims to be as simple and flexible as possible. To this end, it includes a straightforward way to filter the results of most Read API to get the data you want, and only that.

For each Read API function that supports it, a filters parameter exists. To apply a filter to a specific data field, specify an object (e.g. dict in Python) as this parameter, with the following members:

  • field: The field to filter on. Must be a valid field in the type of object being returned
  • op: The comparison operation to perform. One of: "==", "!=", ">", "<", ">=", "<=", "IN", "LIKE", "NOT IN", "NOT LIKE"
  • value: The value that the field will be compared against. Must be the same data type as the field is (e.g. if the field is a string, the value must be a string too)

If you want to filter by multiple fields, then you can specify a list of filter objects. To this end, API functions that take filters also take a filterop parameter, which determines how the filters are combined when multiple filters are specified. It defaults to "and", meaning that filters are ANDed togeher (and that any match must satisfy all of them). You can also specify "or" as an alternative setting, which would mean that filters are ORed together, and that any match must satisfy only one of them.

To disable filtering, you can just not specify the filter argument (if using keyword-based arguments), or, if using positional arguments, just pass null or [] (empty list) for the parameter.

For examples of filtering in-use, please see the examples.

NOTE: Note that with strings being compared, operators like >= do a lexigraphic string comparison (which compares, letter to letter, based on the ASCII ordering for individual characters. For more information on the specific comparison logic used, please see this page.

Aspire-Server API​

Technical Specification

Read API Function Reference

get_{table}

get_{table}(filters=[], filterop=’AND’, order_by=null, order_dir=null, start_block=null, end_block=null, status=null, limit=1000, offset=0, show_expired=true)

Where {table} must be one of the following values: assets, balances, broadcasts, credits, debits, dividends, proofofwork, issuances, mempool, or sends.

For example: get_balances, get_credits, get_debits are all valid API methods. A complete list of tables can be found in the api.py file in the aspire-lib repository.

Parameters

  • filters (list/dict): An optional filtering object, or list of filtering objects. See filtering for more information.
  • filterop (string): Specifies how multiple filter settings are combined. Defaults to AND, but OR can be specified as well. See filtering for more information.
  • order_by (string): If sorted results are desired, specify the name of an attribute of the appropriate table to order the results by (e.g. quantity for balance object, if you called get_balances). If left blank, the list of results will be returned unordered.
  • order_dir (string): The direction of the ordering. Either ASC for ascending order, or DESC for descending order. Mu. st be set if order_by is specified. Leave blank if order_by is not specified.
  • start_block (integer): If specified, only results from the specified block index on will be returned
  • end_block (integer): If specified, only results up to and including the specified block index on will be returned
  • status (string/list): return only results with the specified status or statuses (if a list of status strings is supplied). See the status list. Note that if null is supplied (the default), then status is not filtered. Also note that status filtering can be done via the filters parameter, but doing it through this parameter is more flexible, as it essentially allows for situations where OR filter logic is desired, as well as status-based filtering.
  • limit (integer): (maximum) number of elements to return. Can specify a value less than or equal to the instance’s max limit (default 1000). For more results, use a combination of limit and offsetparameters to paginate results. If the instance has a limit of 0 you can specify any limit for the row results, even 0 to get the full dataset.
  • offset (integer): return results starting from specified offset

Special Parameters

  • show_expired (boolean): used only for get_orders. When false, get_orders doesn’t return orders which expire next block.
  • memo_hex (string): used only for get_sends. When specified, filter the table for a hexadecimal value instead of searching by a text string.

Special Results

  • memo (string): used only for get_sends. The utf-8 encoded string of the memo (like for pizza). This value will be an empty string for hexadecimal-encoded memo IDs that are not valud UTF-8 strings.
  • memo_hex (string): used only for get_sends. Returns the memo field expressed as a hexadecimal value (like 666f722070697a7a61).

Return

A list of objects with attributes corresponding to the queried table fields.

Notes:Please note that the get_balances API call will not return balances for GASP itself. It only returns balances for ASP and other Aspire assets. To get GASP-based balances, use an existing system such as gAsp Core, blockchain.info, etc.

get_asset_info

get_asset_info(asset)

Gets information on an issued asset. NOTE: This method is depreciated and may be removed in a future release.

Parameters

  • asset (string): The name of the asset or subasset for which to retrieve the information.

Return

null if the asset was not found. Otherwise, a list of one or more objects, each one with the following properties:

  • asset (string): The assets of the asset itself
  • asset_longname (string): The subasset longname, if any
  • owner (string): The address that currently owns the asset (i.e. has issuance rights to it)
  • divisible (boolean): Whether the asset is divisible or not
  • locked (boolean): Whether the asset is locked (future issuances prohibited)
  • total_issued (integer): The quantities of the asset issued, in total
  • description (string): The asset’s current description
  • issuer (string): The asset’s original owner (i.e. issuer)

get_supply

get_supply(asset)

Parameters

  • asset (string): The name of the asset or subasset for which to retrieve the information.

Return

null if the asset was not found. Otherwise, a list of one or more objects, each one with the following properties:

get_asset_names

get_asset_names()

Parameters

None

Return

null if the asset was not found. 

get_holder_count

get_holder_count()

Parameters

  • asset (string): The name of the asset or subasset for which to retrieve the information.

Return

An object the asset name as the property name, and the holder count as the value of that property name.

get_holders

get_holders()

Parameters

  • asset (string): The name of the asset or subasset for which to retrieve the information.

Return

A list of addresses that hold some quantity of the specified asset.

get_messages

get_messages(block_index)

Return message feed activity for the specified block index. The message feed essentially tracks all database actions and allows for lower-level state tracking for applications that hook into it.

Parameters

  • block_index (integer): The block index for which to retrieve activity.

Return

A list of one or more ‘message object’ if there was any activity in the block, otherwise [] (empty list).

get_messages_by_index

get_messages_by_index(message_indexes)

Return the message feed messages whose message_index values are contained in the specified list of message indexes.

Parameters

  • message_indexes (list): An array of one or more message_indexvalues for which the corresponding message feed entries are desired.

Return

A list containing a message <#message-object>_ for each message found in the specified message_indexes list. If none were found, [] (empty list) is returned.

get_block_info

get_block_info(block_index)

Gets basic information for a specific block.

Parameters

  • block_index (integer): The block index for which to retrieve information.

Return

If the block was found, an object with the following properties:

  • block_index (integer): The block index (i.e. block height). Should match what was specified for the block_index input parameter).
  • block_hash (string): The block hash identifier
  • block_time (integer): A UNIX timestamp of when the block was processed by the network

get_blocks

get_blocks(block_indexes, min_message_index=null)

Gets block and message data (for each block) in a bulk fashion. If fetching info and messages for multiple blocks, this is much quicker than using multiple get_block_info() and get_messages() calls.

Parameters

  • block_indexes (list): A list of 1 or more block indexes for which to retrieve the data.
  • min_message_index (string): Retrieve blocks from the message feed on or after this specific message index (useful since blocks may appear in the message feed more than once, if a reorg occurred). Note that if this parameter is not specified, the messages for the first block will be returned. If unsure, leave this blank.
  •  

Return

A list of objects, one object for each valid block index specified, in order from first block index to last. Each object has the following properties:

  • block_index (integer): The block index (i.e. block height). Should match what was specified for the block_index input parameter).
  • block_hash (string): The block hash identifier
  • block_time (integer): A UNIX timestamp of when the block was processed by the network
  • _messages (list): A list of one or more ‘message object’ if there was any activity in the block, otherwise [] (empty list).

get_running_info

get_running_info()

Gets some operational parameters for the server.

Parameters

None

Return

An object with the following properties:

  • db_caught_up (boolean): true if block processing is caught up with the gAsp blockchain, false otherwise.
  • gasp_block_count (integer): The block height on the gAsp network (may not necessarily be the same as last_block, if the server is catching up)
  • last_block (integer): The index (height) of the last block processed by the server
  • last_message_index (integer): The index (ID) of the last message in the message feed
  • running_testnet (boolean): true if the server is configured for testnet, false if configured on mainnet.
  • running_testcoin (boolean): true if the server is configured for testcoin use, false if not (default).
  • version_major (integer): The major version of aspire-server running
  • version_minor (integer): The minor version of aspire-server running
  • version_revision (integer): The revision version of aspire-server running
  • api_limit_rows (integer): The max amount of rows any call will return. If 0 there’s no limit to calls. Defaults to 1000.

get_element_counts

get_element_counts()

Gets the number of records for each entity type

Parameters

None

Return

An object with a property for each element type (e.g. transactions, blocks, etc.) with the value of each property being the record count of that respective entity in the database.

get_unspent_txouts

get_unspent_txouts(address, unconfirmed=false, unspent_tx_hash=null)

Get a listing of UTXOs for the specified address.

Parameters

  • address (string): The address for which to receive the UTXO listing
  • unconfirmed (boolean): Set to true to include unconfirmed UTXOs (e.g. those in the mempool)
  • unspent_tx_hash (boolean): Specify a specific transaction hash to only include UTXOs from that transaction

Return

A list of objects, with each entry in the dict having the following properties:

- **amount**: The amount of the UTXO
- **confirmations**: Number of confirmations since the UTXO was created
- **scriptPubKey**: The UTXO's scriptPubKey, encoded in hex format
- **txid**: The txid (hash) that the UTXO was included in
- **vout**: The vout number in the specified txid for the UTXO

getrawtransaction

getrawtransaction(tx_hash, verbose=false, skip_missing=false)

Gets raw data for a single transaction.

Parameters

  • tx_hash (string): The transaction hash identifier
  • verbose (boolean): Include some additional information in the result data
  • skip_missing (boolean): If set to false, and the transaction hash cannot be found, return null, otherwise if true, throw an exception.

Return

If found, a raw transaction objects having the same format as the bitcoind getrawtransaction API call. If not found, null.

getrawtransaction_batch

getrawtransaction_batch(txhash_list, verbose=false, skip_missing=false)

Gets raw data for a list of transactions.

Parameters

  • txhash_list (string): A list of transaction hash identifiers
  • verbose (boolean): Include some additional information in the result data for each transaction
  • skip_missing (boolean): If set to false, and one or more transaction hash cannot be found, the missing txhash data will not be included in the result set, otherwise if true, throw an exception.

Return

A list of raw transaction objects having the same format as the bitcoind getrawtransaction API call.

search_raw_transactions

search_raw_transactions(address, unconfirmed=true)

Gets raw transaction objects for the specified address.

Parameters

  • address (string): The address for which to receive the raw transactions
  • unconfirmed (boolean): Set to true to include unconfirmed transactions (e.g. those in the mempool)

Return

A list of raw transaction objects, with each object having the same format as the bitcoind getrawtransaction API call.

get_tx_info

get_tx_info(tx_hex, block_index=null)

Get transaction info, as parsed by aspire-server.

Parameters

  • tx_hex (string): The canonical hexadecimal serialization of the transaction (not its hash)
  • block_index (integer)

Return

A list with the following items (in order as listed below):

- `source`
- `destination`
- `gasp_amount`
- `fee`
- `data`: The embedded raw protocol data, in hexadecimal-serialized format

search_pubkey

search_pubkey(pubkeyhash, provided_pubkeys=null)

For the specified pubkeyhash (i.e. address), return the public key. Note that this requires that the specified address has made at least one outgoing transaction.

Parameters

  • pubkeyhash (string): The pubkeyhash/address
  • provided_pubkeys (list): A list of supplied pubkeys. If one of these pubkeys matches the pubkeyhash, used if one of the supplied pubkey hashes to the pubkeyhash. (Can be useful if the pubkeyhash has not sent out at least one transaction and you have a list of pubkeys that may match it.)

Return

A string with the specified pubkey. If the pubkey cannot be found, an exception will be generated and returned.

unpack

unpack(data_hex)

Parse the data_hex of a message into its parameters. Currently only works with send messages.

Parameters

  • data_hex (string): The canonical hexadecimal serialization of the transaction (not its hash), e.g. from the data_hex return value from get_tx_info

Return

  • message_type_id (int): the ID of the message type. Legacy sends are 0 and enhanced sends are 2.
  • unpacked (object): A map of message parameters. For legacy sends this object includes asset and quantity. For enhanced sends, this object includes address, asset, quantity and memo. For legacy sends, the source and destination are found using get_tx_info. For enhanced sends, the destination address is in the message parameters and the source may be found using get_tx_info

Action/Write API Function Reference

create_broadcast

create_broadcast(source, fee_fraction, text, timestamp, value)

Broadcast textual and numerical information to the network.

Parameters

  • source (string): The address that will be sending (must have the necessary quantity of the specified asset).
  • text (string): The textual part of the broadcast.
  • timestamp (integer): The timestamp of the broadcast, in Unix time.
  • value (float): Numerical value of the broadcast.
  • NOTE: Additional (advanced) parameters for this call are documented here.

Return

The unsigned transaction, as an hex-encoded string. Must be signed before being broadcast: see here for more information.

create_destroy

create_destroy(source, asset, quantity, tag)

Destroy a user defined asset.

Parameters

  • source (string): The address that will be sending (must have the necessary quantity of the specified asset).
  • asset (string): The asset or subasset to destroy.
  • quantity (integer): The quantities of the asset to destroy.
  • tag (string, optional): The tag (which works like a Memo ) associated with this transaction.
  • NOTE: Additional (advanced) parameters for this call are documented here.

Return

The unsigned transaction, as an hex-encoded string. Must be signed before being broadcast: see here for more information.

create_dividend

create_dividend(source, quantity_per_unit, asset, dividend_asset)

Issue a dividend on a specific user defined asset.

Parameters

  • source (string): The address that will be issuing the dividend (must have the ownership of the asset which the dividend is being issued on).
  • quantity_per_unit (integer): The amount of dividend_assetrewarded.
  • asset (string): The asset or subasset that the dividends are being rewarded on.
  • dividend_asset (string): The asset or subasset that the dividends are paid in.
  • NOTE: Additional (advanced) parameters for this call are documented here.

Return

The unsigned transaction, as an hex-encoded string. Must be signed before being broadcast: see here for more information.

create_issuance

create_issuance(source, asset, quantity, divisible, description, transfer_destination=null)

Issue a new asset, issue more of an existing asset, lock an asset, or transfer the ownership of an asset (note that you can only do one of these operations in a given create_issuance call).

Parameters

  • source (string): The address that will be issuing or transfering the asset.
  • asset (string): The assets to issue or transfer. This can also be a subasset longname for new subasset issuances.
  • quantity (integer): The quantity of the asset to issue (set to 0 if transferring an asset).
  • divisible (boolean, default=true): Whether this asset is divisible or not (if a transfer, this value must match the value specified when the asset was originally issued).
  • description (string, default=’‘): A textual description for the asset. 52 bytes max.
  • transfer_destination (string, default=null): The address to receive the asset (only used when transferring assets – leave set to null if issuing an asset).
  • NOTE: Additional (advanced) parameters for this call are documented here.

Return

The unsigned transaction, as an hex-encoded string. Must be signed before being broadcast: see here for more information.

Notes:

  • To lock the issuance of the asset, specify “LOCK” for the descriptionfield. It’s a special keyword that will not change the actual description, but will simply lock the asset quantity and not allow additional quantity to be issued for the asset.
  • A named asset has an issuance cost of 10 ASP.
  • A subasset has an issuance cost of 10 ASP.
  • In order to issue an asset, GASP and ASP (for first time, non-free Aspire assets) are required at the source address to pay fees.

create_send

create_send(source, destination, asset, quantity)

Send ASP or an Aspire defined asset.

Parameters

  • source (string): The address that will be sending (must have the necessary quantity of the specified asset).
  • destination (string): The address to receive the asset.
  • asset (string): The asset or subasset to send.
  • quantity (integer): The quantities of the asset to send.
  • memo (string, optional): The Memo associated with this transaction.
  • memo_is_hex (boolean, optional): If this is true, interpret the memo as a hexadecimal value. Defaults to false.
  • use_enhanced_send (boolean, optional): If this is false, the construct a legacy transaction sending GASP dust. Defaults to true.
  • NOTE: Additional (advanced) parameters for this call are documented here.

Return

The unsigned transaction, as an hex-encoded string. Must be signed before being broadcast: see here for more information.

Notes:

  • To lock the issuance of the asset, specify “LOCK” for the descriptionfield. It’s a special keyword that will not change the actual description, but will simply lock the asset quantity and not allow additional quantity to be issued for the asset.
  • A named asset has an issuance cost of 10 ASP.
  • A subasset has an issuance cost of 10 ASP.
  • In order to issue an asset, GASP and ASP (for first time, non-free Aspire assets) are required at the source address to pay fees.

Advanced create_ parameters

Each create_ call detailed below can take the following common keyword parameters:

  • encoding (string): The encoding method to use, see transaction encodings for more info.
  • pubkey (string/list): The hexadecimal public key of the source address (or a list of the keys, if multi‐sig). Required when using encodingparameter values of multisig or pubkeyhash. See transactions encoding for more info
  • allow_unconfirmed_inputs (boolean): Set to true to allow this transaction to utilize unconfirmed UTXOs as inputs. Defaults to false.
  • fee (integer): If you’d like to specify a custom miners’ fee, specify it here (in bits). Leave as default for the server to automatically choose.
  • fee_per_kb (integer): The fee per kilobyte of transaction data constant that the server uses when deciding on the dynamic fee to use (in bits).
  • fee_provided (integer): If you would like to specify a maximum fee (up to and including which may be used as the transaction fee), specify it here (in bits). This differs from fee in that this is an upper bound value, which fee is an exact value.
  • custom_inputs (list): Use only these specific UTXOs as inputs for the transaction being created. If specified, this parameter is a list of (JSON-encoded) UTXO objects, whose properties match those as retrieved by listunspent function from gaspd (e.g. see here). Note that the actual UTXOs used may be a subset of this list.
  • unspent_tx_hash (string): When compiling the UTXOs to use as inputs for the transaction being created, only consider unspent outputs from this specific transaction hash. Defaults to null to consider all UTXOs for the address. Do not use this parameter if you are specifying custom_inputs.
  • regular_dust_size (integer): Specify (in bits) to override the (dust) amount of GASP used for each non-(bare) multisig output. Defaults to 5430 bits.
  • multisig_dust_size (integer): Specify (in bits) to override the (dust) amount of GASP used for each (bare) multisig output. Defaults to 7800 bits.
  • dust_return_pubkey (string): The dust return pubkey is used in multi-sig data outputs (as the only real pubkey) to make those the outputs spendable. By default, this pubkey is taken from the pubkey used in the first transaction input. However, it can be overridden here (and is required to be specified if a P2SH input is used and multisig is used as the data output encoding.) If specified, specify the public key (in hex format) where dust will be returned to so that it can be reclaimed. Only valid/useful when used with transactions that utilize multisig data encoding. Note that if this value is set to false, this instructs aspire-server to use the default dust return pubkey configured at the node level. If this default is not set at the node level, the call will generate an exception.
  • disable_utxo_locks (boolean): By default, UTXO’s utilized when creating a transaction are “locked” for a few seconds, to prevent a case where rapidly generating create_ calls reuse UTXOs due to their spent status not being updated in gaspd yet. Specify truefor this parameter to disable this behavior, and not temporarily lock UTXOs.
  • op_return_value (integer): The value (in bits) to use with any OP_RETURN outputs in the generated transaction. Defaults to 0. Don’t use this, unless you like throwing your money away.
  • extended_tx_info (boolean): When this is not specified or false, the create_ calls return only a hex-encoded string. If this is true, the create_ calls return a data object with the following keys: tx_hex, gasp_in, gasp_out, gasp_change, and gasp_fee.

With the exception of pubkey and allow_unconfirmed_inputs, these values should be left at their defaults, unless you know what you are doing.

Transaction Encodings

By default the default value of the encoding parameter detailed above is auto, which means that aspire-server automatically determines the best way to encode the Aspire protocol data into a new transaction. If you know what you are doing and would like to explicitly specify an encoding:

  • To return the transaction as an OP_RETURN transaction, specify opreturn for the encoding parameter.
  • OP_RETURN transactions cannot have more than 80 bytes of data. If you force OP_RETURN encoding and your transaction would have more than this amount, an exception will be generated.
  • To return the transaction as a multisig transaction, specify multisigfor the encoding parameter.
    • pubkey should be set to the hex-encoded public key of the source address.
    • Note that bare multisig encoding does not reliably propagate.
  • To return the transaction as a pubkeyhash transaction, specify pubkeyhash for the encoding parameter.
    • pubkey should be set to the hex-encoded public key of the source address.

REST API Function Reference

get

get(table_name, filters, filterop)

Query table_name in the database using filters concatenated using filterop.

URL format:

/rest//get?&op=

Example query:

/rest/sends/get?source=mn6q3dS2EnDUx3bmyWc6D4szJNVGtaR7zc&destination=mtQheFaSfWELRB2MyMBaiWjdDm6ux9Ezns&op=AND

Parameters: * table_name (string): The name of the desired table. List of all available tables: assets, balances, credits, debits, broadcasts, gasppays, burns, cancels, dividends, issuances, sends, order_expirations, mempool * filters (dict, optional): Data filters as a dictionary. The filter format is same as for get_{} JSON API queries. See Filtering Read API Results for more information on filters and Object Definitions for fields available for specific objects. * filterop (string, optional): The logical operator concatenating the filters. Defaults to AND.

Headers: * Accept (string, optional): The format of return data. Can be either application/json or application/xml. Defaults to JSON.

Return

Desired database rows from table_name sieved using filters.

compose

get(table_name, filters, filterop)

Query table_name in the database using filters concatenated using filterop.

URL format:

/rest//get?&op=

Example query:

/rest/sends/get?source=mn6q3dS2EnDUx3bmyWc6D4szJNVGtaR7zc&destination=mtQheFaSfWELRB2MyMBaiWjdDm6ux9Ezns&op=AND

Parameters: * table_name (string): The name of the desired table. List of all available tables: assets, balances, credits, debits, broadcasts, gasppays, burns, cancels, dividends, issuances, sends, order_expirations, mempool * filters (dict, optional): Data filters as a dictionary. The filter format is same as for get_{} JSON API queries. See Filtering Read API Results for more information on filters and Object Definitions for fields available for specific objects. 

* filterop (string, optional): The logical operator concatenating the filters. Defaults to AND.

Headers: * Accept (string, optional): The format of return data. Can be either application/json or application/xml. Defaults to JSON.

Return

The hex data of composed transaction.

Aspire-Server API​

Objects

The API calls documented can return any one of these objects.

Balance Object

An object that describes a balance that is associated to a specific address:

  • address (string): A PubkeyHash gAsp address, or the pubkey associated with it (in case the address hasn’t sent anything before).
  • asset (string): The ID of the assets in which the balance is specified
  • quantity (integer): The quantities of the specified asset at this address

Broadcast Object

An object that describes a specific occurrence of a broadcast event (i.e. creating/extending a feed):

  • tx_index (integer): The transaction index
  • tx_hash (string): The transaction hash
  • block_index (integer): The block index (block number in the block chain)
  • source (string): The address that made the broadcast
  • timestamp (string): The time the broadcast was made, in Unix time.
  • value (float): The numerical value of the broadcast
  • text (string): The textual component of the broadcast
  • validity (string): Set to “valid” if a valid broadcast. Any other setting signifies an invalid/improper broadcast

Debit/Credit Object

An object that describes a account debit or credit:

  • tx_index (integer): The transaction index
  • tx_hash (string): The transaction hash
  • block_index (integer): The block index (block number in the block chain)
  • address (string): The address debited or credited
  • asset (string): The assets debited or credited
  • quantity (integer): The quantities of the specified asset debited or credited

Dividend Object

An object that describes an issuance of dividends on a specific user defined asset:

  • tx_index (integer): The transaction index
  • tx_hash (string): The transaction hash
  • block_index (integer): The block index (block number in the block chain)
  • source (string): The address that issued the dividend
  • asset (string): The assets that the dividends are being rewarded on
  • quantity_per_unit (integer): The quantities of ASP rewarded per whole unit of the asset
  • validity (string): Set to “valid” if a valid burn. Any other setting signifies an invalid/improper burn

Issuance Object

An object that describes a specific occurance of a user defined asset being issued, or re-issued:

  • tx_index (integer): The transaction index
  • tx_hash (string): The transaction hash
  • block_index (integer): The block index (block number in the block chain)
  • asset (string): The assets being issued, or re-issued
  • asset_longname (string): The subasset longname, if any
  • quantity (integer): The quantities of the specified asset being issued
  • divisible (boolean): Whether or not the asset is divisible (must agree with previous issuances of the asset, if there are any)
  • issuer (string):
  • transfer (boolean): Whether or not this objects marks the transfer of ownership rights for the specified quantity of this asset
  • validity (string): Set to “valid” if a valid issuance. Any other setting signifies an invalid/improper issuance

Send Object

An object that describes a specific send (e.g. “simple send”, of ASP, or a user defined asset):

  • tx_index (integer): The transaction index
  • tx_hash (string): The transaction hash
  • block_index (integer): The block index (block number in the block chain)
  • source (string): The source address of the send
  • destination (string): The destination address of the send
  • asset (string): The assets being sent
  • quantity (integer): The quantities of the specified asset sent
  • validity (string): Set to “valid” if a valid send. Any other setting signifies an invalid/improper send
  • memo (string): The memo associated with this transaction

Message Object

An object that describes a specific event in the aspired message feed (which can be used by 3rd party applications to track state changes to the aspired database on a block-by-block basis).

  • message_index (integer): The message index (i.e. transaction index)
  • block_index (integer): The block index (block number in the block chain) this event occurred on
  • category (string): A string denoting the entity that the message relates to, e.g. “credits”, “burns”, “debits”. The category matches the relevant table name in aspired (see blocks.py for more info).
  • command (string): The operation done to the table noted in category. This is either “insert”, or “update”.
  • bindings (string): A JSON-encoded object containing the message data. The properties in this object match the columns in the table referred to by category.
Aspire-Server API​

Status

Here the list of all possible status for each table:

  • balances: No status field
  • broadcasts: valid, invalid: {problem(s)}
  • gasppays: valid, invalid: {problem(s)}
  • burns: valid, invalid: {problem(s)}
  • cancels: valid, invalid: {problem(s)}
  • credits: No status field
  • debits: No status field
  • dividends: valid, invalid: {problem(s)}
  • issuances: valid, invalid: {problem(s)}
  • sends: valid, invalid: {problem(s)}
Aspire-Server API​

API Changes

This section documents any changes to the API, for version numbers where there were API-level modifications.

There will be no incompatible API pushes that do not either have:

  • A well known set cut over date in the future
  • Or, a deprecation process where the old API is supported for an amount of time

development (unreleased)

  • create_*: adds extended_tx_info parameter to create methods
Don't be a stranger

Get In Touch

Follow us on
Facebook Twitter Reddit Linkedin Telegram
drop us a line.

Fields marked with an * are required

A revolutionary asset solution platform

Receive the latest news

Subscribe To Our Newsletter

Find Us Here

Facebook Twitter Reddit Linkedin Telegram

Aspire: A Revolutionary asset solution platform

All Rights Reserved © 2021