Dev:API - Finance

From Nexus Wiki
Jump to navigation Jump to search

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
      }
    ]
  }
]
Retrieved from "https://nexus-wiki.org/index.php?title=Dev:API_-_Finance&oldid=154"