1 of 10

Peerplays Core API

Popular API Calls

Overview

Some of the most interesting API calls for exchanges and gateways are listed in this document.

We will now take a look at some sample outputs for some of the API calls.

API Calls

list_account_balances

List the balances of an account. Each account can have multiple balances, one for each type of asset owned by that account. The returned list will only contain assets for which the account has a nonzero balance.

vector<asset> graphene::wallet::wallet_api::list_account_balances(
    const string &id)

id: the name or id of the account whose balances you want

A list of the given account’s balances.

import json
from grapheneapi import GrapheneAPI
client = GrapheneAPI("localhost", 8092, "", "")
res = client.list_account_balances("dan")
print(json.dumps(res,indent=4))

[
    {
        "asset_id": "1.3.0",
        "amount": "331104701530"
    },
    {
        "asset_id": "1.3.511",
        "amount": 3844848635
    },
    {
        "asset_id": "1.3.427",
        "amount": 8638
    },
    {
        "asset_id": "1.3.536",
        "amount": 31957981
    }
]

transfer

Transfer an amount from one account to another.

signed_transaction graphene::wallet::wallet_api::transfer(
    string from, 
    string to, 
    string amount, 
    string asset_symbol, 
    string memo, 
    bool broadcast = false)

from: the name or id of the account sending the funds
to: the name or id of the account receiving the funds
amount: the amount to send (in nominal units to send half of a BTS, specify 0.5)
asset_symbol: the symbol or id of the asset to send
memo: a memo to attach to the transaction. The memo will be encrypted in the transaction and readable for the receiver. There is no length limit other than the limit imposed by maximum transaction size, but transaction increase with transaction size
broadcast: true to broadcast the transaction on the network

The final parameter True states that the signed transaction will be broadcast. If this parameter is False the transaction will be signed but not broadcast, hence not executed.

The signed transaction transferring funds.

import json
from grapheneapi import GrapheneAPI
client = GrapheneAPI("localhost", 8092, "", "")
res = client.transfer("fromaccount","toaccount","10", "USD", "$10 gift", True);
print(json.dumps(res,indent=4))

{
  "ref_block_num": 18,
  "ref_block_prefix": 2320098938,
  "expiration": "2015-10-13T13:56:15",
  "operations": [[
      0,{
        "fee": {
          "amount": 2089843,
          "asset_id": "1.3.0"
        },
        "from": "1.2.17",
        "to": "1.2.7",
        "amount": {
          "amount": 10000000,
          "asset_id": "1.3.0"
        },
        "memo": {
          "from": "GPH6MRyAjQq8ud7hVNYcfnVPJqcVpscN5So8BhtHuGYqET5GDW5CV",
          "to": "GPH6MRyAjQq8ud7hVNYcfnVPJqcVpscN5So8BhtHuGYqET5GDW5CV",
          "nonce": "16430576185191232340",
          "message": "74d0e455e2e5587b7dc85380102c3291"
        },
        "extensions": []
      }
    ]
  ],
  "extensions": [],
  "signatures": [
    "1f147aed197a2925038e4821da54bd7818472ebe25257ac9a7ea66429494e7242d0dc13c55c6840614e6da6a5bf65ae609a436d13a3174fd12f073550f51c8e565"
  ]
}

transfer2

This method works just like transfer, except it always broadcasts and returns the transaction ID (hash) along with the signed transaction.

pair<transaction_id_type, signed_transaction> graphene::wallet::wallet_api::transfer2(
    string from, 
    string to, 
    string amount, 
    string asset_symbol, 
    string memo)

from: the name or id of the account sending the funds
to: the name or id of the account receiving the funds
amount: the amount to send
asset_symbol: the symbol or id of the asset to send
memo: a memo to attach to the transaction. The memo will be encrypted in the transaction and readable for the receiver. There is no length limit other than the limit imposed by maximum transaction size, but transaction increase with transaction size

The transaction ID (hash) along with the signed transaction transferring funds

import json
from grapheneapi import GrapheneAPI
client = GrapheneAPI("localhost", 8092, "", "")
res = client.transfer2("fromaccount","toaccount","10", "USD", "$10 gift");
print(json.dumps(res,indent=4))

 [b546a75a891b5c51de6d1aafd40d10e91a717bb3,{
   "ref_block_num": 18,
   "ref_block_prefix": 2320098938,
   "expiration": "2015-10-13T13:56:15",
   "operations": [[
       0,{
         "fee": {
           "amount": 2089843,
           "asset_id": "1.3.0"
         },
         "from": "1.2.17",
         "to": "1.2.7",
         "amount": {
           "amount": 10000000,
           "asset_id": "1.3.0"
         },
         "memo": {
           "from": "GPH6MRyAjQq8ud7hVNYcfnVPJqcVpscN5So8BhtHuGYqET5GDW5CV",
           "to": "GPH6MRyAjQq8ud7hVNYcfnVPJqcVpscN5So8BhtHuGYqET5GDW5CV",
           "nonce": "16430576185191232340",
           "message": "74d0e455e2e5587b7dc85380102c3291"
         },
         "extensions": []
       }
     ]
   ],
   "extensions": [],
   "signatures": [
     "1f147aed197a2925038e4821da54bd7818472ebe25257ac9a7ea66429494e7242d0dc13c55c6840614e6da6a5bf65ae609a436d13a3174fd12f073550f51c8e565"
   ]
 }
]

get_account_history

Returns the most recent operations on the named account.

This returns a list of operation history objects, which describe activity on the account.

vector<operation_detail> graphene::wallet::wallet_api::get_account_history(
    string name, 
    int limit)const

name: the name or id of the account
limit: the number of entries to return (starting from the most recent)

A list of operation_history_objects.

import json
from grapheneapi import GrapheneAPI
client = GrapheneAPI("localhost", 8092, "", "")
res = client.get_account_history("dan", 1)
print(json.dumps(res,indent=4))

[
     {
         "description": "fill_order_operation dan fee: 0 CORE",
         "op": {
             "block_num": 28672,
             "op": [
                 4,
                 {
                     "pays": {
                         "asset_id": "1.3.536",
                         "amount": 20000
                     },
                     "fee": {
                         "asset_id": "1.3.0",
                         "amount": 0
                     },
                     "order_id": "1.7.1459",
                     "account_id": "1.2.21532",
                     "receives": {
                         "asset_id": "1.3.0",
                         "amount": 50000000
                     }
                 }
             ],
             "id": "1.11.213277",
             "trx_in_block": 0,
             "virtual_op": 47888,
             "op_in_trx": 0,
             "result": [
                 0,
                 {}
             ]
         },
         "memo": ""
     }
 ]

get_object

Returns the blockchain object corresponding to the given id.

This generic function can be used to retrieve any object from the blockchain that is assigned an ID. Certain types of objects have specialized convenience functions to return their objects e.g., assets have get_asset(), accounts have get_account(), but this function will work for any object.

variant graphene::wallet::wallet_api::get_object(
    object_id_type id)const

id: the id of the object to return

The requested object.

import json
from grapheneapi import GrapheneAPI
client = GrapheneAPI("localhost", 8092, "", "")
res = client.get_object("1.11.213277")
print(json.dumps(res,indent=4))

{
    "trx_in_block": 0,
    "id": "1.11.213277",
    "block_num": 28672,
    "op": [
        4,
        {
            "fee": {
                "asset_id": "1.3.0",
                "amount": 0
            },
            "receives": {
                "asset_id": "1.3.0",
                "amount": 50000000
            },
            "pays": {
                "asset_id": "1.3.536",
                "amount": 20000
            },
            "account_id": "1.2.21532",
            "order_id": "1.7.1459"
        }
    ],
    "result": [
        0,
        {}
    ],
    "op_in_trx": 0,
    "virtual_op": 47888
}

get_asset

Returns information about the given asset.

extended_asset_object graphene::wallet::wallet_api::get_asset(
    string asset_name_or_id)const

asset_name_or_id: the symbol or id of the asset in question

The information about the asset stored in the block chain.

import json
from grapheneapi import GrapheneAPI
client = GrapheneAPI("localhost", 8092, "", "")
res = client.get_asset("USD")
print(json.dumps(res,indent=4))

{
    "symbol": "USD",
    "issuer": "1.2.1",
    "options": {
        "description": "1 United States dollar",
        "whitelist_authorities": [],
        "flags": 0,
        "extensions": [],
        "core_exchange_rate": {
            "quote": {
                "asset_id": "1.3.536",
                "amount": 11
            },
            "base": {
                "asset_id": "1.3.0",
                "amount": 22428
            }
        },
        "whitelist_markets": [],
        "max_supply": "1000000000000000",
        "blacklist_markets": [],
        "issuer_permissions": 79,
        "market_fee_percent": 0,
        "max_market_fee": "1000000000000000",
        "blacklist_authorities": []
    },
    "dynamic_asset_data_id": "2.3.536",
    "bitasset_data_id": "2.4.32",
    "id": "1.3.536",
    "precision": 4
}

Account History API

The history API is available from the full node via websockets.

Account History

get_account_history

Get operations relevant to the specified account.

account_id_or_name: The account ID or name whose history should be queried
stop: ID of the earliest operation to retrieve
limit: Maximum number of operations to retrieve (must not exceed 100)
start: ID of the most recent operation to retrieve

A list of operations performed by account, ordered from most recent to oldest.

get_account_history_operations

Get only asked operations relevant to the specified account.

account_id_or_name: The account ID or name whose history should be queried
operation_type: The type of the operation we want to get operations in the account ( 0 = transfer , 1 = limit order create, …)
stop: ID of the earliest operation to retrieve
limit: Maximum number of operations to retrieve (must not exceed 100)
start: ID of the most recent operation to retrieve

A list of operations performed by account, ordered from most recent to oldest.

get_relative_account_history

Get operations relevant to the specified account referenced by an event numbering specific to the account. The current number of operations for the account can be found in the account statistics (or use 0 for start).

account_id_or_name: The account ID or name whose history should be queried
stop: Sequence number of earliest operation. 0 is default and will query ‘limit’ number of operations.
limit: Maximum number of operations to retrieve (must not exceed 100)
start: Sequence number of the most recent operation to retrieve. 0 is default, which will start querying from the most recent operation.

A list of operations performed by account, ordered from most recent to oldest.

Market History

get_fill_order_history

Get details of order executions occurred most recently in a trading pair.

a: Asset symbol or ID in a trading pair
b: The other asset symbol or ID in the trading pair
limit: Maximum records to return

a list of order_history objects, in most recent first order

get_market_history

Get OHLCV data of a trading pair in a time range.

a: Asset symbol or ID in a trading pair
b: The other asset symbol or ID in the trading pair
bucket_seconds: Length of each time bucket in seconds.

start: The start of a time range, E.G. “2018-01-01T00:00:00”
end: The end of the time range

A list of OHLCV data, in least recent first order.

If there are more than 200 records in the specified time range, the first 200 records will be returned.

get_market_history_buckets

Get OHLCV time bucket lengths supported (configured) by this API server.

A list of time bucket lengths in seconds.

For example, if the result contains a number “300” it means this API server supports OHLCV data aggregated in 5-minute buckets.

Asset API

Asset

get_asset_holders

Get asset holders for a specific asset.

asset: The specific asset id or symbol
start: The start index
limit: Maximum limit must not exceed 100

A list of asset holders for the specified asset.

get_all_asset_holders

Get all asset holders.

A list of all asset holders.

Block API

Block

get_blocks

Get signed blocks.

block_num_from: The lowest block number
block_num_to: The highest block number

A list of signed blocks from block_num_from to block_num_to

Crypto API

The crypto API is available from the full node via websockets.

Blinding and Un-Blinding

blind

Get signed blocks.

Generates a Pedersen Commitment: *commit = blind * G + value * G2. The commitment is 33 bytes, the blinding factor is 32 bytes.

Tip: For more information about Pedersen Commitment see: Commitment Scheme

commitment_type graphene::app::crypto_api::blind(
    const fc::ecc::blind_factor_type &blind, 
    uint64_t value)

blind: Sha-256 blind factor type
value: Positive 64-bit integer value

A 33-byte Pedersen Commitment: commit = blind G + value * G2

blind_sum

Get SHA-256 blind factor type.

blind_factor_type graphene::app::crypto_api::blind_sum(
    const std::vector<blind_factor_type> &blinds_in, 
    uint32_t non_neg)

blinds_in: List of SHA-256 blind factor types
non_neg: 32-bit integer value

A blind factor type.

Range Proofs

range_get_info

Gets “range proof” information.

The cli_wallet includes functionality for sending blind transfers in which the values of the input and output amounts are “blinded.”

Note: In the case where a transaction produces two or more outputs, (e.g. an amount to the intended recipient plus “charge” back to the sender), a “range proof” must be supplied to prove that none of the outputs commit to a negative value.

range_proof_info graphene::app::crypto_api::range_get_info(
    const std::vector<char> &proof)

proof: List of proof’s characters

A range proof info structure with exponent, mantissa, min and max values.

range_proof_sign

Proves with respect to min_value the range for Pedersen Commitment which has the provided blinding factor and value.

std::vector<char> graphene::app::crypto_api::range_proof_sign(
    uint64_t min_value, 
    const commitment_type &commit, 
    const blind_factor_type &commit_blind, 
    const blind_factor_type &nonce, 
    int8_t base10_exp, 
    uint8_t min_bits, 
    uint64_t actual_value

min_value: Positive 64-bit integer value
commit: 33-byte pedersen commitment
commit_blind: Sha-256 blind factor type for the correct digits
nonce: Sha-256 blind factor type for our non-forged signatures
base10_exp: Exponents base 10 in range [-1 ; 18] inclusively
min_bits: 8-bit positive integer, must be in range [0 ; 64] inclusively
actual_value: 64-bit positive integer, must be greater or equal min_value

A list of characters as proof in proof.

Verification

verify_sum

Verifies that commits + neg_commits + excess == 0.

bool graphene::app::crypto_api::verify_sum(
    const std::vector<commitment_type> &commits_in, 
    const std::vector<commitment_type> &neg_commits_in, 
    int64_t excess)

commits_in: List of 33-byte Pedersen Commitments
neg_commits_in: List of 33-byte Pedersen Commitments
excess: Sum of two list of 33-byte Pedersen Commitments where sums the first set and subtracts the second

(Boolean) True in event of commits + neg_commits + excess == 0, otherwise false

verify_range

Verifies range proof for 33-byte Pedersen Commitment.

verify_range_result graphene::app::crypto_api::verify_range(
    const fc::ecc::commitment_type &commit, 
    const std::vector<char> &proof)

commit: 33-byte pedersen commitment
proof: List of characters

A structure with success, min and max values

verify_range_proof_rewind

Verifies range proof rewind for 33-byte Pedersen Commitment.

verify_range_proof_rewind_result graphene::app::crypto_api::verify_range_proof_rewind(
    const blind_factor_type &nonce, 
    const fc::ecc::commitment_type &commit, 
    const std::vector<char> &proof)

nonce: Sha-256 blind refactor type
commit: 33-byte pedersen commitment
proof: List of characters

A structure with success, min, max, value_out, blind_out and message_out values.

Network Broadcast API

The network broadcast API is available from the full node via web-sockets.

Transactions

broadcast_transaction

Broadcast a transaction to the network.

The transaction will be checked for validity in the local database prior to broadcasting. If it fails to apply locally, an error will be thrown and the transaction will not be broadcast

void graphene::app::network_broadcast_api::broadcast_transaction(
    const precomputable_transaction &trx)

trx: The transaction to broadcast

broadcast_transaction_with_callback

This version of broadcast transaction registers a callback method that will be called when the transaction is included into a block. The callback method includes the transaction id, block number, and transaction number in the block.

void graphene::app::network_broadcast_api::broadcast_transaction_with_callback(
    confirmation_callback cb, 
    const precomputable_transaction &trx)

cb: the callback method
trx: the transaction

Block

broadcast_block

Broadcast a signed block to the network.

void graphene::app::network_broadcast_api::broadcast_block(
    const signed_block &block)

block: The signed block to broadcast.

Network Nodes API

The network node API is available from the full node via web-sockets.

Obtain Network Information

get_info

Return general network information, such as p2p port.

get_connected_peers

Get status of all current connections to peers.

get_potential_peers

Return list of potential peers.

get_advanced_node_parameters

Get advanced node parameters, such as desired and max number of connections.

Change Network Settings

add_node

Connect to a new peer

ep: The IP/Port of the peer to connect to

set_advanced_node_parameters

Set advanced node parameters, such as desired and max number of connections.

params: a JSON object containing the name/value pairs for the parameters to set

Orders API

Orders

get_grouped_limit_orders

Get grouped limit orders in given market.

base_asset: ID or symbol of asset being sold
quote_asset: ID or symbol of asset being purchased
group: Maximum price diff within each order group, have to be one of configured values
start: Optional price to indicate the first order group to retrieve
limit: Maximum number of order groups to retrieve (must not exceed 101)

The grouped limit orders, ordered from best offered price to the worst.

Database API

The database API is available from the full node via web-sockets.

Objects

get_objects

Get the objects corresponding to the provided IDs.

If any of the provided IDs does not map to an object, a null variant is returned in its position.

fc::variants graphene::app::database_api::get_objects(
    const vector<object_id_type> &ids, 
    optional<bool> subscribe = optional<bool>())const

ids: IDs of the objects to retrieve
subscribe: true to subscribe to the queried objects; false to not subscribe; null to subscribe or not subscribe according to current auto-subscription setting (see set_auto_subscription)

The objects retrieved, in the order they are mentioned in ids.

Subscriptions

set_subscribe_callback

Note: auto-subscription is enabled by default and can be disabled with set_auto_subscription

void graphene::app::database_api::set_subscribe_callback(
    std::function<void(const variant&)> cb, 
    bool notify_remove_create, )

cb: The callback handle to register
notify_remove_create: Whether subscribe to universal object creation and removal events. If this is set to true, the API server will notify all newly created objects and ID of all newly removed objects to the client, no matter whether client subscribed to the objects. By default, API servers don’t allow subscribing to universal events, which can be changed on server startup.

set_pending_transaction_callback

Note: A transaction can be pushed to the database and be popped from the database several times while processing, before and after,, included in a block. Every time a push is done, the client will be notified.

void graphene::app::database_api::set_pending_transaction_callback(
    std::function<void(const variant &signed_transaction_object)> cb)

cb: The callback handle to register

set_block_applied_callback

void graphene::app::database_api::set_block_applied_callback(
    std::function<void(const variant &block_id)> cb)

cb: The callback handle to register

cancel_all_subscriptions

Stop receiving any notifications.

This unsubscribes from all subscribed markets and objects.

void graphene::app::database_api::cancel_all_subscriptions()

Blocks and transactions

get_block_header

Retrieve a block header.

optional<block_header> graphene::app::database_api::get_block_header(
    uint32_t block_num)const

block_num: Height of the block whose header should be returned

The header of the referenced block, or null if no matching block was foun

get_block

Retrieve a full, signed block.

optional<signed_block> graphene::app::database_api::get_block(
    uint32_t block_num)const

block_num: Height of the block to be returned

The referenced block, or null if no matching block was found.

get_transaction

Fetch an individual transaction.

processed_transaction graphene::app::database_api::get_transaction(
    uint32_t block_num, uint32_t trx_in_block)const

block_num: height of the block to fetch
trx_in_block: the index (sequence number) of the transaction in the block, starts from 0

The transaction at the given position.

get_recent_transaction_by_id

optional<signed_transaction> graphene::app::database_api::get_recent_transaction_by_id(
    const transaction_id_type &txid)const

txid: hash of the transaction

The corresponding transaction if found, or null if not found.

If the transaction has not expired, this method will return the transaction for the given ID or it will return NULL if it is not known. Just because it is not known does not mean it wasn’t included in the blockchain.

Globals

get_chain_properties

Retrieve the graphene::chain::chain_property_object associated with the chain.

chain_property_object graphene::app::database_api::get_chain_properties()const

get_global_properties

Retrieve the current graphene::chain::global_property_object.

global_property_object graphene::app::database_api::get_global_properties()const

get_config

Retrieve compile-time constants.

fc::variant_object graphene::app::database_api::get_config()const

get_chain_id

Get the chain ID.

chain_id_type graphene::app::database_api::get_chain_id()cons

get_dynamic_global_properties

Retrieve the current graphene::chain::dynamic_global_property_object.

dynamic_global_property_object graphene::app::database_api::get_dynamic_global_properties()const

Keys

get_key_references

Get all accounts that refer to the specified public keys in their owner authority, active authorities or memo key.

vector<flat_set<account_id_type>> graphene::app::database_api::get_key_references(
    vector<public_key_type> keys)const

keys: a list of public keys to query

ID of all accounts that refer to the specified keys.

Accounts

get_accounts

Get a list of accounts by names or IDs.

This function has semantics identical toget_objects

vector<optional<account_object>> graphene::app::database_api::get_accounts(
    const vector<std::string> &account_names_or_ids, 
    optional<bool> subscribe = optional<bool>())const

account_names_or_ids: names or IDs of the accounts to retrieve
subscribe: true to subscribe to the queried account objects; false to not subscribe; null to subscribe or not subscribe according to current auto-subscription setting (see set_auto_subscription)

The accounts corresponding to the provided names or IDs.

get_full_accounts

Fetch all objects relevant to the specified accounts and optionally subscribe to updates.

This function fetches all relevant objects for the given accounts, and subscribes to updates to the given accounts. If any of the strings innames_or_ids cannot be tied to an account, that input will be ignored. All other accounts will be retrieved and subscribed.

std::map<string, full_account> graphene::app::database_api::get_full_accounts(
    const vector<string> &names_or_ids, 
    optional<bool> subscribe = optional<bool>())

names_or_ids: Each item must be the name or ID of an account to retrieve
subscribe: true to subscribe to the queried full account objects; false to not subscribe; null to subscribe or not subscribe according to current auto-subscription setting (see set_auto_subscription)

Map of string from names_or_ids to the corresponding account.

get_account_by_name

Get info of an account by name.

optional<account_object> graphene::app::database_api::get_account_by_name(
    string name)const

name: Name of the account to retrieve

The account holding the provided name.

get_account_references

Get all accounts that refer to the specified account in their owner or active authorities.

vector<account_id_type> graphene::app::database_api::get_account_references(
    const std::string account_name_or_id)const

account_name_or_id: Account name or ID to query

All accounts that refer to the specified account in their owner or active authorities

lookup_account_names

Get a list of accounts by name.

This function has semantics identical to get_objects, but doesn’t subscribe

vector<optional<account_object>> graphene::app::database_api::lookup_account_names(
    const vector<string> &account_names)const

account_names: Names of the accounts to retrieve

The accounts holding the provided names.

lookup_accounts

Get names and IDs for registered accounts.

Note: In addition to the common auto-subscription rules, this API will subscribe to the returned account only if limit is 1.

map<string, account_id_type> graphene::app::database_api::lookup_accounts(
    const string &lower_bound_name, 
    uint32_t limit, 
    optional<bool> subscribe = optional<bool>())const

lower_bound_name: Lower bound of the first name to return
limit: Maximum number of results to return must not exceed 1000
subscribe: true to subscribe to the queried account objects; false to not subscribe; null to subscribe or not subscribe according to current auto-subscription setting (see set_auto_subscription).

Map of account names to corresponding IDs.

get_account_count

Get the total number of accounts registered with the blockchain.

uint64_t graphene::app::database_api::get_account_count()const

Balances

get_account_balances

Get an account’s balances in various assets.

vector<asset> graphene::app::database_api::get_account_balances(
    const std::string &account_name_or_id, 
    const flat_set<asset_id_type> &assets)const

account_name_or_id: name or ID of the account to get balances for.
assets: IDs of the assets to get balances of; if empty, get all assets account has a balance in.

Balances of the account.

get_named_account_balances

Semantically equivalent to get_account_balances.

vector<asset> graphene::app::database_api::get_named_account_balances(
    const std::string &name, 
    const flat_set<asset_id_type> &assets)const

account_name_or_id: name or ID of the account to get balances for.
assets: IDs of the assets to get balances of; if empty, get all assets account has a balance in.

Balances of the account.

get_balance_objects

vector<balance_object> graphene::app::database_api::get_balance_objects(
    const vector<address> &addrs)const

addrs: a list of addresses

All unclaimed balance objects for the addresses.

get_vested_balances

Calculate how much assets in the given balance objects are able to be claimed at current head block time.

vector<asset> graphene::app::database_api::get_vested_balances(
    const vector<balance_id_type> &objs)const

objs: a list of balance object IDs

A list indicating how much asset in each balance object is available to be claimed.

get_vesting_balances

Return all vesting balance objects owned by an account.

vector<vesting_balance_object> graphene::app::database_api::get_vesting_balances(
    const std::string account_name_or_id)const

account_name_or_id: name or ID of an account

All vesting balance objects owned by the account.

Assets

get_assets

Get a list of assets by symbol names or IDs.

Semantically equivalent to get_objects.

vector<optional<extended_asset_object>> graphene::app::database_api::get_assets(
    const vector<std::string> &asset_symbols_or_ids, 
    optional<bool> subscribe = optional<bool>())const

asset_symbols_or_ids: symbol names or IDs of the assets to retrieve
subscribe: true to subscribe to the queried asset objects; false to not subscribe; null to subscribe or not subscribe according to current auto-subscription setting (see set_auto_subscription)

The assets corresponding to the provided symbol names or IDs.

list_assets

Get assets alphabetically by symbol name.

vector<extended_asset_object> graphene::app::database_api::list_assets(
    const string &lower_bound_symbol, 
    uint32_t limit)const

lower_bound_symbol: Lower bound of symbol names to retrieve
limit: Maximum number of assets to fetch (must not exceed 101)

The assets found.

lookup_asset_symbols

Get a list of assets by symbol names or IDs.

Semantically equivalent to get_objects, but doesn’t subscribe.

vector<optional<extended_asset_object>> graphene::app::database_api::lookup_asset_symbols(
    const vector<string> &symbols_or_ids)const

symbols_or_ids: symbol names or IDs of the assets to retrieve

The assets corresponding to the provided symbols or IDs

Markets / Feeds

get_order_book

Returns the order book for the market base

order_book graphene::app::database_api::get_order_book(
    const string &base, 
    const string &quote, 
    unsigned limit = 50)const

base: symbol name or ID of the base asset
quote: symbol name or ID of the quote asset
limit: depth of the order book to retrieve, for bids and asks each, capped at 50

Order book of the market.

get_limit_orders

Get limit orders in a given market.

vector<limit_order_object> graphene::app::database_api::get_limit_orders(
    std::string a, 
    std::string b, 
    uint32_t limit)const

a: symbol or ID of asset being sold
b: symbol or ID of asset being purchased
limit: Maximum number of orders to retrieve

The limit orders, ordered from least price to greatest.

get_call_orders

Get call orders (aka margin positions) for a given asset.

vector<call_order_object> graphene::app::database_api::get_call_orders(
    const std::string &a, 
    uint32_t limit)const

a: symbol name or ID of the debt asset
limit: Maximum number of orders to retrieve

The call orders, ordered from earliest to be called to latest

get_settle_orders

Get forced settlement orders in a given asset.

vector<force_settlement_object> graphene::app::database_api::get_settle_orders(
    const std::string &a, 
    uint32_t limit)const

a: Symbol or ID of asset being settled
limit: Maximum number of orders to retrieve

The settle orders, ordered from earliest settlement date to latest.

get_margin_positions

Get all open margin positions of a given account.

Similar to get_call_orders_by_account, but without pagination.

vector<call_order_object> graphene::app::database_api::get_margin_positions(
    const std::string account_name_or_id)const

account_name_or_id: name or ID of an account

All open margin positions of the account.

subscribe_to_market

Request notification when the active orders in the market between two assets changes.

Callback will be passed a variant containing a vector<pair<operation, operation_result>>.

The vector will contain, in order, the operations which changed the market, and their results

void graphene::app::database_api::subscribe_to_market(std::function<void(
    const variant&)> callback, 
    const std::string &a, 
    const std::string &b, )

callback: Callback method which is called when the market changes
a: symbol name or ID of the first asset
b: symbol name or ID of the second asset

unsubscribe_from_market

Unsubscribe from updates to a given market.

void graphene::app::database_api::unsubscribe_from_market(
    const std::string &a, 
    const std::string &b)

a: symbol name or ID of the first asset
b: symbol name or ID of the second asset

get_ticker

Returns the ticker for the market assetA:assetB.

market_ticker graphene::app::database_api::get_ticker(
    const string &base, 
    const string &quote)const

base: symbol name or ID of the base asset
quote: symbol name or ID of the quote asset

The market ticker for the past 24 hours.

get_24_volume

Returns the 24 hour volume for the market assetA:assetB.

market_volume graphene::app::database_api::get_24_volume(
    const string &base, 
    const string &quote)const

base: symbol name or ID of the base asset
quote: symbol name or ID of the quote asset

The market volume over the past 24 hours.

get_trade_history

Returns recent trades for the market base:quote, ordered by time, most recent first.

Note: Currently, timezone offsets are not supported. The time must be UTC.

The range is [stop, start). In case there are more than 100 trades occurring in the same second, this API only returns the first 100 records; use get_trade_history_by_sequence to query for the rest.

vector<market_trade> graphene::app::database_api::get_trade_history(
    const string &base, 
    const string &quote, 
    fc::time_point_sec start, 
    fc::time_point_sec stop, 
    unsigned limit = 100)const

base: symbol or ID of the base asset
quote: symbol or ID of the quote asset
start: Start time as a UNIX timestamp, the latest trade to retrieve
stop: Stop time as a UNIX timestamp, the earliest trade to retrieve
limit: Number of transactions to retrieve, capped at 100.

Recent transactions in the market

Witnesses

get_witnesses

Get a list of witnesses by ID.

Semantically equivalent to get_objects, but doesn’t subscribe.

vector<optional<witness_object>> graphene::app::database_api::get_witnesses(
    const vector<witness_id_type> &witness_ids)const

witness_ids: IDs of the witnesses to retrieve

The witnesses corresponding to the provided IDs.

get_witness_by_account

Get the witness owned by a given account.

fc::optional<witness_object> graphene::app::database_api::get_witness_by_account(
    const std::string account_name_or_id)const

account_name_or_id: The name or ID of the account whose witness should be retrieved

The witness object, or null if the account does not have a witness.

lookup_witness_accounts

Get names and IDs for registered witnesses.

map<string, witness_id_type> graphene::app::database_api::lookup_witness_accounts(
    const string &lower_bound_name, uint32_t limit)const

lower_bound_name: Lower bound of the first name to return
limit: Maximum number of results to return must not exceed 1000

Map of witness names to corresponding IDs.

get_witness_count

Get the total number of witnesses registered with the blockchain.

uint64_t graphene::app::database_api::get_witness_count()const

Committee members

get_committee_members

Get a list of committee_members by ID.

Semantically equivalent to get_objects, but doesn’t subscribe.

vector<optional<committee_member_object>> graphene::app::database_api::get_committee_members(
    const vector<committee_member_id_type> &committee_member_ids)const

committee_member_ids: IDs of the committee_members to retrieve

The committee_members corresponding to the provided IDs.

get_committee_member_by_account

Get the committee_member owned by a given account.

fc::optional<committee_member_object> graphene::app::database_api::get_committee_member_by_account(
    const string account_name_or_id)const

account_name_or_id: The name or ID of the account whose committee_member should be retrieved

The committee_member object, or null if the account does not have a committee_member.

lookup_committee_member_accounts

Get names and IDs for registered committee_members.

map<string, committee_member_id_type> graphene::app::database_api::lookup_committee_member_accounts(
    const string &lower_bound_name, 
    uint32_t limit)const

lower_bound_name: Lower bound of the first name to return
limit: Maximum number of results to return must not exceed 1000

Map of committee_member names to corresponding IDs

Workers

get_workers_by_account

Get the workers owned by a given account.

vector<optional<worker_object>> graphene::app::database_api::get_workers_by_account(
    const std::string account_name_or_id)const

account_name_or_id: The name or ID of the account whose worker should be retrieved

A list of worker objects owned by the account.

Votes

lookup_vote_ids

Given a set of votes, returns the objects they are voting for.

This will be a mixture of committee_member_objects, witness_objects, and worker_objects

vector<variant> graphene::app::database_api::lookup_vote_ids(
    const vector<vote_id_type> &votes)const

votes: a list of vote IDs

The referenced objects

The results will be in the same order as the votes. Null will be returned for any vote IDs that are not found.

Authority / Validation

get_transaction_hex

Get a hexdump of the serialized binary form of a transaction.

std::string graphene::app::database_api::get_transaction_hex(
    const signed_transaction &trx)const

trx: a transaction to get hexdump from

The hexdump of the transaction.

get_required_signatures

This API will take a partially signed transaction and a set of public keys that the owner has the ability to sign for and return the minimal subset of public keys that should add signatures to the transaction.

set<public_key_type> graphene::app::database_api::get_required_signatures(
    const signed_transaction &trx, 
    const flat_set<public_key_type> &available_keys)const

trx: the transaction to be signed
available_keys: a set of public keys

A subset of available_keys that could sign for the given transaction.

get_potential_signatures

This method will return the set of all public keys that could possibly sign for a given transaction. This call can be used by wallets to filter their set of public keys to just the relevant subset prior to calling get_required_signatures to get the minimum subset.

set<public_key_type> graphene::app::database_api::get_potential_signatures(
    const signed_transaction &trx)const

trx: the transaction to be signed

A set of public keys that could possibly sign for the given transaction.

get_potential_address_signatures

This method will return the set of all addresses that could possibly sign for a given transaction.

set<address> graphene::app::database_api::get_potential_address_signatures(
    const signed_transaction &trx)const

trx: the transaction to be signed

A set of addresses that could possibly sign for the given transaction.

verify_authority

Check whether a transaction has all of the required signatures

bool graphene::app::database_api::verify_authority(
    const signed_transaction &trx)const

trx: a transaction to be verified

true if the trx has all of the required signatures, otherwise throws an exception.

verify_account_authority

Verify that the public keys have enough authority to approve an operation for this account.

bool graphene::app::database_api::verify_account_authority(
    const string &account_name_or_id, 
    const flat_set<public_key_type> &signers)const

account_name_or_id: name or ID of an account to check
signers: the public keys

true if the passed in keys have enough authority to approve an operation for this account.

validate_transaction

Validates a transaction against the current state without broadcasting it on the network.

processed_transaction graphene::app::database_api::validate_transaction(
const signed_transaction &trx)const

trx: a transaction to be validated

A processed_transaction object if the transaction passes the validation, otherwise an exception will be thrown.

get_required_fees

For each operation calculate the required fee in the specified asset type.

vector<fc::variant> graphene::app::database_api::get_required_fees(
    const vector<operation> &ops, 
    const std::string &asset_symbol_or_id)const

ops: a list of operations to be query for required fees
asset_symbol_or_id: symbol name or ID of an asset that to be used to pay the fees

A list of objects which indicates required fees of each operation

Proposed Transactions

get_proposed_transactions

Gets a set of proposed transactions (proposals) that the specified account can add approval to or remove approval from.

vector<proposal_object> graphene::app::database_api::get_proposed_transactions(
    const std::string account_name_or_id)const

account_name_or_id: The name or ID of an account

A set of proposed transactions that the specified account can act on.

Blinded balances

get_blinded_balances

Gets the set of blinded balance objects by commitment ID.

vector<blinded_balance_object> graphene::app::database_api::get_blinded_balances(
    const flat_set<commitment_type> &commitments)const

commitments: a set of commitments to query for

The set of blinded balance objects by commitment ID.

Popular API Calls

Overview

Some of the most interesting API calls for exchanges and gateways are listed in this document.

We will now take a look at some sample outputs for some of the API calls.

API Calls

list_account_balances

vector<asset> graphene::wallet::wallet_api::list_account_balances(
    const string &id)

id: the name or id of the account whose balances you want

A list of the given account’s balances.

import json
from grapheneapi import GrapheneAPI
client = GrapheneAPI("localhost", 8092, "", "")
res = client.list_account_balances("dan")
print(json.dumps(res,indent=4))

[
    {
        "asset_id": "1.3.0",
        "amount": "331104701530"
    },
    {
        "asset_id": "1.3.511",
        "amount": 3844848635
    },
    {
        "asset_id": "1.3.427",
        "amount": 8638
    },
    {
        "asset_id": "1.3.536",
        "amount": 31957981
    }
]

transfer

Transfer an amount from one account to another.

signed_transaction graphene::wallet::wallet_api::transfer(
    string from, 
    string to, 
    string amount, 
    string asset_symbol, 
    string memo, 
    bool broadcast = false)

from: the name or id of the account sending the funds
to: the name or id of the account receiving the funds
amount: the amount to send (in nominal units to send half of a BTS, specify 0.5)
asset_symbol: the symbol or id of the asset to send
memo: a memo to attach to the transaction. The memo will be encrypted in the transaction and readable for the receiver. There is no length limit other than the limit imposed by maximum transaction size, but transaction increase with transaction size
broadcast: true to broadcast the transaction on the network

The final parameter True states that the signed transaction will be broadcast. If this parameter is False the transaction will be signed but not broadcast, hence not executed.

The signed transaction transferring funds.

import json
from grapheneapi import GrapheneAPI
client = GrapheneAPI("localhost", 8092, "", "")
res = client.transfer("fromaccount","toaccount","10", "USD", "$10 gift", True);
print(json.dumps(res,indent=4))

{
  "ref_block_num": 18,
  "ref_block_prefix": 2320098938,
  "expiration": "2015-10-13T13:56:15",
  "operations": [[
      0,{
        "fee": {
          "amount": 2089843,
          "asset_id": "1.3.0"
        },
        "from": "1.2.17",
        "to": "1.2.7",
        "amount": {
          "amount": 10000000,
          "asset_id": "1.3.0"
        },
        "memo": {
          "from": "GPH6MRyAjQq8ud7hVNYcfnVPJqcVpscN5So8BhtHuGYqET5GDW5CV",
          "to": "GPH6MRyAjQq8ud7hVNYcfnVPJqcVpscN5So8BhtHuGYqET5GDW5CV",
          "nonce": "16430576185191232340",
          "message": "74d0e455e2e5587b7dc85380102c3291"
        },
        "extensions": []
      }
    ]
  ],
  "extensions": [],
  "signatures": [
    "1f147aed197a2925038e4821da54bd7818472ebe25257ac9a7ea66429494e7242d0dc13c55c6840614e6da6a5bf65ae609a436d13a3174fd12f073550f51c8e565"
  ]
}

transfer2

This method works just like transfer, except it always broadcasts and returns the transaction ID (hash) along with the signed transaction.

pair<transaction_id_type, signed_transaction> graphene::wallet::wallet_api::transfer2(
    string from, 
    string to, 
    string amount, 
    string asset_symbol, 
    string memo)

from: the name or id of the account sending the funds
to: the name or id of the account receiving the funds
amount: the amount to send
asset_symbol: the symbol or id of the asset to send
memo: a memo to attach to the transaction. The memo will be encrypted in the transaction and readable for the receiver. There is no length limit other than the limit imposed by maximum transaction size, but transaction increase with transaction size

The transaction ID (hash) along with the signed transaction transferring funds

import json
from grapheneapi import GrapheneAPI
client = GrapheneAPI("localhost", 8092, "", "")
res = client.transfer2("fromaccount","toaccount","10", "USD", "$10 gift");
print(json.dumps(res,indent=4))

 [b546a75a891b5c51de6d1aafd40d10e91a717bb3,{
   "ref_block_num": 18,
   "ref_block_prefix": 2320098938,
   "expiration": "2015-10-13T13:56:15",
   "operations": [[
       0,{
         "fee": {
           "amount": 2089843,
           "asset_id": "1.3.0"
         },
         "from": "1.2.17",
         "to": "1.2.7",
         "amount": {
           "amount": 10000000,
           "asset_id": "1.3.0"
         },
         "memo": {
           "from": "GPH6MRyAjQq8ud7hVNYcfnVPJqcVpscN5So8BhtHuGYqET5GDW5CV",
           "to": "GPH6MRyAjQq8ud7hVNYcfnVPJqcVpscN5So8BhtHuGYqET5GDW5CV",
           "nonce": "16430576185191232340",
           "message": "74d0e455e2e5587b7dc85380102c3291"
         },
         "extensions": []
       }
     ]
   ],
   "extensions": [],
   "signatures": [
     "1f147aed197a2925038e4821da54bd7818472ebe25257ac9a7ea66429494e7242d0dc13c55c6840614e6da6a5bf65ae609a436d13a3174fd12f073550f51c8e565"
   ]
 }
]

get_account_history

Returns the most recent operations on the named account.

This returns a list of operation history objects, which describe activity on the account.

vector<operation_detail> graphene::wallet::wallet_api::get_account_history(
    string name, 
    int limit)const

name: the name or id of the account
limit: the number of entries to return (starting from the most recent)

A list of operation_history_objects.

import json
from grapheneapi import GrapheneAPI
client = GrapheneAPI("localhost", 8092, "", "")
res = client.get_account_history("dan", 1)
print(json.dumps(res,indent=4))

[
     {
         "description": "fill_order_operation dan fee: 0 CORE",
         "op": {
             "block_num": 28672,
             "op": [
                 4,
                 {
                     "pays": {
                         "asset_id": "1.3.536",
                         "amount": 20000
                     },
                     "fee": {
                         "asset_id": "1.3.0",
                         "amount": 0
                     },
                     "order_id": "1.7.1459",
                     "account_id": "1.2.21532",
                     "receives": {
                         "asset_id": "1.3.0",
                         "amount": 50000000
                     }
                 }
             ],
             "id": "1.11.213277",
             "trx_in_block": 0,
             "virtual_op": 47888,
             "op_in_trx": 0,
             "result": [
                 0,
                 {}
             ]
         },
         "memo": ""
     }
 ]

get_object

Returns the blockchain object corresponding to the given id.

variant graphene::wallet::wallet_api::get_object(
    object_id_type id)const

id: the id of the object to return

The requested object.

import json
from grapheneapi import GrapheneAPI
client = GrapheneAPI("localhost", 8092, "", "")
res = client.get_object("1.11.213277")
print(json.dumps(res,indent=4))

{
    "trx_in_block": 0,
    "id": "1.11.213277",
    "block_num": 28672,
    "op": [
        4,
        {
            "fee": {
                "asset_id": "1.3.0",
                "amount": 0
            },
            "receives": {
                "asset_id": "1.3.0",
                "amount": 50000000
            },
            "pays": {
                "asset_id": "1.3.536",
                "amount": 20000
            },
            "account_id": "1.2.21532",
            "order_id": "1.7.1459"
        }
    ],
    "result": [
        0,
        {}
    ],
    "op_in_trx": 0,
    "virtual_op": 47888
}

get_asset

Returns information about the given asset.

extended_asset_object graphene::wallet::wallet_api::get_asset(
    string asset_name_or_id)const

asset_name_or_id: the symbol or id of the asset in question

The information about the asset stored in the block chain.

import json
from grapheneapi import GrapheneAPI
client = GrapheneAPI("localhost", 8092, "", "")
res = client.get_asset("USD")
print(json.dumps(res,indent=4))

{
    "symbol": "USD",
    "issuer": "1.2.1",
    "options": {
        "description": "1 United States dollar",
        "whitelist_authorities": [],
        "flags": 0,
        "extensions": [],
        "core_exchange_rate": {
            "quote": {
                "asset_id": "1.3.536",
                "amount": 11
            },
            "base": {
                "asset_id": "1.3.0",
                "amount": 22428
            }
        },
        "whitelist_markets": [],
        "max_supply": "1000000000000000",
        "blacklist_markets": [],
        "issuer_permissions": 79,
        "market_fee_percent": 0,
        "max_market_fee": "1000000000000000",
        "blacklist_authorities": []
    },
    "dynamic_asset_data_id": "2.3.536",
    "bitasset_data_id": "2.4.32",
    "id": "1.3.536",
    "precision": 4
}