[Nxt] API of Nxt

[BCNext]

This thread is dedicated to discussion of Nxt API.  Information about Nxt can be found at https://bitcointalk.org/index.php?topic=303898.0


Requests to Nxt software are done using HTTP GET requests.  Parameters are passed as HTTP parameters.  Responses are returned as JSON objects.  If something goes wrong a response will look {"errorCode": 6, "errorDescription": "Blah-blah-blah"}.

The list of all requests is below, I will update it each time I add new ones.


Decode token
Decodes an authorization token.

Request:
http://localhost:7876/? request=decodeToken & website=www.domain.com & token=StringOf160Chars

Response:
{ "account": "398532577100249608", "timestamp": 622, "valid": true }

Note:
This approach should be used to authorize users on web sites.


Get balance
Retrieves the balance of an account.

Request:
http://localhost:7876/? request=getBalance & account=398532577100249608

Response:
{ "balance": 5000, "unconfirmedBalance": 4200 }

Note:
"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.


Get block
Retrieves block data.

Request:
http://localhost:7876/? 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", ...] }

Note:
"generator" is the account that generated the block.
Payload length = "numberOfTransactions" * 128 B.
"previousBlock" absents for the genesis block.
"nextBlock" absents for the last block in the blockchain.
"transactions" is an array of transaction ids.


Get time
Retrieves current time.

Request:
http://localhost:7876/? request=getTime

Response:
{ "time": 417 }

Note:
"time" is measured in seconds since the genesis block timestamp.


Get transaction
Retrieves transaction data.

Request:
http://localhost:7876/? request=getTransaction & transaction=16244659048134841060

Response:
{ "block": "12726165958299924733", "timestamp": 417, "deadline": 900, "sender": "6330031667105067575",  "recipient": "398532577100249608", "amount": 1500, "fee": 5, "confirmations": 2, "signature": "64BytesRepresentedInHexadecimalForm" }

Note:
Data of an unconfirmed transaction doesn't contain "block" and "confirmations" parameters.  Double-spending transactions are not retrieved.


Send money
Sends money.

Request:
http://localhost:7876/? request=sendMoney & secretPhrase=IWontTellYou & recipient=398532577100249608 & amount=1500 & fee=5 & deadline=900 & referencedTransaction=13689168149259791567

Response:
{ "transaction": "16244659048134841060" }

Note:
"deadline" is specified in minutes.
"referencedTransaction" can be omitted.

[1714788513]

1714788513

[Hazard]

Yawn

[Come-from-Beyond]

Sub

[xchrix]

i dont think sending keys as GET param is a good idea! someone who is logging the traffic can easily sniff every message

[BCNext]

API bot shouldn't connect to a remote server.  You can tunnel it through TLS if you wish.

[Come-from-Beyond]

Could u create anything that lets to get new transactions to an account, plz?

[MessyCoin]

How would I have an account unlocked automatically when Nxt starts (or soon after)?

I have Nxt running in a server and wish to unlock the account after reboot because I was told that the account needs to be unlocked to generate POS.

Thanks!

[Come-from-Beyond]

How would I have an account unlocked automatically when Nxt starts (or soon after)?

I have Nxt running in a server and wish to unlock the account after reboot because I was told that the account needs to be unlocked to generate POS.

Thanks!

Try to use this dirty hack:

http://localhost:7875/?user=0.7657349163200706&request=unlockAccount&secretPhrase=MySecret

Value of "user" must be any random number. This is the way the client unlocks accounts. Ignore a response.

[MessyCoin]

How would I have an account unlocked automatically when Nxt starts (or soon after)?

I have Nxt running in a server and wish to unlock the account after reboot because I was told that the account needs to be unlocked to generate POS.

Thanks!

Try to use this dirty hack:

http://localhost:7875/?user=0.7657349163200706&request=unlockAccount&secretPhrase=MySecret

Value of "user" must be any random number. This is the way the client unlocks accounts. Ignore a response.

Thank you. Any way of doing this without visiting a browser? Nxt is running on a headless linux server and configured to start when server reboots. I want it to be generating POS without having to do anything other than boot it up. Perhaps I can use wget or something to ping the url you've suggested after Nxt is started. Just not sure if that is sufficient.

[Come-from-Beyond]

Thank you. Any way of doing this without visiting a browser? Nxt is running on a headless linux server and configured to start when server reboots. I want it to be generating POS without having to do anything other than boot it up. Perhaps I can use wget or something to ping the url you've suggested after Nxt is started. Just not sure if that is sufficient.

U don't need browser, use wget and ping each minute.

Btw, it's better to use the same "user" value each time, so client won't create a new user session.

[MessyCoin]

Thank you. Any way of doing this without visiting a browser? Nxt is running on a headless linux server and configured to start when server reboots. I want it to be generating POS without having to do anything other than boot it up. Perhaps I can use wget or something to ping the url you've suggested after Nxt is started. Just not sure if that is sufficient.

U don't need browser, use wget and ping each minute.

Btw, it's better to use the same "user" value each time, so client won't create a new user session.

Code:

>wget -t 1 http://localhost:7875/?user=0.468539437886&request=unlockAccoun&secretPhrase=<secret>
Connecting to localhost (localhost)|127.0.0.1|:7875... connected.
HTTP request sent, awaiting response... No data received.

This is the response I get from doing my wget command from the console. Seems to give no response at all. Does that seem right?

I've used crontab to do this same command each minute. Added -t 1 to wget so it does not keep retrying.

Even if all is correct then I guess it will take some time to see if it's generating POS, or is there some way I can find out?

Thanks once again.

[Come-from-Beyond]

This is the response I get from doing my wget command from the console. Seems to give no response at all. Does that seem right?

I've used crontab to do this same command each minute. Added -t 1 to wget so it does not keep retrying.

Even if all is correct then I guess it will take some time to see if it's generating POS, or is there some way I can find out?

Thanks once again.

This is right, client talks to webbrowser with Long-polling style. Next request using the same connection would return a response for the previous one.

It begins generating blocks right after u unlock an account.

[Come-from-Beyond]

After running my Nxt Slot Machine script for a while I figured out a safe way to send transactions via API.

When u send a transaction it's processed only if received back from one of the peers. But if u didn't receive it from a peer this does not mean that it won't be included into a block, maybe ur peer just failed to send it back to u.

So the safe way (without a risk to send it twice) is:

1. Send a transaction with a short deadline (10 minutes)
2. In 12 minutes check it's not included into a block and repeat step 1 again if necessary (u will generate a different transaction with the same recipient and amount but not the same timestamp and id)
3. In 720 blocks make sure that the transaction is still in the blockchain (720 blocks is maximum blockchain reorg depth)

[GCInc.]

3. In 720 blocks make sure that the transaction is still in the blockchain (720 blocks is maximum blockchain reorg depth)

So... is it not safe to accept payment before 720 blocks?

What effect does the deadline time have on the payment?

[Come-from-Beyond]

3. In 720 blocks make sure that the transaction is still in the blockchain (720 blocks is maximum blockchain reorg depth)

So... is it not safe to accept payment before 720 blocks?

What effect does the deadline time have on the payment?

Depends on deadline of a depositing transaction. If deadline is set to 24 hours then I would accept it after 10 confirmations. This is equal to 1 Bitcoin confirmation.

Deadline sets transaction expiration time. After blockchain reorg if a new branch doesn't contain a transaction it can be included into a block only if it's not expired.

[Come-from-Beyond]

Version 0.2.16 got 3 new requests:

http://localhost:7876/?request=getState

http://localhost:7876/?request=getTransactionBytes&transaction=XXX

http://localhost:7876/?request=broadcastTransaction&transactionBytes=XXX

They r selfexplanatory I guess.

[GCInc.]

Could you describe the usage of Decode token request please? I can't get my head over the web site authorization system supported by Nxt.

Also, it would be practically necessary to get transaction identifiers for own transactions to be displayed in the wallet client to be able to refer to them while conducting exchanges of value. They have little use in the API otherwise.

[Come-from-Beyond]

Could you describe the usage of Decode token request please? I can't get my head over the web site authorization system supported by Nxt.

Also, it would be practically necessary to get transaction identifiers for own transactions to be displayed in the wallet client to be able to refer to them while conducting exchanges of value. They have little use in the API otherwise.

1. User visits ur site and sees that SSL certificate is issued to "domain.com"
2. He unlocks his account
3. Then he clicks purple key icon next to his account id
4. Into "Website" field he enters "domain.com" and clicks [Generate authorization token]
5. He gets a long string like "quj6mp8oj4er2b46guvi1viqtg2utrb1nivijah8rocrq7nj0m71sseupk39em80vp0j18i1cbt59qi vpke50klg6p4enedlf312jpsa7itg37ldul09lnqfd3ss6a5780u5ahhv5iv30vfpqnpjmc8klib2e9 i9"
6. Then he copies it and pastes into a special field on ur site
7. U get this string (token) and do request http://88.198.210.245:7876/?request=decodeToken&website=domain.com&token=quj6mp8oj4er2b46guvi1viqtg2utrb1nivijah8rocrq7nj0m71sseupk39em80vp0j18i1cbt59qivpke50klg6p4enedlf312jpsa7itg37ldul09lnqfd3ss6a5780u5ahhv5iv30vfpqnpjmc8klib2e9i9
8. Response should look like

Code:

{"timestamp":364062,"valid":true,"account":"3791936988034107349"}

Now u know that this is the legit owner of account 3791936988034107349. U scan the blockchain to get all transactions from 3791936988034107349 to ur account (even sent in advance) to know how much he deposited. U already now how much he withdrew, so u know his balance in ur service.

This approach is useful if u don't want to force 2-factor authorization. All that u need is to let to withdraw funds to 3791936988034107349 only.

Pay attention that "domain.com" must be entered coz it protects the user. If he didn't enter some text that is associated with ur service then u could use his token to authorize urself on some other service like u were him.

Also u can take into account "timestamp" field and reject all attempts to login with very old timestamp.

[GCInc.]

This approach is useful if u don't want to force 2-factor authorization.

That's nearly ingenious! "1.5-factor" authorization built in, takes a while to sink in for the old dog. So I gather the token can be used as OTP.

If only the transaction numbers were used in the web client for consumers to refer to, transition to these new ways of payment authentication would be less painful...

[Come-from-Beyond]

This approach is useful if u don't want to force 2-factor authorization.

That's nearly ingenious! "1.5-factor" authorization built in, takes a while to sink in for the old dog. So I gather the token can be used as OTP.

If only the transaction numbers were used in the web client for consumers to refer to, transition to these new ways of payment authentication would be less painful...

Aye, I like it too. I'm so tired doing registration/authorization for each project. Or adding authorization via Facebook, Twitter, Google, so on and so forth...