Nxt API

Description
The Nxt API allows interaction with Nxt nodes using HTTP GET requests. Responses are returned as JSON objects.

As of version 0.3.20, all API calls are made by communicating with Nxt nodes on port 7874. In all the examples here, the nose is represented as "localhost".

Many API calls make reference to the Genesis block. FYI, the genesis block's ID is 2680262203532249785

Get Balance
Retrieves the balance of an account.

Request
http://localhost:7874/nxt?request=getBalance&account=ACCOUNT Where:
 * ACCOUNT is the Nxt account number

Response
{ "balance": CONFBALANCE, "unconfirmedBalance": UNCONFBALANCE } Where: [b]Note:[/b] "unconfirmedBalance" is the balance minus all unconfirmed sent transactions. It doesn't include double-spending and unconfirmed received transactions. A user sees the unconfirmed balance in the client.
 * CONFBALANCE is the confirmed balance in the Nxt account.
 * UNCONFBALANCE is the unconfirmed balance in the Nxt account.

Example
Request: http://localhost:7874/nxt?request=getBalance&account=398532577100249608 Response: { "account": "398532577100249608", "timestamp": 622, "valid": true }

Create alias
Allows you to create an alias with a single request

Request
https://localhost:7875/nxt?requestType=assignAlias&secretPhrase=SECRET&alias=ALIAS&uri=URI&fee=FEE&deadline=DEADLINE Where:
 * SECRET is the secret passphrase for the sending account
 * ALIAS is the alias you'd like to create
 * URI is the alias text (e.g. http://www.google.com/)
 * FEE is the fee (in Nxt) for the transaction
 * DEADLINE is the deadline for the transaction, in minutes

'Response'
{ TBD }

'Example'
Request: https://localhost:7875/nxt?requestType=assignAlias&secretPhrase=123&alias=Google&uri=http://google.com&fee=1&deadline=1440 Response: { TBD }

Get alias URI
Tells you the target URI of an alias

Request
https://localhost:7875/nxt?requestType=getAliasURI&alias=ALIAS Where:
 * ALIAS is the alias you'd like to create

'Response'
{ TBD }

'Example'
Request: https://localhost:7875/nxt?requestType=getAliasURI&alias=Google Response: TBD

Get alias IDs
Tells you all transactionIDs of aliases after a specified time in the blockchain

Request
https://localhost:7875/nxt?requestType=getAliasIds&timestamp=TIMESTAMP Where:
 * TIMESTAMP is the time from which you'd like to see defined aliases. This is expressed in seconds since the timestamp of the genesis block

'Response'
{ TBD }

'Example'
Request: https://localhost:7875/nxt?requestType=getAliasIds&timestamp=0 Response: TBD

Get Block
Retrieves block data.

Request
http://localhost:7874/nxt?request=getBlock&block=BLOCKADDRESS Where:
 * BLOCKADDRESS is the Nxt block address

Response
{ "height": HEIGHT, "generator": "ACCOUNT", "timestamp": TIME, "numberOfTransactions": NUMTX, "totalAmount": TOTAL, "totalFee": FEE, "version": VERSION, "baseTarget": "BASETARGET", "previousBlock": "PREVBLOCK", "nextBlock": "NEXTBLOCK", "payloadHash": "32BytesRepresentedInHexadecimalForm", "generationSignature": "64BytesRepresentedInHexadecimalForm", "blockSignature": "64BytesRepresentedInHexadecimalForm", "transactions": ["TRANSACTION1", "TRANSACTION2", "TRANSACTION3", ...] } Where:
 * HEIGHT is the block height
 * "generator" is the account that generated the block.
 * ACCOUNT is an account number
 * TIME is the time in seconds that the block was generated; 0 is the time of creation of the genesis block timestamp.
 * NUMTX is the number of transactions in the block
 * TOTAL is the total Nxt in the block
 * FEE is the Nxt fee for the block
 * VERSION is the block version
 * BASETARGET is the hash target for the block generation
 * Payload length = "numberOfTransactions" * 128 Bytes.
 * "previousBlock" is the previous block address. Empty for the genesis block.
 * PREVBLOCK is the previous block address
 * "nextBlock" is the next block address. Blank for the last block in the blockchain.
 * NEXTBLOCK is the next block address
 * "transactions" is an array of transaction ids, representing the transactions in the block.
 * TRANSACTIONX are ID numbers of transactions in the block

Example
Request: http://localhost:7874/nxt?request=getBlock&block=12726165958299924733 Response: { "height": 16, "generator": "398532577100249608", "timestamp": 504, "numberOfTransactions": 149, "totalAmount": 17400, "totalFee": 24, "version": 1, "baseTarget": "54029906605928", "previousBlock": "3483738553242041290", "nextBlock": "9200836476619146595", "payloadHash": "32BytesRepresentedInHexadecimalForm", "generationSignature": "64BytesRepresentedInHexadecimalForm", "blockSignature": "64BytesRepresentedInHexadecimalForm", "transactions": ["2590525739676698091", "5436057910978689871", "8815617645011985536", ...] }

Get State
TBD

Request
http://localhost:7874/nxt?request=getState

Response
{"lastBlock":"LASTBLOCKID","numberOfBlocks":HEIGHT,"lastBlockchainFeeder":"FEEDERIP","totalMemory":CURMEMORY,"freeMemory":FREEMEMORY,"maxMemory":MAXMEMORY,"numberOfTransactions":NUMTRANS,"numberOfUsers":NUMUSERS,"version":"VERSION","numberOfOrders":NUMORDERS,"time":TIME,"availableProcessors":NUMPROCESSORS,"numberOfAssets":NUMASSETS,"numberOfAccounts":NUMACCOUNTS} Where:
 * LASTBLOCKID is the last block address
 * HEIGHT is the block height
 * FEEDERIP is the IP address of the peer that shared this block
 * CURMEMORY is the amount of memory the node is using
 * FREEMEMORY is the amount of free memory on the node
 * MAXMEMORY is the maximum amount of memory the node may use
 * NUMTRANS is the number of transactions in the blockchain
 * NUMUSERS is the number of users conected to this node
 * NUMORDERS is the number of orders on the node
 * NUMPROCESSORS is the number of processors on the node
 * NUMASSETS is the number of assets on the node
 * NUMACCOUNTS is the number of accounts in the blockchain

Example
Request: http://localhost:7874/nxt?request=getState Response: {"lastBlock":"17693825217221067703","numberOfBlocks":20174,"lastBlockchainFeeder":"78.46.63.221","totalMemory":239599616,"freeMemory":80954160,"maxMemory":1908932608,"numberOfTransactions":4797,"numberOfUsers":5,"version":"0.3.20","numberOfOrders":0,"time":2213712,"availableProcessors":4,"numberOfAssets":0,"numberOfAccounts":1781}

Get Time
Retrieves the current time. In Nxt, time is measured in seconds since the genesis block.

Request
http://localhost:7874/nxt?request=getTime

Response
{ "time": TIME } Where:
 * TIME is number of seconds since the genesis block timestamp.

Example
Request: http://localhost:7874/nxt?request=getTime Response: { "time": 417 }

Decode Token
Decodes an authorization token. This is used to authorize users on web sites.

Request
http://localhost:7874/nxt?request=decodeToken&website=WEBSITE&token=AUTHSTRING Where:
 * WEBSITE is the URL for the web site where authorization was granted. By convention this does not include the "http://" portion of the URL.
 * AUTHSTRING is the encoded authorization string

Response
{ "account": "NXTACCOUNT", "timestamp": 622, "valid": true } Where:
 * NXTACCOUNT is the Nxt account number associated with the token
 * TIME is the time in seconds since the Genesis block timestamp, representing the creation time of the token
 * BOOLEAN will be "true" or "false", indicating whether or not the token is valid

Example
Request: http://localhost:7874/nxt?request=decodeToken&website=www.domain.com&token=StringOf160Chars Response: { "account": "398532577100249608", "timestamp": 622, "valid": true }

Broadcast Transaction
TBD

Request
http://localhost:7874/nxt?request=broadcastTransaction&transactionBytes=XXX

Response
{ TBD }

Example
Request: http://localhost:7874/nxt?request=broadcastTransaction&transactionBytes=XXX Response: { TBD }

Get Transaction
Retrieves transaction data.

Request
http://localhost:7874/nxt?request=getTransaction&transaction=TRANSID Where:
 * TRANSID is the Nxt transaction ID

Response
{ "block": "BLOCKID", "timestamp": TIME, "deadline": DEADLINE, "sender": "SENDERACCOUNT", "recipient": "RECIPACCOUNT", "amount": AMOUNT, "fee": FEE, "confirmations": CONFIRMS, "signature": "64BytesRepresentedInHexadecimalForm" } Where: [b]Note:[/b] Data from an unconfirmed transaction does not contain "block" or "confirmations" parameters. Double-spending transactions are not retrieved.
 * BLOCKID is the ID of the block containing the transaction
 * TIME is the time of the transaction, measured in the number of seconds since the genesis block timestamp.
 * DEADLINE is the deadline for transaction, expressed in seconds
 * SENDERACCOUNT is the account number of the sender
 * RECIPACCOUNT is the account number of the recipient
 * AMOUNT is the amount of Nxt in the transaction
 * FEE is the fee (in Nxt) for the transaction
 * CONFIRMS is the number of confirmations for the transaction

Example
Request: http://localhost:7874/nxt?request=getTransaction&transaction=16244659048134841060 Response: { "block": "12726165958299924733", "timestamp": 417, "deadline": 900, "sender": "6330031667105067575", "recipient": "398532577100249608", "amount": 1500, "fee": 5, "confirmations": 2, "signature": "64BytesRepresentedInHexadecimalForm" }

Get Transaction Bytes
Retrieves the size of a transaction, in bytes.

Request
http://localhost:7874/nxt?request=getTransactionBytes&transaction=XXX

Response
{ TBD }

Example
Request: http://localhost:7874/nxt?request=getTransactionBytes&transaction=XXX Response: { TBD }

Send Nxt
Sends Nxt to an account.

Request
http://localhost:7874/nxt?request=sendMoney & secretPhrase=SECRET & recipient=RECIPACCOUNT & amount=AMOUNT & fee=FEE & deadline=DEADLINE & referencedTransaction=REFTRANSACTION Where:
 * SECRET is the secret passphrase for the sending account
 * RECIPACCOUNT is the account number of the recipient
 * AMOUNT is the amount of Nxt in the transaction
 * FEE is the fee (in Nxt) for the transaction
 * DEADLINE is the deadline for the transaction, in minutes
 * REFTRANSACTION is an option reference to a previous Nxt transaction ID

Response
{ "transaction": "TRANSACTIONID" } Where: [b]Note:[/b] "deadline" is specified in minutes. "referencedTransaction" can be omitted.
 * TRANSACTIONID is the ID of the newly-completed transaction

Example
Request: http://localhost:7874/nxt?request=sendMoney&secretPhrase=IWontTellYou&recipient=398532577100249608&amount=1500&fee=5&deadline=900&referencedTransaction=13689168149259791567 Response: { "transaction": "16244659048134841060" }

Error Codes
1 - Incorrect request

2 - Blockchain not up to date

3 - Parameter not specified

4 - Incorrect parameter

5 - Unknown object (block, transaction, etc.)

6 - Not enough funds