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.
Table of Contents
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_transaction_history_object (2.9.x) can not be subscribed.
- Parameters
ids
: IDs of the objects to retrievesubscribe
: 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 registernotify_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<block_header>
graphene::app::database_api
::
get_block_header
(uint32_t block_num) 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
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 fetchtrx_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
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 retrievesubscribe
: 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>
graphene::app::database_api
::
get_full_accounts
(const vector<string> &names_or_ids, optional<bool> subscribe = optional<bool>())¶ 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 in
names_or_ids
cannot be tied to an account, that input will be ignored. All other accounts will be retrieved and subscribed.- Return
Map of string from
names_or_ids
to the corresponding account- Parameters
names_or_ids
: Each item must be the name or ID of an account to retrievesubscribe
: 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>
graphene::app::database_api
::
lookup_accounts
(const string &lower_bound_name, uint32_t limit, 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 returnlimit
: Maximum number of results to return must not exceed 1000subscribe
: 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 forassets
: 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 retrievesubscribe
: 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 retrievelimit
: Maximum number of assets to fetch (must not exceed 101)
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 "e, unsigned limit = 50) 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 assetquote
: symbol name or ID of the quote assetlimit
: depth of the order book to retrieve, for bids and asks each, capped at 50
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 soldb
: symbol or ID of asset being purchasedlimit
: Maximum number of orders to retrieve
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 assetlimit
: Maximum number of orders to retrieve
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 settledlimit
: Maximum number of orders to retrieve
get_margin_positions¶
-
vector<call_order_object>
graphene::app::database_api
::
get_margin_positions
(const std::string account_name_or_id) const¶ Get all open margin positions of a given account.
Similar to
get_call_orders_by_account, but without pagination.- Return
all 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 changesa
: symbol name or ID of the first assetb
: 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 assetb
: symbol name or ID of the second asset
get_ticker¶
-
market_ticker
graphene::app::database_api
::
get_ticker
(const string &base, const string "e) 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 assetquote
: 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 "e) 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 assetquote
: 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 "e, fc::time_point_sec start, fc::time_point_sec stop, unsigned limit = 100) const¶ 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 when there are more than 100 trades occurred in the same second, this API only returns the first 100 records, can use another API get_trade_history_by_sequence to query for the rest.
- Return
Recent transactions in the market
- Parameters
base
: symbol or ID of the base assetquote
: symbol or ID of the quote assetstart
: Start time as a UNIX timestamp, the latest trade to retrievestop
: Stop time as a UNIX timestamp, the earliest trade to retrievelimit
: Number of trasactions to retrieve, capped at 100.
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>
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 returnlimit
: Maximum number of results to return must not exceed 1000
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>
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 returnlimit
: Maximum number of results to return must not exceed 1000
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 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 signedavailable_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¶
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¶
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 checksigners
: 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 feesasset_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