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


4.1.1. Objects

4.1.1.1. get_objects

fc::variants graphene::app::database_api::get_objects(const vector<object_id_type> &ids) 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
Parameters
  • ids: IDs of the objects to retrieve



4.1.2. Subscriptions

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

Parameters
  • cb: The callback handle to register
  • nofity_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.

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

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

4.1.2.4. cancel_all_subscriptions

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

Stop receiving any notifications.

This unsubscribes from all subscribed markets and objects.



4.1.3. Blocks and transactions

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

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

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

4.1.3.4. get_recent_transaction_by_id

optional<signed_transaction> graphene::app::database_api::get_recent_transaction_by_id(const transaction_id_type &id) 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.



4.1.4. Globals

4.1.4.1. get_chain_properties

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

Retrieve the chain_property_object associated with the chain.

4.1.4.2. get_global_properties

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

Retrieve the current global_property_object.

4.1.4.3. get_config

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

Retrieve compile-time constants.

4.1.4.4. get_chain_id

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

Get the chain ID.

4.1.4.5. get_dynamic_global_properties

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

Retrieve the current dynamic_global_property_object.



4.1.5. Keys

4.1.5.1. get_key_references

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


4.1.6. Accounts

4.1.6.1. get_accounts

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

Get a list of accounts by ID.

This function has semantics identical to

get_objects
Return
The accounts corresponding to the provided IDs
Parameters
  • account_names_or_ids: IDs or names of the accounts to retrieve

4.1.6.2. get_full_accounts

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

Fetch all objects relevant to the specified accounts and 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
  • callback: Function to call with updates
  • names_or_ids: Each item must be the name or ID of an account to retrieve

4.1.6.3. get_account_by_name

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

4.1.6.4. get_account_references

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

Return
all accounts that referr to the key or account id in their owner or active authorities.

4.1.6.5. 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
Return
The accounts holding the provided names
Parameters
  • account_names: Names of the accounts to retrieve

4.1.6.6. lookup_accounts

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

Get names and IDs for registered accounts.

Return
Map of account 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 1000

4.1.6.7. get_account_count

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

Get the total number of accounts registered with the blockchain.



4.1.7. Balances

4.1.7.1. 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: ID or name 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

4.1.7.2. 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, but takes a name instead of an ID.

4.1.7.3. 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 set of addresses

4.1.7.4. get_vested_balances

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

4.1.7.5. get_vesting_balances

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


4.1.8. Assets

4.1.8.1. get_assets

vector<optional<asset_object>> graphene::app::database_api::get_assets(const vector<asset_id_type> &asset_ids) const

Get a list of assets by ID.

This function has semantics identical to

get_objects
Return
The assets corresponding to the provided IDs
Parameters
  • asset_ids: IDs of the assets to retrieve

4.1.8.2. list_assets

vector<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 101)

4.1.8.3. lookup_asset_symbols

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

Get a list of assets by symbol.

This function has semantics identical to

get_objects
Return
The assets corresponding to the provided symbols or IDs
Parameters
  • asset_symbols: Symbols or stringified IDs of the assets to retrieve



4.1.9. Markets / feeds

4.1.9.1. get_order_book

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

Returns the order book for the market base:quote.

Return
Order book of the market
Parameters
  • base: String name of the first asset
  • quote: String name of the second asset
  • depth: of the order book. Up to depth of each asks and bids, capped at 50. Prioritizes most moderate of each

4.1.9.2. get_limit_orders

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

Get limit orders in a given market.

Return
The limit orders, ordered from least price to greatest
Parameters
  • a: ID of asset being sold
  • b: ID of asset being purchased
  • limit: Maximum number of orders to retrieve

4.1.9.3. get_call_orders

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

Get call orders in a given asset.

Return
The call orders, ordered from earliest to be called to latest
Parameters
  • a: ID of asset being called
  • limit: Maximum number of orders to retrieve

4.1.9.4. get_settle_orders

vector<force_settlement_object> graphene::app::database_api::get_settle_orders(asset_id_type 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: ID of asset being settled
  • limit: Maximum number of orders to retrieve

4.1.9.5. get_margin_positions

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

Return
all open margin positions for a given account id or name.

4.1.9.6. subscribe_to_market

void graphene::app::database_api::subscribe_to_market(std::function<void(const variant&)> callback, asset_id_type a, asset_id_type 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: First asset ID
  • b: Second asset ID

4.1.9.7. unsubscribe_from_market

void graphene::app::database_api::unsubscribe_from_market(asset_id_type a, asset_id_type b)

Unsubscribe from updates to a given market.

Parameters
  • a: First asset ID
  • b: Second asset ID

4.1.9.8. 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
  • a: String name of the first asset
  • b: String name of the second asset

4.1.9.9. 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
  • a: String name of the first asset
  • b: String name of the second asset

4.1.9.10. 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, 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 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 trasactions to retrieve, capped at 100.



4.1.10. Witnesses

4.1.10.1. 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
Return
The witnesses corresponding to the provided IDs
Parameters
  • witness_ids: IDs of the witnesses to retrieve

4.1.10.2. get_witness_by_account

fc::optional<witness_object> graphene::app::database_api::get_witness_by_account(const std::string account_id_or_name) 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_id_or_name: The ID of the account whose witness should be retrieved

4.1.10.3. 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 return
  • limit: Maximum number of results to return must not exceed 1000

4.1.10.4. get_witness_count

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

Get the total number of witnesses registered with the blockchain.



4.1.11. Committee members

4.1.11.1. 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
Return
The committee_members corresponding to the provided IDs
Parameters
  • committee_member_ids: IDs of the committee_members to retrieve

4.1.11.2. get_committee_member_by_account

fc::optional<committee_member_object> graphene::app::database_api::get_committee_member_by_account(const std::string account_id_or_name) 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: The ID or name of the account whose committee_member should be retrieved

4.1.11.3. 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 return
  • limit: Maximum number of results to return must not exceed 1000



4.1.12. Workers

4.1.12.1. get_workers_by_account

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

Get the workers owned by a given account.

Return
The worker object, or null if the account does not have a worker
Parameters
  • account_id_or_name: The ID or name of the account whose worker should be retrieved



4.1.13. Votes

4.1.13.1. 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_object, 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.



4.1.14. Authority / Validation

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

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

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

4.1.14.4. get_potential_address_signatures

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

4.1.14.5. verify_authority

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

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

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

Return
true if the signers have enough authority to authorize an account

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

4.1.14.8. get_required_fees

vector<fc::variant> graphene::app::database_api::get_required_fees(const vector<operation> &ops, asset_id_type id) const

For each operation calculate the required fee in the specified asset type. If the asset type does not have a valid core_exchange_rate



4.1.15. Proposed Transactions

4.1.15.1. get_proposed_transactions

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

Return
the set of proposed transactions relevant to the specified account id.



4.1.16. Blinded balances

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