Gdk Functions

int GA_init(const GA_json* config)

Set the global configuration and run one-time initialization code. This function must be called once and only once before calling any other functions. When used in a multi-threaded context this function should be called before starting any other threads that call other gdk functions.

Parameters:
Returns:

GA_OK or an error code.

Return type:

int

int GA_create_session(struct GA_session** session)

Create a new session.

Parameters:
  • session – Destination for the resulting session. Returned session should be freed using GA_destroy_session.
Returns:

GA_OK or an error code.

Return type:

int

int GA_destroy_session(struct GA_session* session)

Free a session allocated by GA_create_session.

Parameters:
  • session – Session to free.
Returns:

GA_OK or an error code.

Return type:

int

int GA_connect(struct GA_session* session, const GA_json* net_params)

Connect to a remote server using the specified network.

Parameters:
Returns:

GA_OK or an error code.

Return type:

int

int GA_disconnect(struct GA_session* session)

Disconnect from a connected remote server.

Parameters:
  • session – The session to use.
Returns:

GA_OK or an error code.

Return type:

int

int GA_reconnect_hint(struct GA_session* session, const GA_json* hint)

Configure networking behaviour when reconnecting.

Parameters:
Returns:

GA_OK or an error code.

Return type:

int

int GA_get_tor_socks5(struct GA_session* session, char** socks5)

Get the current SOCKS5 url for the embedded Tor daemon, if any.

Parameters:
  • session – The session to use.
  • socks5 – Destination for the SOCKS5 url (host:port). Empty string if not set. Returned string should be freed using GA_destroy_string.
Returns:

GA_OK or an error code.

Return type:

int

int GA_check_proxy_connectivity(const GA_json* params)

Check if server can be reached via the proxy.

Parameters:
Returns:

GA_OK or an error code.

Return type:

int

int GA_http_get(struct GA_session* session, const GA_json* params, GA_json** output)

Get JSON data from an https server.

Parameters:
  • session – The session to use.
  • params – the HTTP params JSON of the server to connect to.
  • output – Destination for the output JSON. Returned GA_json should be freed using GA_destroy_json.
Returns:

GA_OK or an error code.

Return type:

int

int GA_refresh_assets(struct GA_session* session, const GA_json* params, GA_json** output)

Refresh the internal cache asset information.

Parameters:
  • session – The session to use.
  • params – the Assets params JSON of the server to connect to.
  • output – Destination for the assets JSON. Returned GA_json should be freed using GA_destroy_json.
Returns:

GA_OK or an error code.

Return type:

int

int GA_validate_asset_domain_name(struct GA_session* session, const GA_json* params, GA_json** output)

Validate asset domain name. (This is a interface stub)

Returns:GA_OK or an error code.
Return type:int
int GA_register_user(struct GA_session* session, const GA_json* hw_device, const char* mnemonic, struct GA_auth_handler** call)

Create a new user account using a hardware wallet/HSM/TPM.

Parameters:
  • session – The session to use.
  • hw_device – Details about the HW device JSON being used to register.
  • mnemonic – The user’s mnemonic passphrase.
  • call – Destination for the resulting GA_auth_handler to perform the registration. Returned GA_auth_handler should be freed using GA_destroy_auth_handler.
Returns:

GA_OK or an error code.

Return type:

int

int GA_login(struct GA_session* session, const GA_json* hw_device, const char* mnemonic, const char* password, struct GA_auth_handler** call)

Authenticate a user using a hardware wallet/HSM/TPM.

Parameters:
  • session – The session to use.
  • hw_device – Details about the HW device JSON being used to login.
  • mnemonic – The user’s mnemonic passphrase.
  • password – The user’s password to decrypt a 27 word mnemonic, or a blank string if none.
  • call – Destination for the resulting GA_auth_handler to perform the login. Returned GA_auth_handler should be freed using GA_destroy_auth_handler.
Returns:

GA_OK or an error code.

Return type:

int

int GA_login_with_pin(struct GA_session* session, const char* pin, const GA_json* pin_data)

Authenticate a user.

Parameters:
Returns:

GA_OK or an error code.

Return type:

int

int GA_set_watch_only(struct GA_session* session, const char* username, const char* password)

Set a watch-only login for the wallet.

Parameters:
  • session – The session to use.
  • username – The username.
  • password – The password.
Returns:

GA_OK or an error code.

Return type:

int

int GA_get_watch_only_username(struct GA_session* session, char** username)

Get the current watch-only login for the wallet, if any.

Parameters:
  • session – The session to use.
  • username – Destination for the watch-only username. Empty string if not set. Returned string should be freed using GA_destroy_string.
Returns:

GA_OK or an error code.

Return type:

int

int GA_login_watch_only(struct GA_session* session, const char* username, const char* password)

Authenticate a user in watch only mode.

Parameters:
  • session – The session to use.
  • username – The username.
  • password – The password.
Returns:

GA_OK or an error code.

Return type:

int

int GA_remove_account(struct GA_session* session, struct GA_auth_handler** call)

Remove an account.

Parameters:
  • session – The session to use.
  • call – Destination for the resulting GA_auth_handler to perform the removal. Returned GA_auth_handler should be freed using GA_destroy_auth_handler.
Returns:

GA_OK or an error code.

Return type:

int

int GA_create_subaccount(struct GA_session* session, const GA_json* details, struct GA_auth_handler** call)

Create a subaccount.

Parameters:
  • session – The session to use.
  • details – The Subaccount detail JSON. “name” (which must not be already used in the wallet) and “type” (either “2of2” or “2of3”) must be populated. For type “2of3” the caller may provide either “recovery_mnemonic” or “recovery_xpub” if they do not wish to have a mnemonic passphrase generated automatically. All other fields are ignored.
  • subaccount – Destination for the created subaccount details. For 2of3 subaccounts the field “recovery_xpub” will be populated, and “recovery_mnemonic” will contain the recovery mnemonic passphrase if one was generated. These values should be stored safely by the caller as they will not be returned again by any GDK call such as GA_get_subaccounts.
  • call – Destination for the resulting GA_auth_handler to perform the creation. Returned GA_auth_handler should be freed using GA_destroy_auth_handler.
Returns:

GA_OK or an error code.

Return type:

int

int GA_get_subaccounts(struct GA_session* session, struct GA_auth_handler** call)

Get the user’s subaccount details.

Parameters:
  • session – The session to use.
  • call – Destination for the resulting GA_auth_handler to perform the creation. Returned GA_auth_handler should be freed using GA_destroy_auth_handler.
Returns:

GA_OK or an error code.

Return type:

int

int GA_get_subaccount(struct GA_session* session, uint32_t subaccount, struct GA_auth_handler** call)

Get subaccount details.

Parameters:
  • session – The session to use.
  • subaccount – The value of “pointer” from Subaccounts list JSON for the subaccount.
  • call – Destination for the resulting GA_auth_handler to perform the creation. Returned GA_auth_handler should be freed using GA_destroy_auth_handler.
Returns:

GA_OK or an error code.

Return type:

int

int GA_rename_subaccount(struct GA_session* session, uint32_t subaccount, const char* new_name)

Rename a subaccount.

Parameters:
  • session – The session to use.
  • subaccount – The value of “pointer” from Subaccounts list JSON or Subaccount JSON for the subaccount to rename.
  • new_name – New name for the subaccount.
Returns:

GA_OK or an error code.

Return type:

int

int GA_get_transactions(struct GA_session* session, const GA_json* details, struct GA_auth_handler** call)

Get a page of the user’s transaction history.

Parameters:
  • session – The session to use.
  • detailsTransactions Details JSON giving the details to get the transactions for.
  • call – Destination for the resulting GA_auth_handler to complete the action. Returned GA_auth_handler should be freed using GA_destroy_auth_handler.

Note

Transactions are returned from newest to oldest with up to 30 transactions per page.

Returns:GA_OK or an error code.
Return type:int
int GA_get_receive_address(struct GA_session* session, const GA_json* details, struct GA_auth_handler** call)

Get a new address to receive coins to.

Parameters:
Returns:

GA_OK or an error code.

Return type:

int

int GA_get_unspent_outputs(struct GA_session* session, const GA_json* details, struct GA_auth_handler** call)

Get the user’s unspent transaction outputs.

Parameters:
  • session – The session to use.
  • detailsUtxos details JSON to get the unspent transaction outputs for.
  • call – Destination for the resulting GA_auth_handler to complete the action. Returned GA_auth_handler should be freed using GA_destroy_auth_handler.
Returns:

GA_OK or an error code.

Return type:

int

int GA_get_unspent_outputs_for_private_key(struct GA_session* session, const char* private_key, const char* password, uint32_t unused, GA_json** utxos)

Get the unspent transaction outputs associated with a non-wallet private key.

Parameters:
  • session – The session to use.
  • key – The private key in WIF or BIP 38 format.
  • password – The password the key is encrypted with, if any.
  • unused – unused, must be 0
  • utxos – Destination for the returned utxos (same format as Transactions list JSON). Returned GA_json should be freed using GA_destroy_json.

Note

Neither the private key or its derived public key are transmitted.

Returns:GA_OK or an error code.
Return type:int
int GA_get_transaction_details(struct GA_session* session, const char* txhash_hex, GA_json** transaction)

Get a transaction’s details.

Parameters:
  • session – The session to use.
  • txhash_hex – The transaction hash of the transaction to fetch.
  • transaction – Destination for the Transaction details JSON. Returned GA_json should be freed using GA_destroy_json.
Returns:

GA_OK or an error code.

Return type:

int

int GA_get_balance(struct GA_session* session, const GA_json* details, struct GA_auth_handler** call)

The sum of unspent outputs destined to user’s wallet.

Parameters:
  • session – The session to use.
  • detailsBalance Details JSON giving the subaccount details to get the balance for.
  • call – Destination for the resulting GA_auth_handler to complete the action. Returned GA_auth_handler should be freed using GA_destroy_auth_handler.
Returns:

GA_OK or an error code.

Return type:

int

int GA_get_available_currencies(struct GA_session* session, GA_json** currencies)

The list of allowed currencies for all available pricing sources.

Parameters:
Returns:

GA_OK or an error code.

Return type:

int

int GA_convert_amount(struct GA_session* session, const GA_json* value_details, GA_json** output)

Convert Fiat to BTC and vice-versa.

Parameters:
Returns:

GA_OK or an error code.

Return type:

int

int GA_set_pin(struct GA_session* session, const char* mnemonic, const char* pin, const char* device_id, GA_json** pin_data)

Set a PIN for the user wallet.

Parameters:
  • session – The session to use.
  • mnemonic – The user’s mnemonic passphrase.
  • pin – The user PIN.
  • device_id – The user device identifier.
  • pin_data – The returned PIN data JSON containing the user’s encrypted mnemonic passphrase. Returned GA_json should be freed using GA_destroy_json.
Returns:

GA_OK or an error code.

Return type:

int

int GA_disable_all_pin_logins(struct GA_session* session)

Disable all PIN logins previously set. After calling this method, user will not be able to login with PIN from any device he previously paired. :return: GA_OK or an error code. :rtype: int

int GA_create_transaction(struct GA_session* session, const GA_json* transaction_details, struct GA_auth_handler** call)

Construct a transaction.

Parameters:
  • session – The session to use.
  • transaction_details – The Create Transaction JSON for constructing.
  • call – Destination for the resulting GA_auth_handler to complete the action. Returned GA_auth_handler should be freed using GA_destroy_auth_handler.
Returns:

GA_OK or an error code.

Return type:

int

int GA_sign_transaction(struct GA_session* session, const GA_json* transaction_details, struct GA_auth_handler** call)

Sign the user’s inputs to a transaction.

Parameters:
  • session – The session to use.
  • transaction_details – The Sign Transaction JSON for signing, previously returned from GA_create_transaction.
  • call – Destination for the resulting GA_auth_handler to perform the signing. Returned GA_auth_handler should be freed using GA_destroy_auth_handler.
Returns:

GA_OK or an error code.

Return type:

int

int GA_broadcast_transaction(struct GA_session* session, const char* transaction_hex, char** tx_hash)

Broadcast a non-Green signed transaction to the P2P network.

Parameters:
  • session – The session to use.
  • transaction_hex – The signed transaction in hex to broadcast.
  • tx_hash – Destination for the resulting transactions hash. Returned string should be freed using GA_destroy_string.
Returns:

GA_OK or an error code.

Return type:

int

int GA_send_transaction(struct GA_session* session, const GA_json* transaction_details, struct GA_auth_handler** call)

Send a transaction created by GA_create_transaction and signed by GA_sign_transaction.

Parameters:
  • session – The session to use.
  • transaction_details – The Send Transaction JSON for sending.
  • call – Destination for the resulting GA_auth_handler to perform the send. Returned GA_auth_handler should be freed using GA_destroy_auth_handler.
Returns:

GA_OK or an error code.

Return type:

int

int GA_send_nlocktimes(struct GA_session* session)

Request an email containing the user’s nLockTime transactions.

Parameters:
  • session – The session to use.
Returns:

GA_OK or an error code.

Return type:

int

int GA_get_expired_deposits(struct GA_session* session, const GA_json* deposit_details, struct GA_auth_handler** call)

Return UTXOs that can be spent/or are spendable without two factor authentication after a block value.

Parameters:
  • session – The session to use.
  • deposit_details – The Deposit Details JSON for sending.
  • call – Destination for the resulting GA_auth_handler to change the locktime. Returned GA_auth_handler should be freed using GA_destroy_auth_handler.
Returns:

GA_OK or an error code.

Return type:

int

int GA_set_csvtime(struct GA_session* session, const GA_json* locktime_details, struct GA_auth_handler** call)

Set the number of blocks after which CSV transactions become spendable without two factor authentication.

Parameters:
  • session – The session to use.
  • locktime_details – The Locktime Details JSON for setting the block value.
  • call – Destination for the resulting GA_auth_handler to change the locktime. Returned GA_auth_handler should be freed using GA_destroy_auth_handler.
Returns:

GA_OK or an error code.

Return type:

int

int GA_set_nlocktime(struct GA_session* session, const GA_json* locktime_details, struct GA_auth_handler** call)

Set the number of blocks after which nLockTime transactions become spendable without two factor authentication. When this function succeeds, if the user has an email address associated with the wallet, an updated nlocktimes.zip file will be sent via email.

Parameters:
  • session – The session to use.
  • locktime_details – The Locktime Details JSON for setting the block value.
  • call – Destination for the resulting GA_auth_handler to change the locktime. Returned GA_auth_handler should be freed using GA_destroy_auth_handler.
Returns:

GA_OK or an error code.

Return type:

int

int GA_set_transaction_memo(struct GA_session* session, const char* txhash_hex, const char* memo, uint32_t memo_type)

Add a transaction memo to a user’s GreenAddress transaction.

Parameters:
  • session – The session to use.
  • txhash_hex – The transaction hash to associate the memo with.
  • memo – The memo to set.
  • memo_type – The type of memo to set, either GA_MEMO_USER or GA_MEMO_BIP70.
Returns:

GA_OK or an error code.

Return type:

int

int GA_get_fee_estimates(struct GA_session* session, GA_json** estimates)

Get the current network’s fee estimates.

Parameters:

The estimates are returned as an array of 25 elements. Each element is an integer representing the fee estimate expressed as satoshi per 1000 bytes. The first element is the minimum relay fee as returned by the network, while the remaining elements are the current estimates to use for a transaction to confirm from 1 to 24 blocks.

Returns:GA_OK or an error code.
Return type:int
int GA_get_mnemonic_passphrase(struct GA_session* session, const char* password, char** mnemonic)

Get the user’s mnemonic passphrase.

Parameters:
  • session – The session to use.
  • password – Optional password to encrypt the user’s mnemonic passphrase with.
  • mnemonic – Destination for the user’s 24 word mnemonic passphrase. if a non-empty password is given, the returned mnemonic passphrase will be 27 words long and will require the password to use for logging in. Returned string should be freed using GA_destroy_string.
Returns:

GA_OK or an error code.

Return type:

int

int GA_get_system_message(struct GA_session* session, char** message_text)

Get the latest un-acknowledged system message.

Parameters:
  • session – The session to use.
  • message_text – The returned UTF-8 encoded message text. Returned string should be freed using GA_destroy_string.

Note

If all current messages are acknowledged, an empty string is returned.

Returns:GA_OK or an error code.
Return type:int
int GA_ack_system_message(struct GA_session* session, const char* message_text, struct GA_auth_handler** call)

Sign and acknowledge a system message.

The message text will be signed with a key derived from the wallet master key and the signature sent to the server.

Parameters:
  • session – The session to use.
  • message_text – UTF-8 encoded message text being acknowledged.
  • call – Destination for the resulting GA_auth_handler to acknowledge the message. Returned GA_auth_handler should be freed using GA_destroy_auth_handler.
Returns:

GA_OK or an error code.

Return type:

int

int GA_get_twofactor_config(struct GA_session* session, GA_json** config)

Get the two factor configuration for the current user.

Parameters:
Returns:

GA_OK or an error code.

Return type:

int

int GA_change_settings(struct GA_session* session, const GA_json* settings, struct GA_auth_handler** call)

Change settings

Parameters:
  • session – The session to use.
  • settings – The new Settings JSON values.
  • call – Destination for the resulting GA_auth_handler. Returned GA_auth_handler should be freed using GA_destroy_auth_handler.
Returns:

GA_OK or an error code.

Return type:

int

int GA_get_settings(struct GA_session* session, GA_json** settings)

Get settings

Parameters:
  • session – The session to use.
  • settings – Destination for the current Settings JSON. Returned GA_json should be freed using GA_destroy_json.
Returns:

GA_OK or an error code.

Return type:

int

int GA_set_notification_handler(struct GA_session* session, GA_notification_handler handler, void* context)

Set a handler to be called when notifications arrive.

Parameters:
  • session – The server session to receive notifications for.
  • handler – The handler to receive notifications.
  • context – A context pointer to be passed to the handler.

This must be called before GA_connect/GA_connect_with_proxy. Notifications may arrive on different threads so the caller must ensure that shared data is correctly locked within the handler. The GA_json object passed to the caller must be destroyed by the caller using GA_destroy_json. Failing to do so will result in memory leaks. When the session is disconnected/destroyed, a final call will be made to the handler with a Session event notification JSON notification.

Returns:GA_OK or an error code.
Return type:int
int GA_destroy_json(GA_json* json)

Free a GA_json object.

Parameters:
  • json – GA_json object to free.
Returns:

GA_OK or an error code.

Return type:

int

int GA_auth_handler_get_status(struct GA_auth_handler* call, GA_json** output)

Get the status/result of an action requiring authorization.

Parameters:

Methods in the api that may require two factor or hardware authentication to complete return a GA_auth_handler object. This object encapsulates the process of determining whether authentication is required and handling conditions such as re-prompting and re-trying after an incorrect two factor code is entered.

The object acts as a state machine which is stepped through by the caller until the desired action is completed. At each step, the current state can be determined and used to perform the next action required.

Some actions require a sequence of codes and decisions; these are hidden behind the state machine interface so that callers do not need to handle special cases or program their own logic to handle any lower level API differences.

The state machine has the following states, which are returned in the “status” element from GA_auth_handler_get_status():

  • “done”: The action has been completed successfully. Any data returned from the action is present in the “result” element of the status JSON.
  • “error”: A non-recoverable error occurred performing the action. The associated error message is given in the status element “error”. The auth_handler object should be destroyed and the action restarted from scratch if this state is returned.
  • “request_code”: Two factor authorization is required. The caller should prompt the user to choose a two factor method from the “methods” element and call GA_auth_handler_request_code() with the selected method.
  • “resolve_code”: The caller should prompt the user to enter the code from the twofactor method chosen in the “request_code” step, and pass this code to GA_auth_handler_resolve_code().
  • “call”: Twofactor or hardwre authorization is complete and the caller should call GA_auth_handler_call() to perform the action.
Returns:GA_OK or an error code.
Return type:int
int GA_auth_handler_request_code(struct GA_auth_handler* call, const char* method)

Request a two factor authentication code to authorize an action.

Parameters:
  • call – The auth_handler representing the action to perform.
  • method – The selected two factor method to use
Returns:

GA_OK or an error code.

Return type:

int

int GA_auth_handler_resolve_code(struct GA_auth_handler* call, const char* code)

Authorize an action by providing its previously requested two factor authentication code.

Parameters:
  • call – The auth_handler representing the action to perform.
  • code – The two factor authentication code received by the user.
Returns:

GA_OK or an error code.

Return type:

int

int GA_auth_handler_call(struct GA_auth_handler* call)

Perform an action following the completion of authorization.

Parameters:
  • call – The auth_handler representing the action to perform.
Returns:

GA_OK or an error code.

Return type:

int

int GA_destroy_auth_handler(struct GA_auth_handler* call)

Free an auth_handler after use.

Parameters:
  • call – The auth_handler to free.
Returns:

GA_OK or an error code.

Return type:

int

int GA_change_settings_twofactor(struct GA_session* session, const char* method, const GA_json* twofactor_details, struct GA_auth_handler** call)

Enable or disable a two factor authentication method.

Parameters:
  • session – The session to use
  • method – The two factor method to enable/disable, i.e. “email”, “sms”, “phone”, “gauth”
  • twofactor_details – The two factor method and associated data such as an email address. Two-factor detail JSON
  • call – Destination for the resulting GA_auth_handler to perform the action Returned GA_auth_handler should be freed using GA_destroy_auth_handler.
Returns:

GA_OK or an error code.

Return type:

int

int GA_twofactor_reset(struct GA_session* session, const char* email, uint32_t is_dispute, struct GA_auth_handler** call)

Request to begin the two factor authentication reset process.

Parameters:
  • session – The session to use.
  • email – The new email address to enable once the reset waiting period expires.
  • is_dispute – GA_TRUE if the reset request is disputed, GA_FALSE otherwise.
  • call – Destination for the resulting GA_auth_handler to request the reset. Returned GA_auth_handler should be freed using GA_destroy_auth_handler.
Returns:

GA_OK or an error code.

Return type:

int

int GA_twofactor_cancel_reset(struct GA_session* session, struct GA_auth_handler** call)

Cancel all outstanding two factor resets and unlock the wallet for normal operation.

Parameters:
  • session – The session to use.
  • call – Destination for the resulting GA_auth_handler to cancel the reset. Returned GA_auth_handler should be freed using GA_destroy_auth_handler.
Returns:

GA_OK or an error code.

Return type:

int

int GA_twofactor_change_limits(struct GA_session* session, const GA_json* limit_details, struct GA_auth_handler** call)

Change twofactor limits settings.

Parameters:
  • session – The session to use.
  • limit_details – Details of the new Transaction Limits JSON
  • call – Destination for the resulting GA_auth_handler to perform the change. Returned GA_auth_handler should be freed using GA_destroy_auth_handler.
Returns:

GA_OK or an error code.

Return type:

int

void GA_destroy_string(char* str)

Free a string returned by the api.

Parameters:
  • str – The string to free.
Returns:

GA_OK or an error code.

Return type:

int

int GA_get_random_bytes(size_t num_bytes, unsigned char* output_bytes, size_t len)

Get up to 32 random bytes.

Generate up to 32 random bytes using the same strategy as Bitcoin Core code.

Parameters:
  • output_bytes – bytes output buffer
  • siz – Number of bytes to return (max. 32)
Returns:

GA_OK or an error code.

Return type:

int

int GA_generate_mnemonic(char** output)

Generate a new random BIP 39 mnemonic.

Parameters:
  • output – The generated mnemonic phrase. Returned string should be freed using GA_destroy_string.
Returns:

GA_OK or an error code.

Return type:

int

int GA_validate_mnemonic(const char* mnemonic, uint32_t* valid)

Validate a BIP 39 mnemonic.

Parameters:
  • mnemonic – The mnemonic phrase
  • valid – Destination for the result: GA_TRUE if the mnemonic is valid else GA_FALSE
Returns:

GA_OK or an error code.

Return type:

int

int GA_register_network(const char* name, const GA_json* network_details)

Register a network configuration

Parameters:
  • name – The name of the network to register
  • network_details – The Network JSON configuration to register

Any existing configuration with the same name is overwritten. If the provided JSON is empty, any existing configuration for the network is removed.

Returns:GA_OK or an error code.
Return type:int
int GA_get_networks(GA_json** output)

Get the available network configurations

Parameters:
Returns:

GA_OK or an error code.

Return type:

int

int GA_get_uniform_uint32_t(uint32_t upper_bound, uint32_t* output)

Get a uint32_t in the range 0 to (upper_bound - 1) without bias

Parameters:
  • output – Destination for the generated uint32_t.
Returns:

GA_OK or an error code.

Return type:

int