The SPARTA API
Sparta Core edited this page Nov 5, 2017
·
11 revisions
The SPARTA API allows interaction with SPARTA nodes using HTTP requests to port 8080. Most HTTP requests can use either the GET or POST methods, but some API calls accept only the POST method for security reasons. Responses are returned as JSON objects.
Each API call is documented below, with definitions given for HTTP request parameters and JSON response fields, followed by an example:
- The JSON response fields are each followed by one of S for string, A for array, O for object, N for number or B for boolean.
- In the examples, the SPARTA node is represented as localhost and requests and responses are formatted for easy reading; line breaks and spaces are not actually used except in some parameter values. All requests are in URL format which implies the HTTP GET method. When GET is allowed, the URL can be entered into a browser URL field but proper URL encoding is usually required (e.g., spaces in a parameter value must be replaced by + or %20). Otherwise, the URL should be used as a guide to preparing an HTTP POST request using cURL, for example.
This document corresponds to SPARTA Version 1.0.0.
All API requests that require an account ID accept either an account number or the corresponding SPARTA address.
The following API calls create SPARTA transactions using HTTP POST requests. Follow the links for examples and HTTP POST request parameters specific to each call. Refer to the sections below for HTTP POST request parameters and JSON response fields common to all calls that create transactions.
- Send Money
The following HTTP POST parameters are common to all API calls that create transactions:
- secretPhrase is the secret passphrase of the account (optional, but transaction neither signed nor broadcast if omitted)
- publicKey is the public key of the account (optional if secretPhrase provided)
-
feeAPL is the fee (in APL) for the transaction:
- 1 SPA, where 1 SPA = 100000000 APL
- deadline is the deadline (in minutes) for the transaction to be confirmed, 32767 minutes maximum
- referencedTransactionFullHash creates a chained transaction, meaning that the current transaction cannot be confirmed unless the referenced transaction is also confirmed (optional)
- broadcast is set to false to prevent broadcasting the transaction to the network (optional)
The following JSON response fields are common to all API calls that create transactions:
- signatureHash (S) is a SHA-256 hash of the transaction signature
- unsignedTransactionBytes (S) are the unsigned transaction bytes
- transactionJSON (O) is a transaction object
- broadcasted (B) is true if the transaction was broadcast, false otherwise
- requestProcessingTime (N) is the API request processing time (in millisec)
- transactionBytes (S) are the signed transaction bytes
- fullHash (S) is the full hash of the signed transaction
- transaction (S) is the ID of the newly created transaction
Get account information given an account ID.
Request:
- requestType is getAccount
- account is the account ID
- includeEffectiveBalance is true to include effectiveBalanceSPA and guaranteedBalanceAPL (optional)
- requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)
- requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)
- unconfirmedBalanceAPL (S) is balanceAPL less unconfirmed outgoing transactions, the balance displayed in the client
-
effectiveBalanceAPL (N) is the balance (in APL) of the account available for forging
- currentHeightTo (S)
- nextHeightFrom (S)
- effectiveBalanceAPL (S)
- currentHeightFrom (S)
- nextHeightTo (S)
- forgedBalanceAPL (S) is the balance (in APL) that the account has forged
- balanceAPL (S) is the minimally confirmed basic balance (in APL) of the account
- publicKey (S) is the public key of the account
- requestProcessingTime (N) is the API request processing time (in millisec)
- guaranteedBalanceAPL (S) is the balance (in APL) of the account with at least 1440 confirmations
- accountSPA (S) is the SPARTA address of the account
- account (S) is the account number
- lastBlock (S) is the last block ID on the blockchain (applies if requireBlock is provided but not requireLastBlock)
Get an account ID given a secret passphrase or public key. POST only.
Request:
- requestType is getAccountId
- secretPhrase is the secret passphrase of the account (optional)
- publicKey is the public key of the account (optional if secretPhrase provided)
- accountSPA (S) is the SPARTA address of the account
- publicKey (S) is the public key of the account
- requestProcessingTime (N) is the API request processing time (in millisec)
- account (S) is the account number
Get the balance of an account.
Request:
- requestType is getBalance
- account is an account ID
- includeEffectiveBalance is true to include effectiveBalanceSPA and guaranteedBalanceAPL (optional)
- height is the height to retrieve account balance for, if still available (optional)
- requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)
- requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)
- unconfirmedBalanceAPL (S) is balanceAPL less unconfirmed outgoing transactions, the balance displayed in the client
- guaranteedBalanceAPL (S) is the balance (in APL) of the account with at least 1440 confirmations
- effectiveBalanceSPA (N) is the balance (in SPA) of the account available for forging
- forgedBalanceAPL (S) is the balance (in APL) that the account has forged
- balanceAPL (S) is the minimally confirmed basic balance (in APL) of the account
- lastBlock (S) is the last block ID on the blockchain (applies if requireBlock is provided but not requireLastBlock)
- requestProcessingTime (N) is the API request processing time (in millisec)
Get the transactions associated with an account in reverse block timestamp order.
Request:
- requestType is getBlockchainTransactions
- account is the account ID
- timestamp is the earliest block (in seconds since the genesis block) to retrieve (optional)
- type is the type of transactions to retrieve (optional)
- subtype is the subtype of transactions to retrieve (optional)
- firstIndex is a zero-based index to the first transaction to retrieve (optional)
- lastIndex is a zero-based index to the last transaction to retrieve (optional)
- numberOfConfirmations is the required number of confirmations per transaction (optional)
- requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)
- requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)
- transactions (A) is an array of transactions
- lastBlock (S) is the last block ID on the blockchain (applies if requireBlock is provided but not requireLastBlock)
- requestProcessingTime (N) is the API request processing time (in millisec)
Get a list of unconfirmed transaction IDs associated with an account.
Request:
- requestType is getUnconfirmedTransactionIds
- account is one account ID (optional)
- requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)
- requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)
- firstIndex is a zero-based index to the first transaction ID to retrieve (optional)
- lastIndex is a zero-based index to the last transaction ID to retrieve (optional)
- unconfirmedTransactionIds (A) is an array of unconfirmed transaction IDs
- lastBlock (S) is the last block ID on the blockchain (applies if requireBlock is provided but not requireLastBlock)
- requestProcessingTime (N) is the API request processing time (in millisec)
Get a list of unconfirmed transactions associated with an account.
Request:
- requestType is getUnconfirmedTransactions
- account is one account ID (optional)
- requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)
- requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)
- firstIndex is a zero-based index to the first unconfirmed transaction to retrieve (optional)
- lastIndex is a zero-based index to the last unconfirmed transaction to retrieve (optional)
- unconfirmedTransactions (A) is an array of unconfirmed transactions
- lastBlock (S) is the last block ID on the blockchain (applies if requireBlock is provided but not requireLastBlock)
- requestProcessingTime (N) is the API request processing time (in millisec)
Send SPA to an account. POST only.
Request: Refer to Create Transaction Request for common parameters.
- requestType is sendMoney
- amountAPL is the amount (in APL) in the transaction
- recipient is the account ID of the recipient
- recipientPublicKey is the public key of the receiving account (optional, enhances security of a new account)
Get a block object given a block ID or block height.
Request:
- requestType is getBlock
- block is the block ID (optional)
- height is the block height (optional if block provided)
- timestamp is the timestamp (in seconds since the genesis block) of the block (optional if height provided)
- includeTransactions is true to include transaction details (optional)
- includeExecutedPhased is true to include approved and executed phased transactions (optional)
- requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)
- requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)
Response:
- previousBlockHash (S) is the 32-byte hash of the previous block
- payloadLength (N) is the length (in bytes) of all transactions included in the block
- totalAmountAPL (S) is the total amount (in APL) of the transactions in the block
- generationSignature (S) is the 32-byte generation signature of the generating account
- generator (S) is the generating account number
- generatorPublicKey (S) is the 32-byte public key of the generating account
- baseTarget (S) is the base target for the next block generation
- payloadHash (S) is the 32-byte hash of the payload (all transactions)
- generatorSPA (S) is the SPARTA address of the generating account
- nextBlock (S) is the next block ID
- numberOfTransactions (N) is the number of transactions in the block
- blockSignature (S) is the 64-byte block signature
- transactions (A) is an array of transaction IDs or transaction objects
- version (N) is the block version
- totalFeeAPL (S) is the total fee (in APL) of the transactions in the block
- previousBlock (S) is the previous block ID
- cumulativeDifficulty (S) is the cumulative difficulty for the next block generation
- block (S) is the block ID
- height (N) is the zero-based block height
- timestamp (N) is the timestamp (in seconds since the genesis block) of the block
- lastBlock (S) is the last block ID on the blockchain (applies if requireBlock is provided but not requireLastBlock)
- requestProcessingTime (N) is the API request processing time (in millisec)
Get a block ID given a block height.
Request:
- requestType is getBlockId
- height is the block height
- requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)
- requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)
- block (S) is the block ID
- lastBlock (S) is the last block ID on the blockchain (applies if requireBlock is provided but not requireLastBlock)
- requestProcessingTime (N) is the API request processing time (in millisec)
Get blocks from the blockchain in reverse block height order.
Request:
- requestType is getBlocks
- timestamp is the earliest block (in seconds since the genesis block) to retrieve (optional)
- firstIndex is first block to retrieve (optional, default is zero or the last block on the blockchain)
- lastIndex is the last block to retrieve (optional, default is firstIndex + 99)
- includeTransactions is true to include transaction details (optional)
- requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)
- requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)
- blocks (A) is an array of blocks retrieved
- lastBlock (S) is the last block ID on the blockchain (applies if requireBlock is provided but not requireLastBlock)
- requestProcessingTime (N) is the API request processing time (in millisec)
Start or stop forging with an account, or check to see if an account is forging. POST only.
Request:
- requestType is either startForging, stopForging or getForging
- secretPhrase is the secret passphrase of the account (optional for stopForging and getForging if password protected)
- deadline (N) is the estimated time (in seconds since the last block) until the account will forge a block (startForging and getForging only)
- hitTime (N) is the estimated time (in seconds since the genesis block) when the account will forge a block (startForging and getForging only)
- remaining (N) is the deadline less the elapsed time since the last block (getForging only)
- foundAndStopped (B) is true if forging was stopped, false if forging was already stopped (stopForging only)
- account (S) is the account number (getForging only)
- accountSPA (S) is the SPARTA address of the account (getForging only)
- requestProcessingTime (N) is the API request processing time (in millisec)
Returns the next block generators ordered by hit time. The list of currently active forgers is first initialized using the block generators with at least 2 blocks generated within the previous 10,000 blocks, excluding accounts without a public key. The list is updated as new blocks are processed. The results are not 100% correct since previously active generators may no longer be running and new generators won't be known until they generate a block.
Request:
- requestType is getNextBlockGenerators
- limit (N) is the number of next block generators to display.
- activeCount (N) is the number of active forging accounts
- lastBlock (S) is the last block ID on the blockchain
-
generators (A) is an array containing the number of next block generators requested
- effectiveBalanceSPA (N) is the balance (in SPA) of the account available for forging
- accountSPA (S) is the SPARTA address of the account
- deadline (N) is the estimated time (in seconds since the last block) until the account will forge a block
- account (S) is the account number
- hitTime (N) is the estimated time (in seconds since the genesis block) when the account will forge a block
- requestProcessingTime (N) is the API request processing time (in millisec)
- timestamp (N) is the timestamp (in seconds since the genesis block) when the request was executed
- height (N) is the height of the blockchain
Add a peer to the list of known peers and attempt to connect to it. POST only.
Request:
- requestType is addPeer
- peer is the IP address or domain name of the peer (plus optional port)
- isNewlyAdded is true if the peer was not already known, omitted otherwise
Blacklist a remote node from the UI, so it won't be used when in roaming and light client modes. POST only.
Request:
- requestType is blacklistAPIProxyPeer
- peer is the IP address or domain name of the peer (plus optional port)
- adminPassword is a string with the admin password (optional)
- done (B) is true if the peer is blacklisted
- requestProcessingTime (N) is the API request processing time (in millisec)
Blacklist a peer for the default blacklisting period. POST only.
Request:
- requestType is blacklistPeer
- peer is the IP address or domain name of the peer (plus optional port)
- done (B) is true if the peer is blacklisted
- requestProcessingTime (N) is the API request processing time (in millisec)
Get all peers that have sent a request to this peer in the last 30 minutes.
Request:
- requestType is getInboundPeers
- includePeerInfo is true to include peer information, otherwise include only the address (optional)
- peers (A) is an array of peer addresses or peer objects depending on includePeerInfo
- requestProcessingTime (N) is the API request processing time (in millisec)
Get hostname and address of the requesting node.
Request:
- requestType is getMyInfo
- host (S) is the node hostname
- address (S) is the node address
- requestProcessingTime (N) is the API request processing time (in millisec)
Get information about a given peer.
Request:
- requestType is getPeer
- peer is the IP address or domain name of the peer (plus optional port)
- hallmark (S) is the hex string of the peer's hallmark, if it is defined
- downloadedVolume (N) is the number of bytes downloaded by the peer
- address (S) the IP address or DNS name of the peer
- weight (N) is the peer's weight value
- uploadedVolume (N) is the number of bytes uploaded by the peer
- version (S) is the version of the software running on the peer
- platform (S) is a string representing the peer's platform
- lastUpdated (N) is the timestamp (in seconds since the genesis block) of the last peer status update
- blacklisted (B) is true if the peer is blacklisted
- services (A) is an array of strings with the services the node provides
- blacklistingCause (S) is the cause of blacklisting (if blacklisted is true)
- announcedAddress (S) is the name that the peer announced to the network (could be a DNS name, IP address, or any other string)
- application (S) is the name of the software application, typically NRS
- state (N) defines the state of the peer: 0 for NON_CONNECTED, 1 for CONNECTED, or 2 for DISCONNECTED
- shareAddress (B) is true if the address is allowed to be shared with other peers
- inbound (B) is true if the peer has made a request to this node
- inboundWebSocket (B) is true if an inbound websocket has been established from this node
- outboundWebSocket (B) is true if an outbound websocket has been established to this node
- lastConnectAttempt (B) is the timestamp (in seconds since the genesis block) of the last connection attempt to the peer
- requestProcessingTime (N) is the API request processing time (in millisec)
Get a list of peer IP addresses.
Request:
- requestType is getPeers
- active is true for active (not NON_CONNECTED) peers only (optional, if true overrides state)
- state is the state of the peers, one of NON_CONNECTED, CONNECTED, or DISCONNECTED (optional)
- includePeerInfo is true to include peer detail as in Get Peer
- service to filter on a specific service
Response:
- peers (A) is an array of peer addresses
- requestProcessingTime (N) is the API request processing time (in millisec)
Set the remote node to use when in roaming and light client modes. POST only.
Request:
- requestType is setAPIProxyPeer
- peer is the IP address or domain name of the peer (plus optional port)
- adminPassword is a string with the admin password (optional)
- downloadedVolume (N) is the number of bytes downloaded by the peer
- address (S) the IP address or DNS name of the peer
- weight (N) is the peer's weight value
- uploadedVolume (N) is the number of bytes uploaded by the peer
- version (S) is the version of the software running on the peer
- platform (S) is a string representing the peer's platform
- blockchainState (S) is a string describing the state of the blockchain in the peer
- lastUpdated (N) is the timestamp (in seconds since the genesis block) of the last peer status update
- blacklisted (B) is true if the peer is blacklisted
- services (A) is an array of strings with the services the node provides
- apiPort (N) is the API access port of the peer
- apiSSLPort (N) is the SSL API access port of the peer
- blacklistingCause (S) is the cause of blacklisting (if blacklisted is true)
- announcedAddress (S) is the name that the peer announced to the network (could be a DNS name, IP address, or any other string)
- application (S) is the name of the software application, typically NRS
- state (N) defines the state of the peer: 0 for NON_CONNECTED, 1 for CONNECTED, or 2 for DISCONNECTED
- shareAddress (B) is true if the address is allowed to be shared with other peers
- inbound (B) is true if the peer has made a request to this node
- inboundWebSocket (B) is true if an inbound websocket has been established from this node
- outboundWebSocket (B) is true if an outbound websocket has been established to this node
- lastConnectAttempt (B) is the timestamp (in seconds since the genesis block) of the last connection attempt to the peer
- requestProcessingTime (N) is the API request processing time (in millisec)
Create, modify or remove an event listener which can report server events via Event Wait. POST only.
Request:
- requestType is eventRegister
-
event is one of multiple server events from the following list of event names: (optional, default is all possible events)
- Block.BLOCK_GENERATED
- Block.BLOCK_POPPED
- Block.BLOCK_PUSHED
- Peer.ADD_INBOUND
- Peer.ADDED_ACTIVE_PEER
- Peer.BLACKLIST
- Peer.CHANGED_ACTIVE_PEER
- Peer.DEACTIVATE
- Peer.NEW_PEER
- Peer.REMOVE
- Peer.REMOVE_INBOUND
- Peer.UNBLACKLIST
- Transaction.ADDED_CONFIRMED_TRANSACTIONS
- Transaction.ADDED_UNCONFIRMED_TRANSACTIONS
- Transaction.REJECT_PHASED_TRANSACTION
- Transaction.RELEASE_PHASED_TRANSACTION
- Transaction.REMOVE_UNCONFIRMED_TRANSACTIONS
- event is one of multiple server events (optional)
- add is true to add events to an existing listener (optional, omit if remove is true)
- remove is true to remove events from an existing listener (optional, omit if add is true)
- requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)
- requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)
Note: An event listener is automatically deactivated whenever all registered events are removed or if Event Wait is not called frequently enough, according to the spa.apiEventTimeout property. The timeout is not precise; the removal process runs every spa.apiEventTimeout / 2 seconds, so that many extra seconds may elapse before removal; the first Event Wait call should be made immediately after registration to avoid deactivation.
Note: Each API user (with a unique address) can create only one event listener. When a new one is created, it will replace an existing one. The maximum number of unique users is controlled by the spa.maxEventUsers property.
Response:
- registered is true if the operation completed successfully
- lastBlock (S) is the last block ID on the blockchain (applies if requireBlock is provided but not requireLastBlock)
- requestProcessingTime (N) is the API request processing time (in millisec)
Wait for events registered with Event Register. POST only.
Request:
- requestType is eventWait
- timeout is the amount of time (in seconds) to wait for an event before the call returns (optional, default and maximum is the spa.apiEventTimeout property)
- requireBlock is the block ID of a block that must be present in the blockchain during execution (optional)
- requireLastBlock is the block ID of a block that must be last in the blockchain during execution (optional)
Response:
-
events (A) is an array of event objects each of which has the following fields:
- name (S) is the name of the event
-
ids (A) is an array of identifiers, depending on the type of event:
- block string identifier (S) for a block event
- peer network address (S) for a peer event
- transaction string identifier (S) for a transaction event
- lastBlock (S) is the last block ID on the blockchain (applies if requireBlock is provided but not requireLastBlock)
- requestProcessingTime (N) is the API request processing time (in millisec)
Get the blockchain status.
Request:
- requestType is getBlockchainStatus
- currentMinRollbackHeight (N) is the current minimum rollback height
- numberOfBlocks (N) is the number of blocks in the blockchain (height + 1)
- isTestnet (B) is true if the node is connected to testnet, false otherwise
- requestProcessingTime (N) is the API request processing time (in millisec)
- version (S) is the application version
- maxRollback (N) is the value of the spa.maxRollback property
- lastBlock (S) is the last block ID on the blockchain
- application (S) is application name, typically NRS
- isScanning (B) is true if the blockchain is being scanned by the application, false otherwise
- isDownloading (B) is true if a download is in progress, false otherwise; true when a batch of more than 10 blocks at once has been downloaded from a peer, reset to false when an attempt to download more blocks from a peer does not result in any new blocks
- cumulativeDifficulty (S) is the cumulative difficulty
- lastBlockchainFeederHeight (N) is the height of the last blockchain of greatest cumulative difficulty obtained from a peer
- time (N) is the current timestamp (in seconds since the genesis block)
- lastBlockchainFeeder (S) is the address or announced address of the peer providing the last blockchain of greatest cumulative difficulty
- blockchainState (S) Current state of this node's blockchain (UP_TO_DATE or DOWNLOADING)
Get all defined constants.
Request:
- requestType is getConstants
- maxBlockPayloadLength (N) is the maximum block payload length (in bytes)
- maxArbitraryMessageLength (N) is the maximum length (in bytes) of an arbitrary message
- epochBeginning (N) is the time in milliseconds when genesis block was created
- genesisAccountId (S) is the genesis account number
- genesisBlockId (S) is the genesis block ID
- transactionTypes (A) is an array of defined transaction types and subtypes (refer to the example below)
- transactionSubTypes (A) is an array of defined transaction subtypes and subtypes (refer to the example below)
- peerStates (A) is an array of defined peer states (refer to the example below)
- currencyTypes (A) is an array of defined currency types (refer to the example below)
- disabledAPIs (A) is an array of configured disabled apis (refer to the example below)
- apiTags (A) is an array of defined api tags (refer to the example below)
- disabledAPITags (A) is an array of configured disabled api tags (refer to the example below)
- requestTypes (A) is an array of decined request types (refer to the example below)
Get the state of the server node and network.
Request:
- requestType is getState
- includeCounts is true if the fields beginning with numberOf... are to be included (optional); password protected if true.
- numberOfPeers (N) is the number of known peers on the network
- numberOfUnlockedAccounts (N) is the number of unlocked accounts on this node
- numberOfTransfers (N) is the number of AE transfers in the blockchain
- numberOfTransactions (N) is the number of transactions in the blockchain
- maxMemory (N) is the maximum amount of memory the node may use (in Bytes)
- maxRollback (N) is the value of the spa.maxRollback property
- isDownloading (B) is true if a download is in progress, false otherwise; true when a batch of more than 10 blocks at once has been downloaded from a peer, reset to false when an attempt to download more blocks from a peer does not result in any new blocks
- isScanning (B) is true if this node is scanning the blockchain, false otherwise
- cumulativeDifficulty (S) is the current cumulative forging difficulty
- freeMemory (N) is the amount of free memory on this node (in Bytes)
- peerPort (N) is the port used for connecting to peers
- availableProcessors (N) is the number of processors on this node
- numberOfAccounts (N) is the number of accounts in the blockchain
- needsAdminPassword (B) is true if the spa.disableAdminPassword property is false
- currentMinRollbackHeight (N) is the current minimum rollback height
- numberOfBlocks (N) is the number of blocks (height + 1) in the blockchain
- isTestnet (B) is true if the node is connected to testnet, false otherwise
- requestProcessingTime (N) is the API request processing time (in millisec)
- version (S) is the software version on this node
- lastBlock (S) is the last block address
- totalMemory (N) is the amount of memory this node is using (in Bytes)
- application (S) is the name of the software running on this node (typically NRS)
- time (N) is the current node time (in seconds since the genesis block)
- isOffline (B) is true if this node is connected to other peers, false otherwise
Get the current time.
Request:
- requestType is getTime
- time (N) is the current time (in seconds since the genesis block).
- requestProcessingTime (N) is the API request processing time (in millisec)