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.

Return

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

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)



Subscriptions

set_subscribe_callback

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

Register a callback handle which then can be used to subscribe to object database changes.

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

set_auto_subscription API.
Parameters
  • 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

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.

Return

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

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.

get_block

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

Retrieve a full, signed block.

Return

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

Parameters
  • block_num: Height of the block to be returned

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.

Return

the transaction at the given position

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

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.

Return

the corresponding transaction if found, or null if not found

Parameters
  • txid: hash of the transaction



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.

Return

ID of all accounts that refer to the specified keys

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



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
Return

The accounts corresponding to the provided names or IDs

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)

get_full_accounts

std::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.
Return

Map of string from names_or_ids to the corresponding account

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)

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.

Return

The account holding the provided name

Parameters
  • name: Name of the account to retrieve

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.

Return

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

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.
Return

The accounts holding the provided names

Parameters
  • account_names: Names of the accounts to retrieve

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.

Return

Map of account names to corresponding IDs

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)

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.

Return

Balances of the account

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

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.

Return

all unclaimed balance objects for the addresses

Parameters
  • addrs: a list of 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.

Return

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

Parameters
  • objs: a list of balance object IDs

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.

Return

all vesting balance objects owned by the account

Parameters
  • account_name_or_id: name or ID of an 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
Return

The assets corresponding to the provided symbol names or IDs

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)

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.

Return

The assets found

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

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
Return

The assets corresponding to the provided symbols or IDs

Parameters
  • symbols_or_ids: symbol names or IDs of the assets to retrieve



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.

Return

Order book of the market

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

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.

Return

The limit orders, ordered from least price to greatest

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

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.

Return

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

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

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.

Return

The settle orders, ordered from earliest settlement date to latest

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

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.
Return

open margin positions of the account

Parameters
  • account_name_or_id: name or ID of an account

subscribe_to_market

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

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.

Parameters
  • 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

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.

Return

The market ticker for the past 24 hours.

Parameters
  • base: symbol name or ID of the base asset

  • quote: symbol name or ID of the quote asset

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.

Return

The market volume over the past 24 hours

Parameters
  • base: symbol name or ID of the base asset

  • quote: symbol name or ID of the quote asset

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.

Return

Transactions in the market

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



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
Return

The witnesses corresponding to the provided IDs

Parameters
  • witness_ids: IDs of the witnesses to retrieve

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.

Return

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

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

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.

Return

Map of witness names to corresponding IDs

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

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
Return

The committee_members corresponding to the provided IDs

Parameters
  • committee_member_ids: IDs of the committee_members to retrieve

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.

Return

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

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

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.

Return

Map of committee_member names to corresponding IDs

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



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.

Return

A list of worker objects owned by the account

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



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

Return

the referenced objects

Parameters
  • votes: a list of vote IDs, the quantity should not be greater than the configured value of api_limit_lookup_vote_ids

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

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.

Return

the hexdump of the transaction

Parameters
  • trx: a transaction to get hexdump from

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.

Return

a subset of available_keys that could sign for the given transaction

Parameters
  • trx: the transaction to be signed

  • available_keys: a set of public keys

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.

Return

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

Parameters
  • trx: the transaction to be signed

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.

Return

a set of addresses that could possibly sign for the given transaction

Parameters
  • trx: the transaction to be signed

verify_authority

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

Check whether a transaction has all of the required signatures

Return

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

Parameters
  • trx: a transaction to be verified

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.

Return

true if the passed in 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

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.

Return

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

Parameters
  • trx: a transaction to be validated

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.

Return

a list of objects which indicates required fees of each operation

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



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

Return

a set of proposed transactions that the specified account can act on

Parameters
  • account_name_or_id: The name or ID of an account



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

Return

the set of blinded balance objects by commitment ID

Parameters
  • commitments: a set of commitments to query for