Database API

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

Objects

get_objects

Get the objects corresponding to the provided IDs.

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

fc::variants graphene::app::database_api::get_objects(
    const vector<object_id_type> &ids, 
    optional<bool> subscribe = optional<bool>())const
  • ids: IDs of the objects to retrieve

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

Subscriptions

set_subscribe_callback

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

void graphene::app::database_api::set_subscribe_callback(
    std::function<void(const variant&)> cb, 
    bool notify_remove_create, )
  • cb: The callback handle to register

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

set_pending_transaction_callback

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

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

void graphene::app::database_api::set_pending_transaction_callback(
    std::function<void(const variant &signed_transaction_object)> cb)
  • cb: The callback handle to register

set_block_applied_callback

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

void graphene::app::database_api::set_block_applied_callback(
    std::function<void(const variant &block_id)> cb)
  • cb: The callback handle to register

cancel_all_subscriptions

Stop receiving any notifications.

This unsubscribes from all subscribed markets and objects.

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

Blocks and transactions

get_block_header

Retrieve a block header.

optional<block_header> graphene::app::database_api::get_block_header(
    uint32_t block_num)const
  • block_num: Height of the block whose header should be returned

get_block

Retrieve a full, signed block.

optional<signed_block> graphene::app::database_api::get_block(
    uint32_t block_num)const
  • block_num: Height of the block to be returned

get_transaction

Fetch an individual transaction.

processed_transaction graphene::app::database_api::get_transaction(
    uint32_t block_num, uint32_t trx_in_block)const
  • block_num: height of the block to fetch

  • trx_in_block: the index (sequence number) of the transaction in the block, starts from 0

get_recent_transaction_by_id

optional<signed_transaction> graphene::app::database_api::get_recent_transaction_by_id(
    const transaction_id_type &txid)const
  • txid: hash of the transaction

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

Globals

get_chain_properties

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

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

get_global_properties

Retrieve the current graphene::chain::global_property_object.

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

get_config

Retrieve compile-time constants.

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

get_chain_id

Get the chain ID.

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

get_dynamic_global_properties

Retrieve the current graphene::chain::dynamic_global_property_object.

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

Keys

get_key_references

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

vector<flat_set<account_id_type>> graphene::app::database_api::get_key_references(
    vector<public_key_type> keys)const
  • keys: a list of public keys to query

Accounts

get_accounts

Get a list of accounts by names or IDs.

This function has semantics identical to get_objects****

vector<optional<account_object>> graphene::app::database_api::get_accounts(
    const vector<std::string> &account_names_or_ids, 
    optional<bool> subscribe = optional<bool>())const
  • account_names_or_ids: names or IDs of the accounts to retrieve

  • subscribe: true to subscribe to the queried account objects; false to not subscribe; null to subscribe or not subscribe according to current auto-subscription setting (see set_auto_subscription)

get_full_accounts

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

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

std::map<string, full_account> graphene::app::database_api::get_full_accounts(
    const vector<string> &names_or_ids, 
    optional<bool> subscribe = optional<bool>())
  • names_or_ids: Each item must be the name or ID of an account to retrieve

  • subscribe: true to subscribe to the queried full account objects; false to not subscribe; null to subscribe or not subscribe according to current auto-subscription setting (see set_auto_subscription)

get_account_by_name

Get info of an account by name.

optional<account_object> graphene::app::database_api::get_account_by_name(
    string name)const
  • name: Name of the account to retrieve

get_account_references

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

vector<account_id_type> graphene::app::database_api::get_account_references(
    const std::string account_name_or_id)const
  • account_name_or_id: Account name or ID to query

lookup_account_names

Get a list of accounts by name.

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

vector<optional<account_object>> graphene::app::database_api::lookup_account_names(
    const vector<string> &account_names)const
  • account_names: Names of the accounts to retrieve

lookup_accounts

Get names and IDs for registered accounts.

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

map<string, account_id_type> graphene::app::database_api::lookup_accounts(
    const string &lower_bound_name, 
    uint32_t limit, 
    optional<bool> subscribe = optional<bool>())const
  • lower_bound_name: Lower bound of the first name to return

  • limit: Maximum number of results to return must not exceed 1000

  • subscribe: true to subscribe to the queried account objects; false to not subscribe; null to subscribe or not subscribe according to current auto-subscription setting (see set_auto_subscription).

get_account_count

Get the total number of accounts registered with the blockchain.

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

Balances

get_account_balances

Get an account’s balances in various assets.

vector<asset> graphene::app::database_api::get_account_balances(
    const std::string &account_name_or_id, 
    const flat_set<asset_id_type> &assets)const
  • account_name_or_id: name or ID of the account to get balances for.

  • assets: IDs of the assets to get balances of; if empty, get all assets account has a balance in.

get_named_account_balances

Semantically equivalent to get_account_balances.

vector<asset> graphene::app::database_api::get_named_account_balances(
    const std::string &name, 
    const flat_set<asset_id_type> &assets)const
  • account_name_or_id: name or ID of the account to get balances for.

  • assets: IDs of the assets to get balances of; if empty, get all assets account has a balance in.

get_balance_objects

vector<balance_object> graphene::app::database_api::get_balance_objects(
    const vector<address> &addrs)const
  • addrs: a list of addresses

get_vested_balances

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

vector<asset> graphene::app::database_api::get_vested_balances(
    const vector<balance_id_type> &objs)const
  • objs: a list of balance object IDs

get_vesting_balances

Return all vesting balance objects owned by an account.

vector<vesting_balance_object> graphene::app::database_api::get_vesting_balances(
    const std::string account_name_or_id)const
  • account_name_or_id: name or ID of an account

Assets

get_assets

Get a list of assets by symbol names or IDs.

Semantically equivalent to get_objects.

vector<optional<extended_asset_object>> graphene::app::database_api::get_assets(
    const vector<std::string> &asset_symbols_or_ids, 
    optional<bool> subscribe = optional<bool>())const
  • asset_symbols_or_ids: symbol names or IDs of the assets to retrieve

  • subscribe: true to subscribe to the queried asset objects; false to not subscribe; null to subscribe or not subscribe according to current auto-subscription setting (see set_auto_subscription)

list_assets

Get assets alphabetically by symbol name.

vector<extended_asset_object> graphene::app::database_api::list_assets(
    const string &lower_bound_symbol, 
    uint32_t limit)const
  • lower_bound_symbol: Lower bound of symbol names to retrieve

  • limit: Maximum number of assets to fetch (must not exceed 101)

lookup_asset_symbols

Get a list of assets by symbol names or IDs.

Semantically equivalent to get_objects, but doesn’t subscribe.

vector<optional<extended_asset_object>> graphene::app::database_api::lookup_asset_symbols(
    const vector<string> &symbols_or_ids)const
  • symbols_or_ids: symbol names or IDs of the assets to retrieve

Markets / Feeds

get_order_book

Returns the order book for the market base

order_book graphene::app::database_api::get_order_book(
    const string &base, 
    const string &quote, 
    unsigned limit = 50)const
  • base: symbol name or ID of the base asset

  • quote: symbol name or ID of the quote asset

  • limit: depth of the order book to retrieve, for bids and asks each, capped at 50

get_limit_orders

Get limit orders in a given market.

vector<limit_order_object> graphene::app::database_api::get_limit_orders(
    std::string a, 
    std::string b, 
    uint32_t limit)const
  • a: symbol or ID of asset being sold

  • b: symbol or ID of asset being purchased

  • limit: Maximum number of orders to retrieve

get_call_orders

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

vector<call_order_object> graphene::app::database_api::get_call_orders(
    const std::string &a, 
    uint32_t limit)const
  • a: symbol name or ID of the debt asset

  • limit: Maximum number of orders to retrieve

get_settle_orders

Get forced settlement orders in a given asset.

vector<force_settlement_object> graphene::app::database_api::get_settle_orders(
    const std::string &a, 
    uint32_t limit)const
  • a: Symbol or ID of asset being settled

  • limit: Maximum number of orders to retrieve

get_margin_positions

Get all open margin positions of a given account.

Similar to get_call_orders_by_account, but without pagination.

vector<call_order_object> graphene::app::database_api::get_margin_positions(
    const std::string account_name_or_id)const
  • account_name_or_id: name or ID of an account

subscribe_to_market

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

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

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

void graphene::app::database_api::subscribe_to_market(std::function<void(
    const variant&)> callback, 
    const std::string &a, 
    const std::string &b, )
  • callback: Callback method which is called when the market changes

  • a: symbol name or ID of the first asset

  • b: symbol name or ID of the second asset

unsubscribe_from_market

Unsubscribe from updates to a given market.

void graphene::app::database_api::unsubscribe_from_market(
    const std::string &a, 
    const std::string &b)
  • a: symbol name or ID of the first asset

  • b: symbol name or ID of the second asset

get_ticker

Returns the ticker for the market assetA:assetB.

market_ticker graphene::app::database_api::get_ticker(
    const string &base, 
    const string &quote)const
  • base: symbol name or ID of the base asset

  • quote: symbol name or ID of the quote asset

get_24_volume

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

market_volume graphene::app::database_api::get_24_volume(
    const string &base, 
    const string &quote)const
  • base: symbol name or ID of the base asset

  • quote: symbol name or ID of the quote asset

get_trade_history

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

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

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

vector<market_trade> graphene::app::database_api::get_trade_history(
    const string &base, 
    const string &quote, 
    fc::time_point_sec start, 
    fc::time_point_sec stop, 
    unsigned limit = 100)const
  • base: symbol or ID of the base asset

  • quote: symbol or ID of the quote asset

  • start: Start time as a UNIX timestamp, the latest trade to retrieve

  • stop: Stop time as a UNIX timestamp, the earliest trade to retrieve

  • limit: Number of transactions to retrieve, capped at 100.

Witnesses

get_witnesses

Get a list of witnesses by ID.

Semantically equivalent to get_objects, but doesn’t subscribe.

vector<optional<witness_object>> graphene::app::database_api::get_witnesses(
    const vector<witness_id_type> &witness_ids)const
  • witness_ids: IDs of the witnesses to retrieve

get_witness_by_account

Get the witness owned by a given account.

fc::optional<witness_object> graphene::app::database_api::get_witness_by_account(
    const std::string account_name_or_id)const
  • account_name_or_id: The name or ID of the account whose witness should be retrieved

lookup_witness_accounts

Get names and IDs for registered witnesses.

map<string, witness_id_type> graphene::app::database_api::lookup_witness_accounts(
    const string &lower_bound_name, uint32_t limit)const
  • lower_bound_name: Lower bound of the first name to return

  • limit: Maximum number of results to return must not exceed 1000

get_witness_count

Get the total number of witnesses registered with the blockchain.

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

Committee members

get_committee_members

Get a list of committee_members by ID.

Semantically equivalent to get_objects, but doesn’t subscribe.

vector<optional<committee_member_object>> graphene::app::database_api::get_committee_members(
    const vector<committee_member_id_type> &committee_member_ids)const
  • committee_member_ids: IDs of the committee_members to retrieve

get_committee_member_by_account

Get the committee_member owned by a given account.

fc::optional<committee_member_object> graphene::app::database_api::get_committee_member_by_account(
    const string account_name_or_id)const
  • account_name_or_id: The name or ID of the account whose committee_member should be retrieved

lookup_committee_member_accounts

Get names and IDs for registered committee_members.

map<string, committee_member_id_type> graphene::app::database_api::lookup_committee_member_accounts(
    const string &lower_bound_name, 
    uint32_t limit)const
  • lower_bound_name: Lower bound of the first name to return

  • limit: Maximum number of results to return must not exceed 1000

Workers

get_workers_by_account

Get the workers owned by a given account.

vector<optional<worker_object>> graphene::app::database_api::get_workers_by_account(
    const std::string account_name_or_id)const
  • account_name_or_id: The name or ID of the account whose worker should be retrieved

Votes

lookup_vote_ids

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

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

vector<variant> graphene::app::database_api::lookup_vote_ids(
    const vector<vote_id_type> &votes)const
  • votes: a list of vote IDs

Authority / Validation

get_transaction_hex

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

std::string graphene::app::database_api::get_transaction_hex(
    const signed_transaction &trx)const
  • trx: a transaction to get hexdump from

get_required_signatures

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

set<public_key_type> graphene::app::database_api::get_required_signatures(
    const signed_transaction &trx, 
    const flat_set<public_key_type> &available_keys)const
  • trx: the transaction to be signed

  • available_keys: a set of public keys

get_potential_signatures

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

set<public_key_type> graphene::app::database_api::get_potential_signatures(
    const signed_transaction &trx)const
  • trx: the transaction to be signed

get_potential_address_signatures

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

set<address> graphene::app::database_api::get_potential_address_signatures(
    const signed_transaction &trx)const
  • trx: the transaction to be signed

verify_authority

Check whether a transaction has all of the required signatures

bool graphene::app::database_api::verify_authority(
    const signed_transaction &trx)const
  • trx: a transaction to be verified

verify_account_authority

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

bool graphene::app::database_api::verify_account_authority(
    const string &account_name_or_id, 
    const flat_set<public_key_type> &signers)const
  • account_name_or_id: name or ID of an account to check

  • signers: the public keys

validate_transaction

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

processed_transaction graphene::app::database_api::validate_transaction(
const signed_transaction &trx)const
  • trx: a transaction to be validated

get_required_fees

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

vector<fc::variant> graphene::app::database_api::get_required_fees(
    const vector<operation> &ops, 
    const std::string &asset_symbol_or_id)const
  • ops: a list of operations to be query for required fees

  • asset_symbol_or_id: symbol name or ID of an asset that to be used to pay the fees

Proposed Transactions

get_proposed_transactions

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

vector<proposal_object> graphene::app::database_api::get_proposed_transactions(
    const std::string account_name_or_id)const
  • account_name_or_id: The name or ID of an account

Blinded balances

get_blinded_balances

Gets the set of blinded balance objects by commitment ID.

vector<blinded_balance_object> graphene::app::database_api::get_blinded_balances(
    const flat_set<commitment_type> &commitments)const
  • commitments: a set of commitments to query for

Last updated