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
success	Boolean flag indicating that the burn 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"
}

credit

Create a new object register specified by given noun.

finance/credit/noun

This command supports the account, any, and token nouns.

Parameters

Name	Description	Required
pin	PIN for this profile.	Required if locked.
session	User session ID	Required if argument -multiuser=1 is set
txid	The transaction hash being credited	yes

Return Values

Name	Description
success	Boolean flag indicating whether the object register has been credited
txid	The ID (hash) of the transaction that was generated. If using -autotx this field will be omitted.

Example Response JSON

{
  "success": true,
  "txid": "01f51d6b23b871fc8da848afa57cf066cb9e3b8fb845a666335e8c678ef5249e98d4f3e477659098918e4bb590472a63d0ed0a17fa87904fcff6316158e9edfd"
}

debit

Deduct an amount of NXS or token specified by the noun and send it to another account or legacy UTXO address. Only NXS can be sent to the legacy address.

finance/debit/noun

This command supports the account, any, and token nouns.

Parameters

Name	Description	Required
amount	The amount of NXS or token to debit	true
expires	Number of seconds until the transaction can no longer be claimed by the recipient. If expires is set to 0, the transaction will never expire, making the sender unable to ever void the transaction. If omitted, a default expiration of 7 days (604800 seconds) is applied.	no
from	Name or register address of the account to debit. The name should be in the format name (for global token names), username:name (for local names) or namespace::name (for names in a namespace).	true
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
to	Name or the register address of the account to credit	true

Return Values

Name	Description
success	Boolean flag indicating whether the debit was successful
txid	The ID (hash) of the transaction that was generated. If using -autotx this field will be omitted.

Example Response JSON

{
  "success": true,
  "txid": "01f51d6b23b871fc8da848afa57cf066cb9e3b8fb845a666335e8c678ef5249e98d4f3e477659098918e4bb590472a63d0ed0a17fa87904fcff6316158e9edfd"
}

get

Retrieves information for a single object for a type specified by the noun

 finance/get/noun

This command supports the account, trust and token nouns.

Parameters

Name	Description	Required
address	Register address of the account to debit the tokens from the be burnt	Required if name is not provided
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
session	User session ID	Required if argument -multiuser=1 is set

Return Values

Name	Description
address	Register address that has been retrieved
age	Age of the trust account in the format "(x) days, (x) hours, (x) minutes"
balance	The available balance of this account. This is the last confirmed balance added to any new debits made since the last block.
created	UNIX timestamp when the account was created
currentsupply	Amount of tokens that have been distributed to token accounts
decimals	Maximum number of decimal places that can be applied to token amounts
maxsupply	Maximum token supply amount
modified	UNIX timestamp when the account was last modified
owner	Genesis hash of the profile that owns this account
rate	Current annual percentage reward rate from staking
stake	Amount of NXS currently staked in a trust account
ticker	Name of the token object. For NXS accounts will show NXS.
token	Register address of the token. Set to 0 for NXS accounts.
trust	Trust score of the trust account
type	The type of register. Can be OBJECT, RAW or READONLY
version	The serialization version of the transaction

Example Response JSON

{
  "owner": "b1b5b4f4197548886016586f95735f0cb8235183a9185b8720bd27502a2e2850",
  "version": 1,
  "created": 1638020495,
  "modified": 1655118914,
  "type": "OBJECT",
  "balance": 300.536104,
  "stake": 15000.0,
  "token": "0",
  "ticker": "NXS",
  "trust": 3399813,
  "age": "39 days, 8 hours, 23 minutes",
  "rate": 3.0,
  "address": "8EunQ82qVdnuQkX2gXKZr5P55kQRz4KbpaLdCVBjBNu8jeys4C4"
}

history

This will get the history of the specified noun.

finance/history/noun

This command supports the account, trust and token nouns.

Parameters

Name	Description	Required
address	register address of the asset	Required if name is not provided
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
session	User session ID	Required if argument -multiuser=1 is set

Return Values

Name	Description
action	MODIFY | TRANSFER | CLAIM.
address	Register address that has been retrieved
age	Age of the trust account in the format "(x) days, (x) hours, (x) minutes"
balance	The available balance of this account. This is the last confirmed balance added to any new debits made since the last block.
created	UNIX timestamp when the account was created
currentsupply	Amount of tokens that have been distributed to token accounts
decimals	Maximum number of decimal places that can be applied to token amounts
maxsupply	Maximum token supply amount
modified	UNIX timestamp when the account was last modified
name	Name identifying the account, trust or token
owner	Genesis hash of the profile that owns the object
rate	Current annual percentage reward rate from staking
stake	Amount of NXS currently staked in a trust account
ticker	Name of the token object. For NXS accounts will show NXS.
token	Register address of the token. Set to 0 for NXS accounts.
trust	Trust score of the trust account
type	The type of register. Can be OBJECT, RAW or READONLY
version	The serialization version of the transaction

Example Response JSON

[
  {
    "owner": "b7fa11647c02a3a65a72970d8e703d8804eb127c7e7c41d565c3514a4d3fdf13",
    "version": 1,
    "created": 1654808903,
    "modified": 1654809207,
    "type": "OBJECT",
    "balance": 1000.0,
    "token": "8DXmAmkTtysSZUxM3ePA8wRmbSUofuHKSoCyDpN28aLuSrm1nDG",
    "ticker": "XYZ",
    "address": "8Bk5PxsecfXWpbHsDXeZ47MCgDF7qDLsU4Y4MJw2VB29LsTR98z",
    "name": "local:XYZToken",
    "action": "CREDIT"
  },
  {
    "owner": "b7fa11647c02a3a65a72970d8e703d8804eb127c7e7c41d565c3514a4d3fdf13",
    "version": 1,
    "created": 1654808903,
    "modified": 1654808903,
    "type": "OBJECT",
    "balance": 0.0,
    "token": "8DXmAmkTtysSZUxM3ePA8wRmbSUofuHKSoCyDpN28aLuSrm1nDG",
    "ticker": "XYZ",
    "address": "8Bk5PxsecfXWpbHsDXeZ47MCgDF7qDLsU4Y4MJw2VB29LsTR98z",
    "name": "local:XYZToken",
    "action": "CREATE"
  }
]