Database API

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

If you have not set up your websockets connection, please read this article.

Objects 

get_objects 

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

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.

Note

operation_history_object (1.11.x) and account_history_object (2.9.x) can not be subscribed.

Parameters:

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)

Returns:

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

Subscriptions 

set_pending_transaction_callback 

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

Register a callback handle which will get notified when a transaction is pushed to database.

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

Parameters:: 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)

Register a callback handle which will get notified when a block is pushed to database.

Parameters:: cb – The callback handle to register

cancel_all_subscriptions 

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

Stop receiving any notifications.

This unsubscribes from all subscribed markets and objects.

Blocks and transactions 

get_block_header 

optional<maybe_signed_block_header> graphene::app::database_api::get_block_header(uint32_t block_num, const optional<bool> &with_witness_signature = optional<bool>()) const

Retrieve a block header.

Parameters:

block_num – Height of the block whose header should be returned
with_witness_signature – Whether to return witness signature. Optional. If omitted or is false, will not return witness signature.

Returns:

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

get_block 

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

Retrieve a full, signed block.

Parameters:: block_num – Height of the block to be returned
Returns:: the referenced block, or null if no matching block was found

get_transaction 

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

used to fetch an individual transaction.

Parameters:

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

Returns:

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

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.

Parameters:: txid – hash of the transaction
Returns:: the corresponding transaction if found, or null if not found

Globals 

get_chain_properties 

chain_property_object graphene::app::database_api::get_chain_properties() const: Retrieve the graphene::chain::chain_property_object associated with the chain.

get_global_properties 

global_property_object graphene::app::database_api::get_global_properties() const: Retrieve the current graphene::chain::global_property_object.

get_config 

fc::variant_object graphene::app::database_api::get_config() const: Retrieve compile-time constants.

get_chain_id 

chain_id_type graphene::app::database_api::get_chain_id() const: Get the chain ID.

get_dynamic_global_properties 

dynamic_global_property_object graphene::app::database_api::get_dynamic_global_properties() const: Retrieve the current graphene::chain::dynamic_global_property_object.

Keys 

get_key_references 

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

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

Parameters:: keys – a list of public keys to query, the quantity should not be greater than the configured value of api_limit_get_key_references
Returns:: ID of all accounts that refer to the specified keys

Accounts 

get_accounts 

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

Get a list of accounts by names or IDs.

This function has semantics identical to get_objects

Parameters:

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)

Returns:

The accounts corresponding to the provided names or IDs

get_full_accounts 

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

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

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

Note

The maximum number of accounts allowed to subscribe per connection is configured by the api_limit_get_full_accounts_subscribe option. Exceeded subscriptions will be ignored.

Note

For each object type, the maximum number of objects to return is configured by the api_limit_get_full_accounts_lists option. Exceeded objects need to be queried with other APIs.

Parameters:

names_or_ids – Each item must be the name or ID of an account to retrieve, the quantity should not be greater than the configured value of api_limit_get_full_accounts
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)

Returns:

Map of string from names_or_ids to the corresponding account

get_account_by_name 

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

Get info of an account by name.

Parameters:: name – Name of the account to retrieve
Returns:: The account holding the provided name

get_account_references 

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

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

Parameters:: account_name_or_id – Account name or ID to query
Returns:: all accounts that refer to the specified account in their owner or active authorities

lookup_account_names 

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

Get a list of accounts by name.

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

Parameters:: account_names – Names of the accounts to retrieve
Returns:: The accounts holding the provided names

lookup_accounts 

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

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.

Parameters:

lower_bound_name – Lower bound of the first name to return
limit – Maximum number of results to return, must not exceed the configured value of api_limit_lookup_accounts
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)

Returns:

Map of account names to corresponding IDs

get_account_count 

uint64_t graphene::app::database_api::get_account_count() const: Get the total number of accounts registered with the blockchain.

Balances 

get_account_balances 

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

Get an account’s balances in various assets.

Parameters:

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

Returns:

Balances of the account

get_named_account_balances 

vector<asset> graphene::app::database_api::get_named_account_balances(const std::string &name, const flat_set<asset_id_type> &assets) const: Semantically equivalent to get_account_balances.

get_balance_objects 

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

Return all unclaimed balance objects for a list of addresses.

Parameters:: addrs – a list of addresses
Returns:: all unclaimed balance objects for the addresses

get_vested_balances 

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

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

Parameters:: objs – a list of balance object IDs
Returns:: a list indicating how much asset in each balance object is available to be claimed

get_vesting_balances 

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

Return all vesting balance objects owned by an account.

Parameters:: account_name_or_id – name or ID of an account
Returns:: all vesting balance objects owned by the account

Assets 

get_assets 

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

Get a list of assets by symbol names or IDs.

This function has semantics identical to get_objects

Parameters:

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)

Returns:

The assets corresponding to the provided symbol names or IDs

list_assets 

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

Get assets alphabetically by symbol name.

Parameters:

lower_bound_symbol – Lower bound of symbol names to retrieve
limit – Maximum number of assets to fetch, must not exceed the configured value of api_limit_get_assets

Returns:

The assets found

lookup_asset_symbols 

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

Get a list of assets by symbol names or IDs.

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

Parameters:: symbols_or_ids – symbol names or IDs of the assets to retrieve
Returns:: The assets corresponding to the provided symbols or IDs

Markets / feeds 

get_order_book 

order_book graphene::app::database_api::get_order_book(const string &base, const string &quote, uint32_t limit = application_options::get_default().api_limit_get_order_book) const

Returns the order book for the market base:quote.

Parameters:

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 the configured value of api_limit_get_order_book and api_limit_get_limit_orders

Returns:

Order book of the market

get_limit_orders 

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

Get limit orders in a given market.

Parameters:

a – symbol or ID of asset being sold
b – symbol or ID of asset being purchased
limit – Maximum number of orders to retrieve, must not exceed the configured value of api_limit_get_limit_orders

Returns:

The limit orders, ordered from least price to greatest

get_call_orders 

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

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

Parameters:

a – symbol name or ID of the debt asset
limit – Maximum number of orders to retrieve, must not exceed the configured value of api_limit_get_call_orders

Returns:

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

get_settle_orders 

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

Get forced settlement orders in a given asset.

Parameters:

a – Symbol or ID of asset being settled
limit – Maximum number of orders to retrieve, must not exceed the configured value of api_limit_get_settle_orders

Returns:

The settle orders, ordered from earliest settlement date to latest

get_margin_positions 

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

Get open margin positions of a given account.

Similar to get_call_orders_by_account, but only the first page will be returned, the page size is the configured value of api_limit_get_call_orders.

Parameters:: account_name_or_id – name or ID of an account
Returns:: open margin positions of the account

unsubscribe_from_market 

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

Unsubscribe from updates to a given market.

Parameters:

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

get_ticker 

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

Returns the ticker for the market assetA:assetB.

Parameters:

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

Returns:

The market ticker for the past 24 hours.

get_24_volume 

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

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

Parameters:

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

Returns:

The market volume over the past 24 hours

get_trade_history 

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, uint32_t limit = application_options::get_default().api_limit_get_trade_history) const

Get market transactions occurred in the market base:quote, ordered by time, most recent first.

Note

The time must be UTC, timezone offsets are not supported. The range is [stop, start]. In case when there are more transactions than limit occurred in the same second, this API only returns the most recent records, the rest records can be retrieved with the get_trade_history_by_sequence API.

Parameters:

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 transactions to retrieve
stop – Stop time as a UNIX timestamp, the earliest transactions to retrieve
limit – Maximum quantity of transactions to retrieve, capped at the configured value of api_limit_get_trade_history

Returns:

Transactions in the market

Witnesses 

get_witnesses 

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

Get a list of witnesses by ID.

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

Parameters:: witness_ids – IDs of the witnesses to retrieve
Returns:: The witnesses corresponding to the provided IDs

get_witness_by_account 

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

Get the witness owned by a given account.

Parameters:: account_name_or_id – The name or ID of the account whose witness should be retrieved
Returns:: The witness object, or null if the account does not have a witness

lookup_witness_accounts 

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

Get names and IDs for registered witnesses.

Parameters:

lower_bound_name – Lower bound of the first name to return
limit – Maximum number of results to return, must not exceed the configured value of api_limit_lookup_witness_accounts

Returns:

Map of witness names to corresponding IDs

get_witness_count 

uint64_t graphene::app::database_api::get_witness_count() const: Get the total number of witnesses registered with the blockchain.

Committee members 

get_committee_members 

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

Get a list of committee_members by ID.

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

Parameters:: committee_member_ids – IDs of the committee_members to retrieve
Returns:: The committee_members corresponding to the provided IDs

get_committee_member_by_account 

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

Get the committee_member owned by a given account.

Parameters:: account_name_or_id – The name or ID of the account whose committee_member should be retrieved
Returns:: The committee_member object, or null if the account does not have a committee_member

lookup_committee_member_accounts 

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

Get names and IDs for registered committee_members.

Parameters:

lower_bound_name – Lower bound of the first name to return
limit – Maximum number of results to return, must not exceed the configured value of api_limit_lookup_committee_member_accounts

Returns:

Map of committee_member names to corresponding IDs

Workers 

get_workers_by_account 

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

Get the workers owned by a given account.

Parameters:: account_name_or_id – The name or ID of the account whose worker should be retrieved
Returns:: A list of worker objects owned by the account

Votes 

lookup_vote_ids 

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

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

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

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

Parameters:: votes – a list of vote IDs, the quantity should not be greater than the configured value of api_limit_lookup_vote_ids
Returns:: the referenced objects

Authority / Validation 

get_transaction_hex 

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

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

Parameters:: trx – a transaction to get hexdump from
Returns:: the hexdump of the transaction

get_required_signatures 

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

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.

Parameters:

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

Returns:

a subset of available_keys that could sign for the given transaction

get_potential_signatures 

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

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.

Parameters:: trx – the transaction to be signed
Returns:: a set of public keys that could possibly sign for the given transaction

get_potential_address_signatures 

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

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

Parameters:: trx – the transaction to be signed
Returns:: a set of addresses that could possibly sign for the given transaction

verify_authority 

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

Check whether a transaction has all of the required signatures

Parameters:: trx – a transaction to be verified
Returns:: true if the trx has all of the required signatures, otherwise throws an exception

verify_account_authority 

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

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

Parameters:

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

Returns:

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

validate_transaction 

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

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

Parameters:: trx – a transaction to be validated
Returns:: a processed_transaction object if the transaction passes the validation, otherwise an exception will be thrown

get_required_fees 

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

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

Parameters:

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

Returns:

a list of objects which indicates required fees of each operation

Proposed Transactions 

get_proposed_transactions 

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

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

Parameters:: account_name_or_id – The name or ID of an account
Returns:: a set of proposed transactions that the specified account can act on

Blinded balances 

get_blinded_balances 

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

return the set of blinded balance objects by commitment ID

Parameters:: commitments – a set of commitments to query for
Returns:: the set of blinded balance objects by commitment ID