# HTTP API

# 1 API Usage Guide

# 1.1 Request Process Overview

  • Generate request data: according to the interface specification you need to generate the request with a valid JSON object. The prefered way to do this is with the @gny/client.
  • Send request data: transfer the generated data to the GNY Blockchain also with @gny/client.
  • GNY Blockchain handles data object: after receiving the data object, the GNY Blockchain will validate the data first and edit to a block if all checks pass.
  • Return the response data: The GNY Blockchain returns the transaction id upon successful execution. See the corresponding endpoint specification for detail.
  • Client handles the response data

TIP

The @gny/client is the preferred way to communicate with the HTTP API

Head to the @gny/client documentation for details

# 2 Interface

# 2.1 Accounts

# 2.1.1 Read Account

# 2.1.1.1 Read Account with PublicKey

API Endpoint: /api/accounts/openAccount
HTTP Verb: POST
Supported Format: JSON
Request Parameter Description:

Name Type Required Description
publicKey string Y GNY publicKey

Response Parameter Description:

Name Type Description
success bool Whether login is successful
account json Account information

# 2.1.2 Get Account Information

API Endpoint: /api/accounts
HTTP Verb: GET
Supported Format: urlencoded
Request Parameter Description:

Name Type Required Description
address string N account address
username string N account username

Response Parameter Description:

Name Type Description
success bool whether response returned successfully
address string Address of of an account. e.g. G3J3aXARHkaGhuwkuzSL2BqYXkcNJ
username string username of an account. e.g. liangpeili
gny string balance of an account. e.g. 476500000000
publicKey string publickey of an account
secondPublicKey string second publickey of an account (optional)
isDelegate number if the account is a delegate. Either 0 (false) or 1 (true)
isLocked number if the account is locked. Either 0 (false) or 1 (true)
lockHeight string if the account is locked this will be not "0" but e.g. block height "2800000"
lockAmount string if the account is locked then this will not be "0" but e.g. "476500000000"
_version_ number the number of how often the properties on the account changed

# 2.1.3 Get Balance of Account

API Endpoint: /api/accounts/getBalance
HTTP Verb: GET
Supported Format: urlencoded
Request Parameter Description:

Name Type Required Description
address string Y Client's address
limit number N
offset number N

Response Parameter Description:

Name Type Description
success bool true: response data return successfully
count number the total number of available balances
balances Array list of balances

# 2.2 Transactions

# 2.2.1 Get the Transaction Detail Information

API Endpoint: /api/transactions
HTTP Verb: GET
Supported Format: urlencoded
Comment: if there is no parameter in request data, all transactions will be returned.

Request Parameter Description:

Name Type Required Description
limit integer N the limitation of returned records,minimum:0,maximum:100
offset integer N offset, minimum 0
id string N transaction id
senderId N GNY address of sender
senderPublicKey string N sender's public key
blockId string N block id
height integer specific block height
type interger N Transaction type, see https://github.com/GNYIO/gny-general/wiki/Transactions for futher information
message string Transaction message

Response Parameter Description:

Name Type Description
success bool true: response data return successfully
transactions Array A JSON object list containing multiple transactions' detail
count int the total number of available transactions

# 2.2.3 Get Transaction Detail by Unconfirmed Transaction ID

API Endpoint: /api/transactions/unconfirmed/get
HTTP Verb: GET
Supported Format: urlencoded
Info: A unconfirmed transaction is only available up to 10 seconds until it is confirmed Request Parameter Description:

Name Type Required Description
id string Y unconfirmed transaction id

Response Parameter Description:

Name Type Description
success bool true: response data return successfully
transaction json unconfirmed transaction detail inforamtion

# 2.2.4 Get Unconfirmed Transaction Detail Information [within all network]

API Endpoint: /api/transactions/unconfirmed
HTTP Verb: GET
Supported Format: urlencoded
Comment: If there is no parameter, all unconfirmed transactions in the whole network will be returned. Request Parameter Description:

Name Type Required Description
senderPublicKey string N sender's public key
address string N address

Response Parameter Description:

Name Type Description
success bool true: response data return successfully
transactions Array a list containing all unconfirmed transactions

# 2.2.5 Get Count of confirmed Transaction

API Endpoint: /api/transactions/count
HTTP Verb: GET
Supported Format: urlencoded

Request Parameter Description:

Name Required Type Description
senderId N string Optional senderId parameter
senderPublicKey N string Optional senderPublicKey parameter

Response Parameter Description:

Name Type Description
count number the number of currently confirmed transactions on the Blockchain

# 2.2.6 Get Transactions, newest first

API Endpoint: /api/transactions/newestFirst
HTTP Verb: GET
Supported Format: urlencoded

Request Parameter Description:

Name Type Required Description
count number Y The count paramter is required. New transactions can be added to the Blockchain every second and which transaction are the newest and get returned by this endpoint changes when new transactions arrive. If the total transaction count changes between two HTTP requests, then the starting point of the counting would change. This would lead to inconsistent result. This makes this parameter mandatory. Therefore it is advised to first fetch the current count of all transactions (/api/transactions/count) and pass it then to this endpoint (/api/transactions/newestFirst?count=123). If the count parameter is passed in, the returned values are consistent. Then paging can be used with ?count=123&offset=0 and then ?count=123&offset=100 to get the first 100 transactions and then the next 23
limit number N maximum number of returned records, between 0 and 100
offset number N default is 0
senderId string N Optional parameter senderId. This can be used to filter for the senderId of all transactions
senderPublicKey sring N Optional parameter senderPublicKey. This can be used to filter for the senderPublicKey of all transactions

Response Parameter Description:

Name Type Description
success bool true: response data return successfully
transactions Array a list containing all unconfirmed transactions

# 2.3 Blocks

# 2.3.1 Get the Block Detail Information of the Given ID

API Endpoint: /api/blocks/getBlock
HTTP Verb: GET
Supported Format: urlencoded
Request Parameter Description:

Name Type Required Description
id string only choose one of these three parameters block ID
height string ditto block height

Response Parameter Description:

Name Type Description
success bool true: response data return successfully
block json the block detail information

# 2.3.2 Get the Latest Block

API Endpoint: /api/blocks
HTTP Verb: GET
Supported Format: urlencoded
Comment: if there is no parameter, the detail of all the blocks in the whole network will be returned
Request Parameter Description:

Name Type Required Description
limit integer N maximum number of returned records, between 0 and 100
offset integer N default is 0
orderBy string N sort by a field in the table, for example, specify height:desc to sort descending, default is height:asc. You can only sort by the height property
transactions boolean N When transactions=true then

Response Parameter Description:

Name Type Description
success bool true: response data return successfully
blocks Array a list of JSON objects containing block detail
count integer block height

# 2.3.3 Get the Block Height

API Endpoint: /api/blocks/getHeight
HTTP Verb: GET
Supported Format: none
Request Parameter Description: none

Response Parameter Description:

Name Type Description
success bool true: response data return successfully
height integer block height

# 2.3.5 Get the Milestone

API Endpoint: /api/blocks/getMilestone
HTTP Verb: GET
Supported Format: none
Request Parameter Description: none
Response Parameter Description:

Name Type Description
success bool true: response data return successfully
milestone integer

Request Example:

# 2.3.6 Get the Reward Information of a Block

API Endpoint: /api/blocks/getReward
Request Method: GET
Supported Format: none
Request Parameter Description: none

Response Parameter Description:

Name Type Description
success bool true: response data return successfully
reward integer the reward of the block

# 2.3.7 Get the Current Maximum Supply of the Blockchain

API Endpoint: /api/blocks/getSupply
HTTP Verb: GET
Supported Format: none
Request Parameter Description: none

Response Parameter Description:

Name Type Description
success bool true: response data return successfully
supply integer the total amount of XAS in the whole network

# 2.3.8 Get Current Status of Blockchain

API Endpoint: /api/blocks/getStatus
HTTP Verb: GET
Supported Format: none
Request Parameter Description: none

Response Parameter Description:

Name Type Description
success bool true: response data return successfully
height integer blockchain height
fee integer transaction fee
milestone integer
reward integer block reward
supply integer total amount of XAS in the whole network

Request Example:

# 2.4 Delegates

# 2.4.1 Get the Total Number of Delegates

API Endpoint: /api/delegates/count
HTTP Verb: GET
Supported Format: none
Request Parameter Description: none

Response Parameter Description:

Name Type Description
success bool true: response data return successfully
count integer total number of delegates

# 2.4.2 Get the Voters for a Delegate

API Endpoint: /api/delegates/getVoters
Request Method: GET
Supported Format: urlencoded
Request Parameter Description:

Name Type Required Description
username string Y username of the delegate

Response Parameter Description:

Name Type Description
success bool true: response data return successfully
accounts Array an array of accounts that voted for this delegate. In order to vote one doesn't need to be delegate. It is enough to have some GNY tokens locked. Only the locked GNY tokens add to the weight of the delegate in the ranking
accounts[0].delegate Object The delegate object on an account object is entirely optional. The delegate object appears only if the the account that voted is also a delegate.

# 2.4.3 Get the Delegate's Detail by Public Key or Name

API Endpoint: /api/delegates/get/
HTTP Verb: GET
Supported Format: urlencoded
Comment: Get the delegate's detail by his/her public key or user name
Request Parameter Description:

Name Type Required Description
publickey string choose only one parameter of these three delegate's public key
username string ditto delegate's user name
address string ditto delgates's address

Response Parameter Description:

Name Type Description
success bool true: response data return successfully
delegate JSON the detail information of this delegate

# 2.4.4 Get the List of Delegates

API Endpoint: /api/delegates
HTTP Verb: GET
Supported Format: urlencoded
Comment: if there is no parameter, all delegates in the whole network will be returned. Request Parameter Description:

Name Type Required Description
limit int N maximum return records
offset integer N offset, minimum: 0

Response Parameter Description:

Name Type Description
success bool true: response data return successfully
delegates Array a list containing delegates' detail information
count number How many delegates exist overall?

# 2.4.7 Get own Votes

API Endpoint: /api/delegates/getOwnVotes
HTTP Verb: POST
Supported Format: urlencoded
Request Parameter Description:

Name Type Required Description
address string N accounts address
username string N accounts username

Response Parameter Description:

Name Type Description
success bool true: response data return successfully
delegates Array a list containing delegates' detail information

# 2.4.8 Enable Forging for Delegate

API Endpoint: /api/delegates/forging/enable
HTTP Verb: POST
Supported Format: urlencoded
Request Parameter Description:

Name Type Required Description
secret string Y GNY account password
publicKey string N public key

Response Parameter Description:

Name Type Description
success bool true: response data return successfully

# 2.4.9 Disable Forging for Delegate

API Endpoint: /api/delegates/forging/disable
HTTP Verb: POST
Supported Format: urlencoded
Request Parameter Description:

Name Type Required Description
secret string Y GNY account password
publicKey string N public key

Response Parameter Description:

Name Type Description
success bool true: response data return successfully

# 2.4.10 Check Delgate Forging Status

API Endpoint: /api/delegates/forging/status
HTTP Verb: GET
Supported Format: urlencoded
Request Parameter Description:

Name Type Required Description
publicKey string N public key of a delegate

# 2.4.11 Return own Delegates Produced Blocks

API Endpoint: /api/delegates/ownProducedBlocks
HTTP Verb: GET
Supported Format: urlencoded

Request Parameter Description:

Name Type Required Description
publicKey string N public key of a delegate
address string N address of a delegate
username string N username of a delegate
limit integer N maximum number of produced blocks to return, between 0 and 100
offset integer N Offset, minimum 0

Response Parameter Description:

Name Type Description
success bool true: response data return successfully
delegate JSON the detail information of this delegate
blocks Array a list of JSON objects containing block detail

# 2.4.12 Search for Delegates

API Endpoint: /api/delegates/search
HTTP Verb: GET
Supported Format: urlencoded

Request Parameter Description:

Name Type Required Description
searchFor string Y if provided with a full address, only this delegate gets returned. If provided with a part of a delegate (e.g. jo) all matching delegates that include this pattern get returned. This endpoint is case sensitive
limit integer N limit, default 200
offset integer N offset, default 0

Response Parameter Description:

Name Type Description
success bool true: response data return successfully
delegate Array the detail information of the matching delegates
count number count how many delegates match the searchFor pattern overall. By default only 200 delegates get returned that match the searchFor pattern, therefore you need to have page thourgh the rest with the help of the offset query parameter

# 2.5 Peers

# 2.5.1 Get all Peers' Information in the Whole Network

API Endpoint: /api/peers
HTTP Verb: GET
Supported Format: urlencoded
Request Parameter Description: none

Response Parameter Description:

Name Type Description
success bool true: response data return successfully
peers Array a JSON array of peers' information
count integer the number of currently running peers

# 2.5.2 Get the Version of Peer

API Endpoint: /api/peers/version
HTTP Verb: GET
Supported Format: none
Request Parameter Description: none

Response Parameter Description:

Name Type Description
success bool true: response data return successfully
version string version number
build timestamp built time
net string either localnet, testnet or mainnet

# 2.5.3 Get Node P2P Information

API Endpoint: /api/peers/version
HTTP Verb: GET
Supported Format: none
Request Parameter Description: none

Response Parameter Description:

Name Type Description
success bool true: response data return successfully
id string of peerId libp2p peer-id (opens new window)
multiaddrs string[] Array of multiaddrs (opens new window) strings which is used for p2p communcation
publicIp string own public ip
address string ip address on which the server is listening. Normal this is a private ip address

# 2.6 Sync and Loader

# 2.6.1 Get the local blockchain loadig status

API Endpoint: /api/loader/status
HTTP Verb: GET
Supported Format: none
Request Parameter Description: none

Response Parameter Description:

Name Type Description
success bool true: response data return successfully
loaded bool
blocksCount integer
now integer

# 2.6.2 Get the block syncing status

API Endpoint: /api/loader/status/sync
HTTP Verb: GET
Supported Format: none
Request Parameter Description: none

Response Parameter Description:

Name Type Description
success bool true: response data return successfully
height int block height

# 2.7 Transfers

# 2.6.1 Get the transfers

API Endpoint: /api/transfers/ HTTP Verb: GET
Supported Format: none
Request Parameter Description:

Name Type Required Description
query.limit integer N the limitation of returned records,minimum:0,maximum:100
query.offset integer N offset, minimum 0
query.ownId string N GNY address, this will return all transfers where the ownId is the recipient or the sender
query.currency string N gny UIA Assets
query.senderId string N GNY address of sender
query.recipientId string N recipient's GNY address

Response Parameter Description:

Name Type Description
success bool true: response data return successfully
count string the number of transfers
transfers Array An array of transfers

# 2.6.2 Get the total amount of transfers

API Endpoint: /api/transfers/amount
HTTP Verb: GET
Supported Format: none
Request Parameter Description:

Name Type Required Description
startTimestamp string Y start timestamp
endTimestamp string Y end timestamp

Response Parameter Description:

Name Type Description
success bool true: response data return successfully
count string the number of transfers
strTotalAmount string the total amout of transfers

# 2.11 User Defined Asset UIA

# 2.11.1 Get all publishers

API Endpoint: /api/uia/issuers
HTTP Verb: GET
Format: urlencoded

Request Parameter Description:

Name Type Required Description
limit integer N maximum number of records to return, between 0 and 100
offset integer N Offset, minimum 0

Response Parameter Description:

Name Type Description
success boolean Whether operation was successful
issuers Array Array of publishers
count integer Total number of publishers

# 2.11.2 Query information about a publisher by name

API Endpoint: /api/uia/issuers/:name|address
HTTP Verb: GET
Format: urlencoded

Request Parameter Description:

Name Type Required Description
publisherName string Y Can be GNY publisher name
address string Y Can be the GNY account address

Response Parameter Description:

Name Type Description
success boolean Whether operation was successful
issuers JSON Contains the publisher name, description and id (GNY address)

# 2.11.3 View assets of a specified publisher

API Endpoint: /api/uia/issuers/:publisherName/assets
HTTP Verb: GET
Format: urlencoded

Request Parameter Description:

Name Type Required Description
name string Y GNY issuer name. For example MARCUS
limit integer N maximum number of records to return, between 0 and 100
offset integer N Offset, minimum 0

Response Parameter Description:

Name Type Description
success boolean true: response data return successfully
assets Array Array of assets
count interger The total number of assets registered by this issuer

# 2.11.4 Get all assets

API Endpoint: /api/uia/assets
HTTP Verb: GET
Format: urlencoded

Request Parameter Description:

Name Type Required Description
limit integer N maximum number of records to return, between 0 and 100
offset integer N Offset, minimum 0

Response Parameter Description:

Name Type Description
success boolean Whether operation was successful
assets Array Array of assets
count integer Number of all assets

# 2.11.5 Get specified asset information

API Endpoint: /api/uia/assets/:name
HTTP Verb: GET
Format: urlencoded

Request Parameter Description:

Name Type Required Description
name string Y Asset name

Response Parameter Description:

Name Type Description
success boolean true: response data return successfully
asset JSON The requested asset

# 2.11.6 Get the balance of all UIA Assets for an account

API Endpoint: /api/uia/balances/:address
HTTP Verb: GET
Format: urlencoded

Request Parameter Description:

Name Type Required Description
address string Y GNY account address
limit integer N maximum number of records to return, between 0 and 100
offset integer N Offset, minimum 0

Response Parameter Description:

Name Type Description
success boolean Whether operation was successful
balances Array Asset array, details owned, each element is an asset, including asset name, balance, cap, precision, current circulation, whether to cancel (0: not cancelled, 1: cancelled)
count integer The number of assets currently owned by this address

# 2.11.7 Get balance of a specific UIA Asset for an account

API Endpoint: /api/uia/balances/:address/:currency
HTTP Verb: GET
Format: urlencoded Request Parameter Description: none

Response Parameter Description:

Name Type Description
success boolean Whether operation was successful

# 2.11.8 Get holders of a specific UIA Asset

API Endpoint: /api/uia/holders/:currency
HTTP Verb: GET
Format: urlencoded Request Parameter Description:

Name Type Required Description
currency string Y a specific UIA Asset
limit integer N maximum number of records to return, between 0 and 100
offset integer N Offset, minimum 0

Response Parameter Description:

Name Type Description
success boolean Whether operation was successful
holders Array Asset array, each element is an asset holder, including address, balance, currency
count integer The number of holders owning this asset

# 2.9 Initiate Transactions

# 2.9.1 Overview

In order to send transactions you need set the magic header:

Last Updated: 3/28/2022, 10:05:07 AM