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

Endpoints

finance/get/balances

This will retrieve a summary of balance information across all accounts belonging to the currently logged in profile.

finance/get/balances

Parameters

Name	Description	Required
session	User session ID	Required if argument -multiuser=1 is set

Example Response JSON

[
  {
    "available": 1573155.354522,
    "unclaimed": 0.0,
    "unconfirmed": 0.0,
    "decimals": 6,
    "token": "0",
    "ticker": "NXS",
    "stake": 15000.0,
    "immature": 0.0
  },
  {
    "available": 10000.0,
    "unclaimed": 0.0,
    "unconfirmed": 0.0,
    "decimals": 2,
    "token": "8E61JVQENSGtFsr3ivscvC77Tvr3oLm8Zqnw3K4H4vbbTUBeGqW",
    "ticker": "NEX"
  }
]

finance/get/stakeinfo

This will retrieve account values and staking metrics for the trust account belonging to the currently logged in signature chain. If called when the stake minter is not running, this method only returns trust account values. Staking metrics will return 0.

finance/get/stakeinfo

Parameters

Name	Description	Required
session	User session ID	Required if argument -multiuser=1 is set

Example Response JSON

{
  "address": "8EunQ82qVdnuQkX2gXKZr5P55kQRz4KbpaLdCVBjBNu8jeys4C4",
  "balance": 337.362522,
  "stake": 15000.0,
  "trust": 338495,
  "onhold": false,
  "stakerate": 1.8052413746600344,
  "trustweight": 53.440432749937834,
  "blockweight": 15.358176013767272,
  "stakeweight": 49.63220707632078,
  "staking": true,
  "change": false
}

finance/set/stake

Creates a stake change request for a profile's trust account. This request will add or remove stake to set the stake value to the requested amount. If the new value is more than the current stake amount, it adds stake from the account balance. If the new value is less, it removes stake to the account balance (with appropriate trust penalty, if applicable).

Requests are saved locally and take effect with the next stake block found by staking the profiles's trust account. Because they are saved locally, you must continue to stake on the machine where it was created until the next stake block is found, or the request will not be processed. Until implemented, you can update the request by calling set/stake again.

To remove a stake change request, you can either set an expiration time, or set the amount equal to the current trust account stake.

finance/set/stake

finance/void/transaction

Voids (reverses) a debit or transfer transaction, only if it has not been credited or claimed by the recipient. The method creates a corresponding credit or claim transaction but back to the originating account / profile. This means that any applicable fees will apply, as will conditions on the debit / transfer transaction (such as expiration conditions).

For debits that were made to a tokenized asset as part of a split payment transaction, the reversing credit will be made for the debit amount minus any partial amounts that have already been credited by the token holders.

finance/void/transaction

finance/migrate/accounts

This method will migrate your legacy accounts to signature chain accounts, sending the balance across in the process. A new account will be created in your signature chain for each legacy account, with a corresponding matching name (unless flagged not to create names). The balance of each legacy account is sent to the newly created signature chain account in individual transactions. As such, each transaction incurs the default legacy fee of 0.01 NXS, which is deducted from the amount being migrated.

The method uses the arbitrary data field in the account object register to track which legacy account it was created from. As a result, it is possible to invoke this method multiple times, and each time it will sweep any NXS from legacy accounts to existing signature chain accounts (as well as creating any necessary new accounts).

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"
  }
]

list

This will list off all of the object register details specified by the noun.

finance/list/noun

This command supports the account, trust and token nouns.

Parameters

Name	Description	Required
session	User session ID	Required if argument -multiuser=1 is set
where	An array of clauses to filter the JSON results. More information can be found on Queries page.	no

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
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": 1654808816,
    "modified": 1655061950,
    "type": "OBJECT",
    "balance": 5998.0,
    "decimals": 2,
    "currentsupply": 4002.0,
    "maxsupply": 10000.0,
    "token": "8DXmAmkTtysSZUxM3ePA8wRmbSUofuHKSoCyDpN28aLuSrm1nDG",
    "ticker": "XYZ",
    "address": "8DXmAmkTtysSZUxM3ePA8wRmbSUofuHKSoCyDpN28aLuSrm1nDG"
  }
]

transactions

This will list off all of the transactions for the specified noun.

finance/transactions/noun

This command supports the account, trust and token nouns.

Parameters

Name	Description	Required
session	User session ID	Required if argument -multiuser=1 is set
verbose	determines the transaction data included in the response. Supported values are default, summary, and detail.	no

Return Values

Name	Description
blockhash	Hash of the block containing this transaction. Blank if not yet included in a block.
confirmations	Number of confirmations this transaction has obtained by the network
contracts	Described in the contracts table below
sequence	Sequence number of this transaction within the signature chain
timestamp	Unix timestamp when the transaction was created
txid	Transaction hash
type	tritium base | trust | genesis | user)
version	The serialization version of the transaction

contracts

Name	Description
amount	Token amount of the transaction.
contract	Contract ID within the transaction for the credit/claim.
for	For CREDIT transactions, the contract that this credit was created for . Can be COINBASE, DEBIT or LEGACY.
from	For DEBIT, CREDIT, FEE transactions, the register address of the account that the debit is being made from.
from_name	For DEBIT, CREDIT, FEE transactions, the name of the account that the debit is being made from. Only included if the name can be resolved.
id	The sequential ID of this contract within the transaction.
object	Returns a list of all hashed public keys in the crypto object register for the specified profile. The object result will contain the nine default keys(app1, app2, app3, auth, cert lisp, network, sign and verify).
OP	Contract operation. Can be APPEND, CLAIM, COINBASE, CREATE, CREDIT, DEBIT, FEE, GENESIS, LEGACY, TRANSFER, TRUST, STAKE, UNSTAKE, or WRITE.
proof	Register address proving the credit
reference	For DEBIT and CREDIT transactions this is the user supplied reference used by the recipient to relate the transaction to an order or invoice number.
ticket	Name of the token related to the transaction
to	For DEBIT and CREDIT transactions, the register address of the recipient account
to_name	For DEBIT and CREDIT transactions, the name of the recipient account. Only included if the name can be resolved.
token	Register address of the token related to the transaction. Set to 0 for NXS transactions.
txid	The transaction ID hash of the transaction for the credit/claim.

Example Response JSON

[
  {
    "txid": "0123517ca0f1ca110c7b07de9e3c9b33ccbe717f96911e1449b7c73bb9695fbc9c14a58f01f5fb7e9b64756f658af91daec9f0f579df2fad8df61843defae833",
    "type": "tritium user",
    "version": 4,
    "sequence": 23,
    "timestamp": 1655061950,
    "blockhash": "8b206ab2ee4b46a835f74af0ff5d4e0b395acdb94d66468a24083f2a5fd01a07a93956774001bab1a801d53d7bf6ed60ee84a573650eef1a9feaf6fa9beb308bd20b567663cc7ec4f85796b261164ef3452ebfaa13a60141b42fc49d6d2eb2792440925b1b19248ad9fe65e01d3742f2d3dec2817c56c8e4f6e03a10f4147308",
    "confirmations": 4,
    "contracts": [
      {
        "id": 0,
        "OP": "DEBIT",
        "from": "8DXmAmkTtysSZUxM3ePA8wRmbSUofuHKSoCyDpN28aLuSrm1nDG",
        "to": "8Bk5PxsecfXWpbHsDXeZ47MCgDF7qDLsU4Y4MJw2VB29LsTR98z",
        "amount": 1.0,
        "token": "8DXmAmkTtysSZUxM3ePA8wRmbSUofuHKSoCyDpN28aLuSrm1nDG",
        "ticker": "XYZ",
        "reference": 57891358795
      }
    ]
  },
  {
    "txid": "01f1a3f9227a69382f9811a5b1497a865ace17ad83b03118b24f875f6ade83117887c35d08375c259aa1076b91f42206110314756a11a943760bb5c0dd0523d7",
    "type": "tritium user",
    "version": 4,
    "sequence": 21,
    "timestamp": 1655060214,
    "blockhash": "048f3b308e8bd8c1aa31ec1ec2e136a9ccc91ec4498283d07fc5d0a00c8576e2c199567a44058222961f474626c6f2c5d7e774eee34c34f98acafaeb50b7abaaade7e9c641fe9727fe62533b1ec6bf2f75ffbf19d17d74671e2458bd73b6407b4bba1951fc84e1af11c2c4fbce1d05d7739e910fdb8a37197c1c422521e2e9f3",
    "confirmations": 6,
    "contracts": [
      {
        "id": 0,
        "OP": "DEBIT",
        "from": "8DXmAmkTtysSZUxM3ePA8wRmbSUofuHKSoCyDpN28aLuSrm1nDG",
        "to": "8Bk5PxsecfXWpbHsDXeZ47MCgDF7qDLsU4Y4MJw2VB29LsTR98z",
        "amount": 1.0,
        "token": "8DXmAmkTtysSZUxM3ePA8wRmbSUofuHKSoCyDpN28aLuSrm1nDG",
        "ticker": "XYZ",
        "reference": 0
      }
    ]
  }
]