This section describes the various JSON formats used by the library.
Passed to GA_init when initializing the library.
{
"datadir": "/path/to/store/data"
"tordir": "/path/to/store/tor/data"
"registrydir": "/path/to/store/registry/data"
"log_level": "info",
}
- datadir
Mandatory. A directory which gdk will use to store encrypted data relating to sessions.
- tordir
An optional directory for tor state data, used when the internal tor implementation is enabled in
net-params
. Note that each process using the library at the same time requires its own distinct directory. If not given, a sub-directory"tor"
inside"datadir"
is used.- registrydir
An optional directory for the registry data, used when the network is liquid based. Note that each process using the library at the same time requires its own distinct directory. If not given, a sub-directory
"registry"
inside"datadir"
is used.- log_level
Library logging level, one of
"debug"
,"info"
,"warn"
,"error"
, or"none"
.
{
"name": "testnet",
"proxy": "localhost:9150",
"use_tor": true,
"user_agent": "green_android v2.33",
"spv_enabled": false,
"cert_expiry_threshold": 1
"gap_limit": 20,
}
- name
The name of the network to connect to. Must match a key from
networks-list
.- proxy
The proxy connection to pass network traffic through, if any.
- use_tor
true
to enable Tor connections,false
otherwise. If enabled and a proxy is not given, a Tor connection will be started internally. If a proxy is given and Tor is enabled, the proxy must support resolving".onion"
domains.- user_agent
The user agent string to pass to the server for multisig connections.
- spv_enabled
true
to enable SPV verification for the session,false
otherwise.- cert_expiry_threshold
Ignore certificates expiring within this many days from today. Used to pre-empt problems with expiring embedded certificates.
- gap_limit
Optional, singlesig only. Number of consecutive empty scripts/addresses to monitor. Defaults to 20.
Contains the proxy settings in use by a session.
{
"proxy": "localhost:9150",
"use_tor": true
}
- proxy
The proxy connection being used to pass network traffic through, or an empty string.
- use_tor
true
if Tor is enabled,false
otherwise.
Contains the authentication details used to create and login to a wallet via GA_register_user or GA_login_user. Also returned from GA_get_credentials where it contains the credentials used to login, and for Liquid sessions, the element "master_blinding_key"
will be present and hold the wallets SLIP 77 master blinding key if it is available.
To authenticate with a hardware wallet, pass empty JSON and provide hw-device
.
To authenticate with a mnemonic and optional password:
{
"mnemonic": "moral lonely ability sail balance simple kid girl inhale master dismiss round about aerobic purpose shiver silly happy kitten track kind pattern nose noise",
"password": ""
}
Or, with a mnemonic and optional BIP39 passphrase:
{
"mnemonic": "moral lonely ability sail balance simple kid girl inhale master dismiss round about aerobic purpose shiver silly happy kitten track kind pattern nose noise",
"bip39_passphrase": ""
}
To authenticate with a PIN:
{
"pin": "123456",
"pin_data": {
"encrypted_data": "0b39c1e90ca6adce9ff35d1780de74b91d46261a7cbf2b8d2fdc21528c068c8e2b26e3bf3f6a2a992e0e1ecfad0220343b9659495e7f4b21ff95c32cee1b2dd6b0f44b3828ccdc73d68d9e4142a25437b0c6b53a056e2415ca23442dd18d11fb5f62ef9155703c36a5b3e10b2d93973602cebb2369559612cb4267f4826028cea7b067d6ec3658cc72155a4b17b4ba277c143d40ce49c407102c62ca759d04e74dd0778ac514292be09f66449993c36b0bc0cb78f41368bc394d0cf444d452bea0e7df5766b92a3c3a3c57169c2529e9aa36e89b3f6dfcfddc6027f3aabd47dedbd9851729a3f6fba899842b1f5e949117c62e94f558da5ebd37feb4927209e2ead2d492c1d647049e8a1347c46c75411a14c5420ef6896cd0d0c6145af76668d9313f3e71e1970de58f674f3b387e4c74d24214fbc1ad7d30b3d2db3d6fb7d9e92dd1a9f836dad7c2713dc6ebfec62f",
"pin_identifier": "38e2f188-b3a8-4d98-a7f9-6c348cb54cfe",
"salt": "a99/9Qy6P7ON4Umk2FafVQ=="
}
}
- pin
The PIN entered by the user to unlock the wallet.
- pin_data
See
pin-data
.
To authenticate a watch-only user (multisig only):
{
"username": "my_watch_only_username",
"password": "my_watch_only_password"
}
To authenticate a watch-only wallet (singlesig and Bitcoin only):
{
"core_descriptors": ["pkh([00000000/44'/1'/0']tpubDC2Q4xK4XH72J7Lkp6kAvY2Q5x4cxrKgrevkZKC2FwWZ9A9qA5eY6kvv6QDHb6iJtByzoC5J8KZZ29T45CxFz2Gh6m6PQoFF3DqukrRGtj5/0/*"],
}
Or alternatively:
{
"slip132_extended_pubkeys": ["tpubDC2Q4xK4XH72J7Lkp6kAvY2Q5x4cxrKgrevkZKC2FwWZ9A9qA5eY6kvv6QDHb6iJtByzoC5J8KZZ29T45CxFz2Gh6m6PQoFF3DqukrRGtj5"],
}
The values to use for "core_descriptors"
and "slip132_extended_pubkeys"
can be obtained from GA_get_subaccount.
Describes the capabilities of an external signing device.
{
"device": {
"name": "Ledger",
"supports_ae_protocol": 0,
"supports_arbitrary_scripts": true,
"supports_host_unblinding": false,
"supports_external_blinding": false,
"supports_liquid": 1,
"supports_low_r": false,
}
}
- name
The unique name of the hardware device.
- supports_arbitrary_scripts
True if the device can sign non-standard scripts such as CSV.
- supports_low_r
True if the device can produce low-R ECDSA signatures.
- supports_liquid
0 if the device does not support Liquid, 1 otherwise.
- supports_host_unblinding
True if the device supports returning the Liquid master blinding key.
- supports_external_blinding
True if the device supports blinding and signing Liquid transactions with outputs that are already blinded from another wallet (e.g. 2-step swaps).
- supports_ae_protocol
See "ae_protocol_support_level" enum in the gdk source for details.
The default for any value not provided is false or 0.
Contains the data returned by GA_encrypt_with_pin. The caller must persist this data and pass it to GA_login_user along with the users PIN in order to allow a PIN login.
{
"encrypted_data": "0b39c1e90ca6adce9ff35d1780de74b91d46261a7cbf2b8d2fdc21528c068c8e2b26e3bf3f6a2a992e0e1ecfad0220343b9659495e7f4b21ff95c32cee1b2dd6b0f44b3828ccdc73d68d9e4142a25437b0c6b53a056e2415ca23442dd18d11fb5f62ef9155703c36a5b3e10b2d93973602cebb2369559612cb4267f4826028cea7b067d6ec3658cc72155a4b17b4ba277c143d40ce49c407102c62ca759d04e74dd0778ac514292be09f66449993c36b0bc0cb78f41368bc394d0cf444d452bea0e7df5766b92a3c3a3c57169c2529e9aa36e89b3f6dfcfddc6027f3aabd47dedbd9851729a3f6fba899842b1f5e949117c62e94f558da5ebd37feb4927209e2ead2d492c1d647049e8a1347c46c75411a14c5420ef6896cd0d0c6145af76668d9313f3e71e1970de58f674f3b387e4c74d24214fbc1ad7d30b3d2db3d6fb7d9e92dd1a9f836dad7c2713dc6ebfec62f",
"pin_identifier": "38e2f188-b3a8-4d98-a7f9-6c348cb54cfe",
"salt": "a99/9Qy6P7ON4Umk2FafVQ=="
}
{
"pin": "...",
"plaintext": {}
}
- pin
The PIN to protect the server provided key.
- plaintext
The json to encrypt. For instance it can be the
login-credentials
with the mnemonic.
{
"pin_data": "...",
}
- pin_data
See
pin-data
.
{
"pin": "...",
"pin_data": "...",
}
- pin
The PIN that protects the server provided key.
- pin_data
See
pin-data
.
Describes the wallet to compute an identifier for using GA_get_wallet_identifier. You may pass login-credentials
to compute an identifier from a mnemonic and optional password, note that PIN or watch-only credentials cannot be used. otherwise, pass the wallets master xpub as follows:
{
"master_xpub": "tpubD8G8MPH9RK9uk4EV97RxhzaY8SJPUWXnViHUwji92i8B7vYdht797PPDrJveeathnKxonJe8SbaScAC1YJ8xAzZbH9UvywrzpQTQh5pekkk",
}
- master_xpub
The base58-encoded BIP32 extended master public key of the wallet.
Accepts an optional password to encrypt the mnemonic.
{
"password": ""
}
Describes a subaccount within the users wallet. Returned by GA_get_subaccount and as the array elements of GA_get_subaccounts.
- hidden
Whether the subaccount is hidden.
- name
The name of the subaccount.
- pointer
The subaccount number.
- receiving_id
The Green receiving ID for the subaccount.
- recovery_chain_code
For
"2of3"
subaccounts, the BIP32 chain code of the users recovery key.- recovery_pub_key
For
"2of3"
subaccounts, the BIP32 public key of the users recovery key.- recovery_xpub
For
"2of3"
subaccounts, the BIP32 xpub of the users recovery key.- required_ca
For
"2of2_no_recovery"
subaccounts, the number of confidential addresses that the user must upload to the server before transacting.- type
For multisig subaccounts, one of
"2of2"
,"2of3"
or"2of2_no_recovery"
. For singlesig subaccounts, one of"p2pkh"
,"p2wpkh"
or"p2sh-p2wpkh"
.- bip44_discovered
Singlesig only. Whether or not this subaccount contains at least one transaction.
- user_path
The BIP32 path for this subaccount. This field is only returned by GA_get_subaccount.
- core_descriptors
Singlesig only. The Bitcoin Core compatible output descriptors. One for the external chain and one for internal chain (change), for instance
"sh(wpkh(tpubDC2Q4xK4XH72H18SiEV2A6HUwUPLhXiTEQXU35r4a41ZVrUv2cgKUMm2fsKTapi8DH4Y8ZVjy8TQtmyWMuH37kjw8fQGJahjWbuQoPm6qRF/0/*))"
"sh(wpkh(tpubDC2Q4xK4XH72H18SiEV2A6HUwUPLhXiTEQXU35r4a41ZVrUv2cgKUMm2fsKTapi8DH4Y8ZVjy8TQtmyWMuH37kjw8fQGJahjWbuQoPm6qRF/1/*))"
for ap2sh-p2wpkh
subaccount. This field is only returned by GA_get_subaccount.- slip132_extended_pubkey
Singlesig and Bitcoin only. The extended public key with modified version as specified in SLIP-0132 (xpub, ypub, zpub, tpub, upub, vpub). Use of this value is discouraged and this field might be removed in the future. Callers should use descriptors instead. This field is only returned by GA_get_subaccount.
Describes updates to be made to a subaccount via GA_update_subaccount.
{
"hidden": true,
"name": "New name",
"subaccount": 1
}
- hidden
If present, updates whether the subaccount will be marked hidden.
- name
If present, updates the name of the subaccount.
- subaccount
The subaccount to update.
{
"subaccounts": [
{ },
{ }
]
}
- subaccounts
An array of
subaccount-detail
elements for each of the users subaccounts.
Describes a users transaction history returned by GA_get_transactions.
- transactions
Top level container for the users transaction list.
- block_height
The network block height that the transaction was confirmed in, or
0
if the transaction is in the mempool.- can_cpfp
A boolean indicating whether the user can CPFP the transaction.
- can_rbf
A boolean indicating whether the use can RBF (bump) the transaction fee.
- created_at_ts
The timestamp in microseconds from the Unix epoch when the transaction was seen by gdk or Green servers, or included in a block.
- fee
The BTC or L-BTC network fee paid by the transaction in satoshi.
- fee_rate
The fee rate in satoshi per thousand bytes.
- inputs
See
tx-list-input
.- memo
The users memo, if previously set by GA_set_transaction_memo.
- outputs
See
tx-list-output
.- rbf_optin
A boolean indicating whether the transaction is RBF-enabled.
- satoshi
A map of asset names to the signed satoshi total for that asset in the transaction. Negative numbers represent outgoing amounts, positive incoming.
- spv_verified
The SPV status of the transaction, one of
"in_progress"
,"verified"
,"not_verified"
,"disabled"
,"not_longest"
or"unconfirmed"
.- transaction_vsize
The size of the transaction in vbytes.
- transaction_weight
The weight of the transaction.
- txhash
The txid of the transaction.
- type
One of
"incoming"
,"outgoing"
,"mixed"
or"not unblindable"
.
Describes a transaction input in tx-list
.
- address
For user wallet addresses, the wallet address in base58, bech32 or blech32 encoding.
- addressee
Optional, multisig only. For historical social payments, the account name sent from.
- address_type
For user wallet addresses, One of
"csv"
,"p2sh"
,"p2wsh"
(multisig), or"p2pkh"
,"p2sh-p2wpkh"
,"p2wpkh"
(singlesig), indicating the type of address.- is_internal
Whether or not the user key belongs to the internal chain. Always false for multisig.
- is_output
Always false. Deprecated, will be removed in a future release.
- is_relevant
A boolean indicating whether the input relates to the subaccount the caller passed to GA_get_transactions.
- is_spent
Always true. Deprecated, will be removed in a future release.
- pointer
For user wallet addresses, the address number/final number in the address derivation path.
- pt_idx
Deprecated, will be removed in a future release.
- satoshi
The amount of the input in satoshi.
- script_type
Deprecated, will be removed in a future release.
- subaccount
For user wallet addresses, the subaccount this output belongs to, or
0
.- subtype
For
"address_type"
"csv"
, the number of CSV blocks used in the receiving scriptpubkey.
Liquid inputs have additional fields:
- amountblinder
The hex-encoded amount blinder (value blinding factor, vbf).
- asset_id
The hex-encoded asset id in display format.
- asset_tag
The hex-encoded asset commitment.
- assetblinder
The hex-encoded asset blinder (asset blinding factor, abf).
- commitment
The hex-encoded value commitment.
- is_blinded
A boolean indicating whether or not the input is blinded.
- nonce_commitment
The hex-encoded nonce commitment.
- previdx
The output index of the transaction containing the output representing this input.
- prevpointer
Deprecated, will be removed in a future release.
- prevsubaccount
Deprecated, will be removed in a future release.
- prevtxhash
The txid of the transaction containing the output representing this input.
- script
The scriptpubkey of the output representing this input.
Describes a transaction output in tx-list
.
- address
For user wallet addresses, the wallet address in base58, bech32 or blech32 encoding.
- address_type
For user wallet output addresses, One of
"csv"
,"p2sh"
,"p2wsh"
(multisig), or"p2pkh"
,"p2sh-p2wpkh"
,"p2wpkh"
(singlesig), indicating the type of address.- is_internal
Whether or not the user key belongs to the internal chain. Always false for multisig.
- is_output
Always true. Deprecated, will be removed in a future release.
- is_relevant
A boolean indicating whether the output relates to the subaccount the caller passed to GA_get_transactions.
- is_spent
A boolean indicating if this output has been spent.
- pointer
For user wallet addresses, the address number/final number in the address derivation path.
- pt_idx
Deprecated, will be removed in a future release.
- satoshi
The amount of the output in satoshi.
- script_type
Deprecated, will be removed in a future release.
- subaccount
For user wallet addresses, the subaccount this output belongs to, or
0
.- subtype
For
"address_type"
"csv"
, the number of CSV blocks used in the receiving scriptpubkey.
Liquid outputs have the following additional fields:
- amountblinder
The hex-encoded amount blinder (value blinding factor, vbf).
- asset_id
The hex-encoded asset id in display format.
- asset_tag
The hex-encoded asset commitment.
- assetblinder
The hex-encoded asset blinder (asset blinding factor, abf).
- blinding_key
The blinding public key for the output.
- commitment
The hex-encoded value commitment.
- is_blinded
For user wallet outputs, a boolean indicating whether or not the output is blinded.
- is_confidential
For user wallet outputs, always true when
is_blinded
is true.- nonce_commitment
The hex-encoded nonce commitment.
- script
For user wallet outputs, the scriptpubkey of this output.
- unconfidential_address
For user wallet outputs, the non-confidential address corresponding to
address
. This is provided for informational purposes only and should not be used to receive.
Contains information about a transaction that may not be associated with the users wallet. Returned by GA_get_transaction_details.
Contains the details of a caller-generated transaction to sign.
To sign with a specific sighash, set "user_sighash"
for the elements of "transaction_inputs"
you wish to sign with a certain sighash, otherwise SIGHASH_ALL
(1
) will be used.
Set "skip_signing"
to true
for any input in "transaction_inputs"
you do not wish to have signed.
All other fields are not user-editable and should be passed unchanged.
Contains the details of a caller-generated and signed transaction from GA_sign_transaction to send to the network.
For multisig session, this will send via the Green backend service, signing any inputs that require service signatures before broadcasting.
All fields are not user-editable and should be passed unchanged.
Describes the swap to be created when calling GA_create_swap_transaction.
{
"swap_type": "liquidex",
"input_type": "liquidex_v1",
"liquidex_v1": {},
"output_type": "liquidex_v1"
}
- swap_type
Pass
"liquidex"
to create the maker's side of a LiquiDEX 2-step swap.- input_type
Pass
"liquidex_v1"
to pass LiquiDEX version 1 details.- liquidex_v1
The LiquiDEX v1 specific parameters, see
liquidex-v1-create-details
. This field must included only if"input_type"
is"liquidex_v1"
.- output_type
Pass
"liquidex_v1"
to return LiquiDEX proposal JSON version 1.
If the "output_type"
was "liquidex_v1"
this field is liquidex-v1-create-result.
Describes the swap to be completed when calling GA_complete_swap_transaction.
{
"swap_type": "liquidex",
"input_type": "liquidex_v1",
"liquidex_v1": {},
"output_type": "transaction",
"utxos": {},
}
- swap_type
Pass
"liquidex"
to complete the taker's side of a LiquiDEX 2-step swap.- input_type
Pass
"liquidex_v1"
to pass a LiquiDEX proposal JSON version 1.- liquidex_v1
The LiquiDEX v1 specific parameters, see
liquidex-v1-complete-details
. This field must included only if"input_type"
is"liquidex_v1"
.- output_type
Pass
"transaction"
to return a transaction JSON that can be passed to GA_sign_transaction.- utxos
Mandatory. The UTXOs to fund the transaction with,
unspent-outputs
as returned by GA_get_unspent_outputs. Note that coin selection is not performed on the passed UTXOs. All passed UTXOs of the same asset as the receiving asset id will be included in the transaction.
If the "output_type"
was "transaction"
this field is sign-tx-details
.
{
"psbt": "...",
"utxos": [],
"blinding_nonces": [],
}
- psbt
The PSBT or PSET encoded in base64 format.
- utxos
Mandatory. The UTXOs that should be signed,
unspent-outputs
as returned by GA_get_unspent_outputs. UTXOs that are not inputs of the PSBT/PSET can be included. Caller can avoid signing an input by not passing in its UTXO.- blinding_nonces
For
"2of2_no_recovery"
subaccounts only, the blinding nonces in hex format for all outputs.
{
"psbt": "...",
"utxos": [],
}
- psbt
The input PSBT or PSET in base64 format, with signatures added for all inputs signed.
- utxos
The UTXOs corresponding to each signed input, in the order they appear in the PSBT transaction.
{
"psbt": "...",
"utxos": [],
}
- psbt
The PSBT or PSET encoded in base64 format.
- utxos
Mandatory. The UTXOs owned by the wallet,
unspent-outputs
as returned by GA_get_unspent_outputs. UTXOs that are not inputs of the PSBT/PSET can be included.
{
"inputs": [
{
"asset_id": "...",
"satoshi": 0,
"subaccount": 0,
},
],
"outputs": [
{
"asset_id": "...",
"satoshi": 0,
"subaccount": 0,
},
],
}
Note
Inputs and outputs might have additional fields that might be removed or changed in following releases.
Describes a request for the wallet to sign a given message via GA_sign_message.
{
"address": "...",
"message": "..."
}
- address
The address to use for the private key. Must be a singlesig address, and the address must belong to the wallet.
- message
The message to sign.
Returned by GA_sign_message.
{
"signature": "..."
}
- message
The recoverable signature of the message encoded in base 64.
{"fees":[1000,10070,10070,10070,3014,3014,3014,2543,2543,2543,2543,2543,2543,1499,1499,1499,1499,1499,1499,1499,1499,1499,1499,1499,1499]}
Describes the wallets enabled two factor methods, current spending limits, and two factor reset status.
{
"all_methods": [
"email",
"sms",
"phone",
"gauth"
],
"any_enabled": true,
"email": {
"confirmed": true,
"data": "***@@g***",
"enabled": true
},
"enabled_methods": [
"email"
],
"gauth": {
"confirmed": false,
"data": "otpauth://totp/Green%20Bitcoin?secret=IZ3SMET5RDWVUSHB4CPTKUWBJM4HSYHO",
"enabled": false
},
"limits": {
"bits": "5000.00",
"btc": "0.00500000",
"fiat": "0.01",
"fiat_currency": "EUR",
"fiat_rate": "1.10000000",
"is_fiat": false,
"mbtc": "5.00000",
"satoshi": 500000,
"sats": "500000",
"ubtc": "5000.00"
},
"phone": {
"confirmed": false,
"data": "",
"enabled": false
},
"sms": {
"confirmed": false,
"data": "",
"enabled": false
},
"twofactor_reset": {
"days_remaining": -1,
"is_active": false,
"is_disputed": false
}
}
When the user has a fiat spending limit set instead of BTC, limits are returned as e.g:
{
"limits": {
"fiat": "0.01",
"fiat_currency": "EUR",
"is_fiat": true
}
}
- twofactor_reset/days_remaining
The number of days remaining before the wallets two factor authentication is reset, or -1 if no reset procedure is underway.
- twofactor_reset/is_active
Whether or not the wallet is currently undergoing the two factor reset procedure.
- twofactor_reset/is_disputed
Whether or not the wallet two factor reset procedure is disputed.
Contains CBOR data to encode into UR format using GA_bcur_encode.
{
"ur_type": "crypto-seed",
"data": "A20150C7098580125E2AB0981253468B2DBC5202D8641947DA",
"max_fragment_len": 100
}
- ur_type
The type of the CBOR-encoded data.
- data
CBOR-encoded data in hexadecimal format.
- max_fragment_len
The maximum size of each UR-encoded fragment to return.
Where data
is longer than max_fragment_len
, the result is a multi-part encoding using approximately 3 times the minimum number of fragments needed to decode the data, split into parts of size max_fragment_len
or less.
In this case, the caller must provide all returned parts to any decoder, e.g. by generating an animated QR code from them.
Contains UR format data encoded using GA_bcur_encode.
{
"parts": ["ur:crypto-seed/oeadgdstaslplabghydrpfmkbggufgludprfgmaotpiecffltnlpqdenos"]
}
- parts
The resulting array of UR-encoded fragments representing the input CBOR.
Contains UR encoded data to decode into CBOR using GA_bcur_decode.
{
"part": "ur:crypto-seed/oeadgdstaslplabghydrpfmkbggufgludprfgmaotpiecffltnlpqdenos"
}
- part
The UR-encoded string for an individual part. For multi-part decoding, the parts can be provided in any order.
Contains CBOR data decoded from UR format using GA_bcur_decode. The returned JSON depends on the type of the input as returned in the ur-type
element. If the type is not one of those listed below, it is returned as if it were "bytes"
.
- ur-type
"crypto-psbt".
- psbt
The psbt in base-64 format.
- ur-type
"crypto-output".
- descriptor
The bitcoin output descriptor.
- ur-type
"crypto-account".
- descriptors
The list of all available descriptors for the account.
- master_fingerprint
The BIP32 key fingerprint of the master key of the account.
- ur-type
"bytes".
- data
The decoded bytes in hexadecimal format.
- ur-type
"custom".
- data
The decoded data in hexadecimal format.
Contains the users settings.
Contains the query parameters for requesting an address using GA_get_receive_address.
{
"subaccount": 0,
"is_internal": false,
"ignore_gap_limit": false,
}
- subaccount
Mandatory. The value of "pointer" from
subaccount-list
orsubaccount-detail
for the subaccount to fetch addresses for.- is_internal
Optional, singlesig only. Whether or not the user key belongs to the internal chain.
- ignore_gap_limit
Optional, singlesig only. Whether to allow squentially generated addresses to go beyond the
"gap_limit"
passed to or defaulted by GA_connect. This is potentially dangerous as funds received on such addresses are not synced until an address within the gap_limit receives funds.
- address
The wallet address in base58, bech32 or blech32 encoding.
- address_type
One of
"csv"
,"p2sh"
,"p2wsh"
(multisig), or"p2pkh"
,"p2sh-p2wpkh"
,"p2wpkh"
(singlesig), indicating the type of address.- branch
Always
1
, used in the address derivation path for subaccounts.- pointer
The address number/final number in the address derivation path.
- script
The locking script of the address.
- scriptpubkey
The scriptpubkey of the address.
- script_type
Integer representing the type of script.
- subaccount
The subaccount this address belongs to. Matches
"pointer"
fromsubaccount-list
orsubaccount-detail
.- subtype
For
"address_type"
"csv"
, the number of CSV blocks referenced in"script"
, otherwise, 0.- user_path
The BIP32 path for the user key.
For Liquid addresses, the following additional fields are returned:
{
"blinding_key": "02a519491b130082a1abbe17395213b46dae43c3e1c05b7a3dbd2157bd83e88a6e",
"is_blinded": true,
"unconfidential_address": "XV4PaYgbaJdPnYaJDzE41TpbBF6yBieeyd"
}
- blinding_key
The blinding key used to blind this address.
- is_blinded
Always
true
.- unconfidential_address
The non-confidential address corresponding to
address
. This is provided for informational purposes only and should not be used to receive.
Contains the query parameters for requesting previously generated addresses using GA_get_previous_addresses.
{
"subaccount": 0,
"last_pointer": 0,
}
- subaccount
Mandatory. The value of "pointer" from
subaccount-list
orsubaccount-detail
for the subaccount to fetch addresses for.- last_pointer
The address pointer from which results should be returned. If this key is not present, the newest generated addresses are returned. If present, the "last_pointer" value from the resulting
previous-addresses
should then be given, until sufficient pages have been fetched or the "last_pointer" key is not present indicating all addresses have been fetched.- is_internal
Singlesig only. Whether or not the user key belongs to the internal chain.
Contains a page of previously generated addresses, from newest to oldest.
- last_pointer
If present indicates that there are more addresses to be fetched, and the caller to get the next page should call again GA_get_previous_addresses passing this value in
previous-addresses-request
. If not present there are no more addresses to fetch.- list
Contains the current page of addresses in
receive-address-details
format.
Describes which unspent outputs to return from GA_get_unspent_outputs, or which unspent outputs to include in the balance returned by GA_get_balance.
{
"subaccount": 3,
"num_confs": 0,
"all_coins": false,
"expired_at": 99999,
"confidential": false,
"dust_limit": 546,
"sort_by": "newest"
}
- subaccount
The subaccount to fetch unspent outputs for.
- num_confs
Pass
0
for unconfirmed UTXOs or1
for confirmed.- all_coins
Pass
true
to include UTXOs with statusfrozen
. Defaults tofalse
.- expired_at
If given, only UTXOs where two-factor authentication expires by the given block are returned.
- confidential
Pass
true
to include only confidential UTXOs. Defaults tofalse
.- dust_limit
If given, only UTXOs with a value greater than the limit value are returned.
- sort_by
One of
"oldest"
,"newest"
,"largest"
,"smallest"
. Returns the unspent outputs sorted by block height or value respectively. If not given, defaults to"oldest"
for 2of2 subaccounts and"largest"
for other subaccount types.
Describes the private key to search for unspent outputs for with GA_get_unspent_outputs_for_private_key.
{
"private_key": "6PRK95NQL1rJWZYegfeY1x2vPdsWFsiDDJTziatqkpVFeYi3osJDtiQiw9",
"password": "foobar"
}
- private_key
Mandatory. The private key in WIF or BIP 38 format. If you want to sweep "p2wpkh"/"p2sh-p2wpkh" outputs, prefix the WIF key with
"p2wpkh:"
/"p2wpkh-p2sh:"
.- password
Optional. The password the key is encrypted with, if any.
Contains unspent outputs for the wallet as requested by GA_get_unspent_outputs.
- txhash
The txid of the transaction.
- pt_idx
The index of the output, the vout.
- satoshi
The amount of the output.
- block_height
The height of the block where the transaction is included. Is 0 if the transaction is unconfirmed.
- address_type
One of
"csv"
,"p2sh"
,"p2wsh"
(multisig), or"p2pkh"
,"p2sh-p2wpkh"
,"p2wpkh"
(singlesig), indicating the type of address.- is_internal
Whether or not the user key belongs to the internal chain. Always false for multisig.
- pointer
The user key number/final number in the derivation path.
- subaccount
The subaccount this output belongs to. Matches
"pointer"
fromsubaccount-list
orsubaccount-detail
.- prevout_script
The script being signed, the script code.
- user_path
The BIP32 path for the user key.
- public_key
Singlesig only. The user public key.
- expiry_height
Multisig only. The block height when two-factor authentication expires.
- script_type
Multisig only. Integer representing the type of script.
- user_status
Multisig only. 0 for
"default"
and 1 for"frozen"
.- subtype
Multisig only. For
"address_type"
"csv"
, the number of CSV blocks referenced in"script"
, otherwise, 0.
For Liquid instead of having the "btc"
field, there are (possibly) multiple fields, one for each asset owned, and the keys are the hex-encoded policy ids.
For Liquid the inner maps have additional fields:
- amountblinder
The hex-encoded amount blinder (value blinding factor, vbf).
- asset_id
The hex-encoded asset id in display format.
- asset_tag
The hex-encoded asset commitment.
- assetblinder
The hex-encoded asset blinder (asset blinding factor, abf).
- commitment
The hex-encoded value commitment.
- is_blinded
A boolean indicating whether or not the output is blinded.
- nonce_commitment
The hex-encoded nonce commitment.
Valid status values are "default"
for normal behavior or "frozen"
. Frozen outputs are hidden from the caller's balance and unspent output requests, are not returned in nlocktime emails, and cannot be spent. An account containing frozen outputs can be deleted, whereas an account with unfrozen outputs can not.
Freezing an output requires two factor authentication. Outputs should only be frozen in response to e.g. a dust attack on the wallet. Once a wallet is deleted, any frozen outputs it contained will be unspendable forever.
Note
Only outputs of value less that two times the dust limit can be frozen.
{
"list" : [
{
"txhash": "09933a297fde31e6477d5aab75f164e0d3864e4f23c3afd795d9121a296513c0",
"pt_idx": 1,
"user_status": "frozen"
}
]
}
{"subaccount":0,"first":0,"count":30}
Contains the data describing a network the caller can connect to.
Contains details of all available networks the API can connect to.
For each network listed, a network
element is present containing the networks information.
{"is_fiat":false,"mbtc":"555"}
{"is_fiat":true,"fiat":"555"}
{"confirmed":true,"data":"mail@example.com","enabled":true}
Describes the status of a GA_auth_handler. Returned by GA_auth_handler_get_status.
All status JSON contains a "name"
element with the name of the handler being invoked.
The remaining data returned depends on the current state of the handler, as follows:
"done"
:
{
"status": "done",
"action": "disable_2fa",
"result": {}
}
- action
The action being processed.
- result
The data returned from the call, if any.
"error"
:
{
"status": "error",
"action": "disable_2fa",
"error": "Incorrect code"
}
- action
The action being processed.
- error
A text description of the error that occurred.
"call"
:
{
"status": "call",
"action": "disable_2fa"
}
- action
The action being processed.
"request_code"
:
{
"status": "request_code",
"action": "disable_2fa",
"methods": [ "email", "sms", "phone", "gauth", "telegram" ]
}
- action
The action being processed.
- methods
A list of available two factor methods the user has enabled, or the single element
"data"
if the call requires more data to continue.
"resolve_code"
(two factor):
{
"status": "resolve_code",
"action": "disable_2fa",
"method": "email",
"auth_data": {},
"attempts_remaining": "3"
}
- action
The action being processed.
- method
The two factor method the user should fetch the code to enter from.
- auth_data
Method-specific ancillary data for resolving the call.
- attempts_remaining
If present, the number of incorrect attempts that can be made before the call fails.
"resolve_code"
(hardware wallet/external device):
{
"status": "resolve_code",
"action": "disable_2fa",
"required_data": {
"action": "get_xpubs",
"device": {}
}
}
- action
The action being processed.
- required_data
Contains the data the HWW must provide, see
hw-resolve-overview
.
"resolve_code"
(request for additional data):
{
"status": "resolve_code",
"action": "data",
"method": "data",
"auth_data": {}
}
- action
Always "data".
- method
Always "data".
- auth_data
Method-specific ancillary data for processing the additional data request.
Controls session and internal Tor instance reconnection behavior.
{
"hint": "connect",
"tor_hint": "connect"
}
- hint
Optional, must be either
"connect"
or"disconnect"
if given.- tor_hint
Optional, must be either
"connect"
or"disconnect"
if given.
For both hint types, "disconnect"
will disconnect the underlying network connection used by the session, while "connect"
will reconnect it. if a hint is not given, no action will be taken for that connection type.
Each session will automatically attempt to reconnect in the background when they detect a disconnection, unless "disconnect"
is passed to close the connection first. The session will be notified using a ntf-network
when the underlying network connection changes state.
For environments such as mobile devices where networking may become unavailable to the callers application, the network must be disconnected and reconnected using GA_reconnect_hint in order for connectivity to be resumed successfully. In particular, when using the built-in Tor implementation to connect, failure to do so may result in Tor failing to connect for the remaining lifetime of the application (this is a Tor limitation).
Amounts to convert are passed with a single key containing the unit value to convert, returning all possible conversion values for that value. See amount-data
for the list of unit values available.
For example, to convert satoshi into all available units:
{
"satoshi": 1120
}
If "fiat_currency"
and "fiat_rate"
members are provided, the fiat conversion will fall back on these values if no fiat rates are available. Callers can check the "is_current"
member in the result amount-data
to determine if the fall back values were used.
For example, to convert bits into all available units, with a fiat conversion fallback:
{
"bits": "20344.69",
"fiat_currency": "USD",
"fiat_rate": "42161.22"
}
It is possible to call this method in non logged Electrum sessions by providing pricing details. For example:
{
"satoshi": 1000,
"pricing": {
"currency": "USD",
"exchange": "BITFINEX"
}
}
{
"bits": "20344.69",
"btc": "0.02034469",
"fiat": "0.02",
"fiat_currency": "EUR",
"fiat_rate": "1.10000000",
"mbtc": "20.34469",
"satoshi": 2034469,
"sats": "2034469",
"subaccount": 0,
"ubtc": "20344.69"
"is_current": true
}
- fiat_currency
Set to the users fiat currency if available, otherwise an empty string.
- fiat_rate
Set to the users fiat exchange rate if available, otherwise
null
.- is_current
true
if the"fiat_currency"
and"fiat_rate"
members are current.
{
"all":["AUD","BRL","CAD","CHF","CNY","DKK","EUR","GBP","HKD","IDR","INR","JPY","MXN","MYR","NGN","NOK","NZD","PLN","RUB","SEK","SGD","THB","TRY","USD","ZAR"],
"per_exchange":{"BITFINEX":["USD"],"BITSTAMP":["USD"],"BTCAVG":[],"BTCCHINA":[],"HUOBI":[],"KIWICOIN":["NZD"],"KRAKEN":["EUR","USD"],"LOCALBTC":["AUD","BRL","CAD","CHF","CNY","DKK","EUR","GBP","HKD","IDR","INR","JPY","MXN","MYR","NGN","NOK","NZD","PLN","RUB","SEK","SGD","THB","TRY","USD","ZAR"],"LUNO":["IDR","MYR","NGN","ZAR"],"QUADRIGACX":["CAD","USD"],"TRT":["EUR"]}
}
{
"accept":"json"
"method":"GET"
"urls":[
"https://assets.blockstream.info/index.json"
"http://vi5flmr4z3h3luup.onion/index.json"
]
"proxy":"localhost:9150"
"headers":{"If-Modified-Since":"Mon, 02 Sep 2019 22:39:39 GMT"}
"timeout":10
}
{
"value":65535
}
{
"assets": true,
"icons": true
}
Information about Liquid assets can be obtained by either passing a list of asset ids to query:
{
"assets_id": ["6f0279e9ed041c3d710a9f57d0c02928416460c4b722ae3457a11eec381c526d","ce091c998b83c78bb71a632313ba3760f1763d9cfcffae02258ffa9865a37bd2"]
}
or by specifying one or more of the following attributes:
- names
a list of strings representing asset names;
- tickers
a list of strings representing asset tickers:
- category
must be one of: -
"with_icons"
: only assets that have icons associated to them will be returned; -"hard_coded"
: only assets bundled in the GDK release will be returned; -"all"
: all the locally-stored assets and icons will be returned.
Specifying multiple attributes is interpreted as a logical AND. For example, {"category": "with_icons", "tickers": ["LCAD"]}
will return all the assets with ticker LCAD
that also have an icon.
{
"assets": {
"6f0279e9ed041c3d710a9f57d0c02928416460c4b722ae3457a11eec381c526d": {
"asset_id": "6f0279e9ed041c3d710a9f57d0c02928416460c4b722ae3457a11eec381c526d",
"contract": null,
"entity": null,
"issuance_prevout": {
"txid": "0000000000000000000000000000000000000000000000000000000000000000",
"vout": 0
},
"issuance_txin":{
"txid": "0000000000000000000000000000000000000000000000000000000000000000",
"vin": 0
},
"issuer_pubkey": "",
"name": "btc",
"precision": 8,
"ticker": "L-BTC",
"version": 0
}
},
"icons": {
"6f0279e9ed041c3d710a9f57d0c02928416460c4b722ae3457a11eec381c526d": "BASE64"
}
}
{
"details":"assertion failure: ga_session.cpp:2166:Unknown subaccount"
}
Parameters controlling the GA_get_subaccounts call.
{
"refresh": false
}
- refresh
If set to
true
, subaccounts are re-discovered if appropriate for the session type. Note that this will take significantly more time if set. Defaults tofalse
.
Passed to GA_validate to check the validity of gdk input data.
To validate addressees, for example prior to calling `GA_create_transaction`:
{
"addressees": {},
"network": "mainnet"
}
- addressees
Mandatory. An array of
addressee
elements.- network
Optional. The name of a network to validate the addressees against.
Validation includes that the address is correct and supported by the network, and that the amount given is valid. The given amount in whatever denomination will be converted into "satoshi"
in the returned addressee. For Liquid, a valid hex "asset_id"
must be present.
It is also possible to validate an addressee for another network than that of the current session. To do so, pass a network name in "network"
. Note that when validating against a different network, any amount in the addressee will not be validated or converted, as the session does not have pricing data for other networks than its own.
To validate a LiquiDEX version 1 proposal:
{
"liquidex_v1": {
"proposal": {}
}
}
- liquidex_v1/proposal
The LiquiDEX version 1 proposal to validate.
Returned from GA_validate to indicate the validity of the given JSON document.
{
"is_valid": true,
"errors": [],
"addressees": {}
}
- is_valid
true
if the JSON is valid,false
otherwise.- errors
An array of strings describing each error found in the given document; Empty if
"is_valid"
istrue
.- addressees
If validating addressees, the given
addressee
elements with data sanitized and converted if required. For example, BIP21 URLs are converted to addresses, plus amount/asset if applicable.