Dev:API - Finance

The Finance API provides methods for sending and receiving NXS or other tokens between users / accounts, creating accounts, and managing staking. The full supported endpoint of the finance URI is as follows:

finance/verb/noun/filter/operator

Minimum required components of the URI:

finance/verb/noun

Direct Endpoints

The following commands are direct endpoints not using the supported nouns and verbs:

finance/get/balances
finance/get/stakeinfo
finance/set/stake
finance/void/transaction
finance/migrate/accounts

Supported Nouns

The following nouns are supported for this API command-set:

Noun	Description
account	An object register containing a token-id and balance
any	An object selection noun allowing mixed accounts of different tokens
all	An object selection noun to collect all accounts for given token type
token	An object register containing a token-id, balance, supply, and decimals
trust	An object register containing a token-id, balance, and trust

Supported Verbs

The following verbs are currently supported by this command-set:

Verb	Description	Nouns
burn	Remove a given token from circulation	account
create	Generate a new object of supported type	account, token
credit	Claim funds issued to account from debit	account, any, token
debit	Issue funds from a supported type	account, any, token
get	Get object of a supported type	account, trust, token
history	Generate the history of all last states	account, trust, token
list	List all objects owned by a given user	account, trust, token
transactions	List all transactions that modified specified object	account, trust, token

Verbs

burn

This method can be used to take tokens permanently out of the current supply in a process commonly known as "burning". The method will debit a token account and send the tokens back to the token address. However the transaction contains a condition that will always evaluate to false, guaranteeing that the debit cannot be credited by the token issuer nor the sender. The result is that the amount burned will always appear in the "pending" balance of the token.

finance/burn/account

This command only supports the account noun.

Parameters

Name	Description	Required
address	Register address of the account to debit the tokens from the be burnt	Required if name is not provided
amount	amount of tokens to burn	yes
name	In the format username:name (for local names) or namespace::name (for names in a namespace). If you are logged in, the username: field is not required.	Required if address is not provided
pin	PIN for this profile.	Required if locked.
reference	A 64-bit unsigned integer in the range of 0 to 18446744073709551615.	no
session	User session ID	Required if argument -multiuser=1 is set

Return Values

Name	Description
address	Register address for this account. The address (or name that hashes to this address) is needed when creating crediting or debiting the account.
success	Boolean flag indicating that the debit was successful
txid	The hash of the transaction that was generated for this tx. If using -autotx this field will be omitted.

Example Response JSON

{
  "success": true,
  "address": "8BfLgEprhbHs82LxUkJR9jhQufRZf49g73Nt8XTGevfiyy7ijhb",
  "txid": "01854fe4fdf0d59aebb3a880141484f0542af061cbebfd468db3fcecd13f63a986d990cf669ca4a60822a82b2d4fc7e7e474801a01bff86a35fd0a147a5a62da"
}

create

Create a new object register specified by given noun.

finance/create/noun

This command does not support the any or all nouns.

Parameters

Name	Description	Required
data	Input for the data object	Optional for any noun
decimals	Total number of significant figures. Defaults to 2.	no
name	UTF-8 encoded string that will generate a name object register that points to new object. If noun is token this will be created as a global name.	no
pin	PIN for this profile.	Required if locked.
session	User session ID	Required if argument -multiuser=1 is set
supply	Sets the maximum token supply	Required for token noun
token	Base58-encoded address or ticker name. Defaults to NXS.	no

Return Values

Name	Description
address	Register address of the created object
success	Boolean flag indicating whether the object register has been created
txid	The hash of the transaction that was generated for this tx. If using -autotx this field will be omitted.

Example Response JSON

{
  "success": true,
  "address": "8ESvYizqdApiuKEBjZMF1hnB8asDqECaDwAstcH3UtJ4Z6ceCn2",
  "txid": "0131e17af8029b414814283a3d90813d12c238db6ddab213440249b795090a9cd77079d5804ec38303a59414d87108d4e44bf31f54a6c176285281a88ab5d737"
}