Skip to main content

Locus JSON-RPC

What is JSON RPC?

JSON-RPC is a protocol where the client sends a request message in JSON format to the node, which processes it and returns the result in a JSON format response message.

It stands for Remote Procedure Call (RPC) protocol, which is a method for communication.

Locus Chain RPC

Locus Chain nodes provide a JSON-RPC API. Through nodes run by individuals or provided by some public services, users can easily query information from the blockchain network.

Call

Simple Query RPC Call

You can receive the result with a single call.

RPC call to create Tx

If the parameter includes 'Sig', this is an RPC for creating a Tx. Call the same RPC twice. Proceed in 4 steps as follows.

  • [STEP1: 1st Call] Receive Tx and Hash from the node.
  • [STEP2: Tx Verify] Verify the received Tx with the VerifyTx function of the Locus Library.
  • [STEP3: Sign] If there is no problem with the Tx, sign it through the Locus Library or Wallet.
  • [STEP4: 2nd Call] Add the signature to the parameter of the first call and make the second call to create the Tx.

RPC Call Example

{
"jsonrpc": "2.0",
"method": "locus_getAccountDetail",
"params": [{ "account": "D4YLP5B3NC3RWVXYDWFPCT6IG2ASCVP32ANLOAD73I" }],
"id": 1
}

Common Response Format

The basic response value has the following format. The result value changes depending on the called Function.

Success

{
"jsonrpc": "2.0",
"id": 1, // int
"result": {} // any
}

Failure

{
"jsonrpc": "2.0",
"id": 1,
"error": {
"code": 1, // int
"message": "" // string
}
}

Function List


locus_echo

It can be used to check if the node responds correctly to RPC calls. The current time is added to the input value and returned in the response.

Request

KeyTypeDescription
strstringString

Response

KeyTypeDescription
-stringInput string + current time

locus_getSyncState

To receive current synchronization status of the node.

Request

[None]

Response

KeyTypeDescription
syncStatestringNODE_STATE_IN_INIT
NODE_STATE_IN_SYNC
NODE_STATE_IN_RESYNC
NODE_STATE_SYNC_COMPLETE
NODE_STATE_STABLE
Unknown NodeState

locus_getGenesisAccount

Retrieve the address of the Genesis account.

Request

[None]

Response

KeyTypeDescription
genesisbase32Genesis account address

locus_openAccount

Register the account on the Locus Chain network.

Request

KeyTypeDescription
accountbase32Target account address
senderbase32Account that sent the coin
indexintHeight of the Tx that sent coin
args[]stringArguments
pkbase32Normal public key
keySignbase32Key signature
mpkbase32Master public key
signbase64Signature
signedHeightintsignedHeight from the 1st response

Response

KeyTypeDescription
hashbase64Tx Hash
txobjectCreated Tx
successboolSuccess
signedHeightintSigned tx height
feeTypeintFee Type (AUTO:0, GRANT_ONLY:1)

locus_becomeHost

Set the specified account as host for the node. The specified account should have no guests, and the node must be an empty node without a host.

Request

KeyTypeDescription
accountbase32Account to be the host
signbase64Signature
signedHeightintsignedHeight from the 1st response

Response

KeyTypeDescription
hashbase64Tx Hash
txobjectCreated Tx
successboolSuccess
signedHeightintSigned tx height
feeTypeintFee Type (AUTO:0, GRANT_ONLY:1)

locus_becomeGuest

Set the specified account as guest for the node. The specified account should have no guests, and the node must have an existing host.

Request

KeyTypeDescription
accountbase32Account to be the guest
signbase64Signature
signedHeightintsignedHeight from the 1st response

Response

KeyTypeDescription
hashbase64Tx Hash
txobjectCreated Tx
successboolSuccess
signedHeightintSigned tx height
feeTypeintFee Type (AUTO:0, GRANT_ONLY:1)

locus_changeKey

Change the account's normal key.

Request

KeyTypeDescription
accountbase32Account to change key
masterPkeybase32Master public key
newNormalPkeybase32New Normal public key
signByMasterKeybase64Value signed of New Normal public key with Master public key
signbase64Signature
signedHeightintSigned height

Response

KeyTypeDescription
hashbase64Tx Hash
txobjectCreated Tx
successboolSuccess
signedHeightintSigned tx height
feeTypeintFee Type (AUTO:0, GRANT_ONLY:1)

locus_transferCoin

Send coins to another account.

Request

KeyTypeDescription
frombase32Sender Account
tobase32Receiver Account
amountstringAmount to send
signbase64Signature
signedHeightintsignedHeight from the 1st response
feeTypeintFee Type (AUTO:0, GRANT_ONLY:1)

Response

KeyTypeDescription
hashbase64Tx Hash
txobjectCreated Tx
successboolSuccess
signedHeightintSigned tx height
feeTypeintFee Type (AUTO:0, GRANT_ONLY:1)

locus_getTx

Retrieve the Tx information for a specific Height of the account.

Request

KeyTypeDescription
accountbase32Account
heightintHeight of Account

Response

KeyTypeDescription
txstringTx Information

locus_getAccountHistory

Retrieve the list of Tx for the account.

Request

KeyTypeDescription
accountbase32Account
heightintStart Height to retrieve
If Height is -1, start from the latest Tx.
countintNumber of Tx to retrieve (number of previous Tx from the starting position).

Response

KeyTypeDescription
txs[]stringTx string list

locus_getAccountDetail

Retrieve detailed information of the account.

Request

KeyTypeDescription
accountbase32Account

Response

KeyTypeDescription
identitystringHost : Host account of the node
Guest : Guest account of the node
Neighbor : Neighboring accounts of the shard to which the node belongs. This is the state at the time of the query and may be inaccurate depending on the synchronization status.
no identity : None of above
fromNoAliveboolThis flag becomes true if OpenAccount is done but not yet included in consensus.
balancestringLocus Coin Balance
unactBalancestringBalance unavailable because it is not activated yet
representativebase32Delegated Account (Host Account)
grantuint64Grant possessed
publicKeybase32Account's Normal public key
txChainHeightintAccount's Height
txLinkstringLast Tx link

locus_getWorldRoundStatesList

Retrieve the list of World Round States (WRS).

Request

KeyTypeDescription
roundintStart Round to retrieve
countintNumber to retrieve (previous ones from start), Max 500.

Response

KeyTypeDescription
nextRoundList[]intWRS list

locus_getWorldRoundState

Retrieve detailed information of the World Round State (WRS).

Request

KeyTypeDescription
roundintRound to retrieve

Response

KeyTypeDescription
nextRoundintRound
addShardRoundint0 : No shard splitting planned.
1 : Sharding is required, but the timing has not been determined yet.
2 above: Sharding is planned for the upcoming round.
rootAcctHashstring
worldInfoHashstring
currentHashstring
prevLinkstring
prevNextRoundint
sigHashstringThe hash value of the signature information below. The signature information below may be pruned.
validatorsWeightintTotal sum of the Validator's weights
validators[]types.Validator{Validator's Addr, Weight, Sign}

types.Validator

KeyTypeDescription
addrbase32Validator Address
weightuint16Weight
signstringSignature

locus_getInactiveTxList

Retrieve the list of Tx for the account that has not been activated yet.

Request

KeyTypeDescription
accountbase32Account

Response

KeyTypeDescription
timeOutTxs[]types.ListTxList of Tx that timed out due to the first target not being activated.
txs[]types.ListTxList of Tx with completed consensus on the sender's side.
unconfirmedTxs[]types.ListTxList of Tx awaiting consensus on the sender's side.
pendingTxs[]types.ListTxList of Tx proposed for less than 10 seconds.
unspreadTxs[]types.ListTxUnspread Tx list.
conflictedTxs[]types.ListTxList of conflicting Tx.
contractResultstypes.ContractResultsContract results

types.ListTx

KeyTypeDescription
senderbase32Sender Account
indexintIndex
txstringTx Content
vtxobjectDetailed Tx Info

types.ContractResults

KeyTypeDescription
pending[]types.ListTxList of Tx in Pending state
conflicting[]types.ListTxList of conflicting Tx

locus_getMontInfoList

Retrieve the account's Mont (MOnitoring seNT) list. Only possible for the node's host/guest accounts.

Request

KeyTypeDescription
accountbase32Account

Response

KeyTypeDescription
proofedTxs[]types.MontTxList of Tx with completed consensus on the sender's side.
pendingTxs[]types.MontTxList of Tx that have only been proposed.

types.MontTx

KeyTypeDescription
indexintIndex
txstringTx Content

locus_createToken

Generate System Token. One system token can be created per account.

Request

KeyTypeDescription
accountbase32Account to create token
tokenBalancestringQuantity of tokens to Generate
signbase64Signature
signedHeightintsignedHeight from the 1st response
feeTypeintFee Type (AUTO:0, GRANT_ONLY:1)

Response

KeyTypeDescription
hashbase64Tx Hash
txobjectCreated Tx
successboolSuccess
signedHeightintSigned tx height
feeTypeintFee Type (AUTO:0, GRANT_ONLY:1)

locus_transferToken

Send tokens to another account.

Request

KeyTypeDescription
frombase32Sender Account
tobase32Receiver Account
amountstringAmount to send
tokenAmounts[]types.TokenAmountList of tokens to send
signbase64Signature
signedHeightintsignedHeight from the 1st response
feeTypeintFee Type (AUTO:0, GRANT_ONLY:1)
sourcetypes.SourceSource

types.TokenAmount

KeyTypeDescription
tokenIdstringToken ID
amountTokenstringToken Amount

types.Source

KeyTypeDescription
ownerstringOwner
heightintHeight

Response

KeyTypeDescription
hashbase64Tx Hash
txobjectCreated Tx
successboolSuccess
signedHeightintSigned tx height
feeTypeintFee Type (AUTO:0, GRANT_ONLY:1)

locus_getAccountTokenList

Retrieve the list of tokens owned by the account and their balances.

Request

KeyTypeDescription
accountbase32Account to Retrieve tokens

Response

KeyTypeDescription
tokenListmap[base32]string{"TokenID": Balance}

locus_hasSystemToken

Check if the account has created a system token, and if so, retrieve the token ID.

Request

KeyTypeDescription
accountbase32Account

Response

KeyTypeDescription
havingboolWhether system token exists
tokenIdstringIf having is true, return the System Token ID.

locus_postData

Post the data.

Request

KeyTypeDescription
accountbase32Account
labelintTransactions with the same label are linked within the chain. When verifying the proof for a given Tx, this is used to check if there is a more recent Tx with the same label.
database64Data to be posted
signbase64Signature
signedHeightintsignedHeight from the 1st response
feeTypeintFee Type (AUTO:0, GRANT_ONLY:1)

Response

KeyTypeDescription
hashbase64Tx Hash
txobjectCreated Tx
successboolSuccess
signedHeightintSigned tx height
feeTypeintFee Type (AUTO:0, GRANT_ONLY:1)

locus_readTxListWithProof

Retrieve the list of Tx and Proof together.

Request

KeyTypeDescription
accountbase32Account
baseHeightintStart Height
countuintNumber to retrieve (previous ones from start position).

Response

KeyTypeDescription
accountbase32Account
txs[]stringTx string list
proofstringMerkle Proof of the requested Tx list
checkRoundP1intRound + 1 in which the Proof was generated

locus_verifyTxListWithProof

Verify the proof of the Tx list.

Request

KeyTypeDescription
accountbase32Account
txs[]stringList of Tx to verify
proofMerkleProofMerkle Proof of the list of Tx to verify
checkRoundP1intRound + 1 in which the Proof was generated

Response

KeyTypeDescription
-boolVerification Result

locus_generateLatestStoredDataProof

Generate Proof that specific label's TxPostData is the latest.

Request

KeyTypeDescription
accountbase32Account
heightintHeight of the first TxPostData to generate Proof.

Response

KeyTypeDescription
accountbase32Account
latestProofstringProof that Tx is included in the latest StoredDataHash.

locus_verifyLatestStoredDataProof

Verify the Proof generated by locus_generateLatestStoredDataProof RPC.

Request

KeyTypeDescription
accountbase32Account to generate Proof of Tx list.
latestProofstringProof that Tx is included in the latest StoredDataHash.

Response

KeyTypeDescription
-boolVerification Result

locus_lockStake

Lock the Stake.

Request

KeyTypeDescription
accountbase32Account
vmeIdbase32VME ID
lockAmountuint32Lock Amount (1 UnitStakeLock = 100 Locus)
signbase64Signature
signedHeightintsignedHeight from the 1st response

Response

KeyTypeDescription
hashbase64Tx Hash
txobjectCreated Tx
successboolSuccess
signedHeightintSigned tx height
feeTypeintFee Type (AUTO:0, GRANT_ONLY:1)

locus_unlockStake

Unlock the Stake.

Request

KeyTypeDescription
accountbase32Account
vmeIdbase32VME ID
unlockAmountuint32Unlock Amount (1 UnitStakeLock = 100 Locus)
signbase64Signature
signedHeightintsignedHeight from the 1st response

Response

KeyTypeDescription
hashbase64Tx Hash
txobjectCreated Tx
successboolSuccess
signedHeightintSigned tx height
feeTypeintFee Type (AUTO:0, GRANT_ONLY:1)

locus_provideScript

Deploy the Core Script.

Request

KeyTypeDescription
providerbase32Account to deploy the script
targetbase32The account that will activate the coins or tokens sent by the provider by executing the Core script within the time lock.
targetAfterTimeLockbase32The account that will automatically activate the coins or tokens sent by the provider after the time lock.
timeLockintThe round duration for the time lock, with the current max = 30 and min = 3.
args[]hexArguments to be used when the target executes the provider's script (ScriptSig), with a maximum of 4 arguments allowed.
scriptProvidehexThe provider's script to be executed by the target, with the current MaxSize = 32 bytes.
scriptAccepthexThe script to be executed by the target, with the current MaxSize = 32 bytes.
amountstringThe coin amount that can be activated if the target successfully executes the Core script.
tokenAmounts[]types.TokenAmountThe token amounts that can be activated if the target successfully executes the Core script.

types.TokenAmount

KeyTypeDescription
tokenIdstringToken ID
amountTokenstringToken Amount
signbase64Signature
signedHeightintsignedHeight from the 1st response

Response

KeyTypeDescription
hashbase64Tx Hash
txobjectCreated Tx
successboolSuccess
signedHeightintSigned tx height
feeTypeintFee Type (AUTO:0, GRANT_ONLY:1)

locus_acceptScript

Execute Core Script.

Request

KeyTypeDescription
acceptorbase32The account that will activate the Core script specified as the target in TxProvideScript. Activation is only possible within the time lock.
providerbase32The account that deployed the TxProvideScript.
indexintHeight of LeadTx(TxProvideScript)
args[]hexArguments to be used when the target executes the target's script (ScriptSig), with a maximum of 4 arguments allowed.
signbase64Signature
signedHeightintsignedHeight from the 1st response

Response

KeyTypeDescription
hashbase64Tx Hash
txobjectCreated Tx
successboolSuccess
signedHeightintSigned tx height
feeTypeintFee Type (AUTO:0, GRANT_ONLY:1)

locus_queryAddress

Retrieve the full address with key address.

Request

KeyTypeDescription
addrbase32Key Address

Response

KeyTypeDescription
addrbase32Full Address

locus_accountHeightsToDownload

Get account block height list to download.

Request

KeyTypeDescription
accountbase32Account
heightChunks[]types.HeightChunkHeight Chunk List

types.HeightChunk

KeyTypeDescription
bottomintBottom
topintTop

Response

KeyTypeDescription
heightChunks[]types.HeightChunkHeight Chunk List

locus_accountHeightsToUpload

Get account block height list to upload.

Request

KeyTypeDescription
accountbase32Account
heightChunks[]types.HeightChunkHeight Chunk List

Response

KeyTypeDescription
heightChunks[]types.HeightChunkHeight Chunk List
validTopintValid Top
validBottomintValid Bottom

locus_calculateSpentByExpress

Calculate spent amount by Express.

Request

KeyTypeDescription
accountbase32Account
senderbase32Send Account
sentHeightintsent Height

Response

KeyTypeDescription
amountstringAmount

locus_changeVkey

Change Validator Key (VKey).

Request

KeyTypeDescription
accountbase32Account
signbase64Signature
signedHeightintsignedHeight from the 1st response

Response

KeyTypeDescription
hashbase64Tx Hash
txobjectCreated Tx
successboolSuccess
signedHeightintSigned tx height
feeTypeintFee Type (AUTO:0, GRANT_ONLY:1)

locus_checkAddressExist

Check if the address exists.

Request

KeyTypeDescription
keyAddrbase32Key address

Response

KeyTypeDescription
addrbase32Address
existboolExistence

locus_clientMessage

Send Client Message.

Request

KeyTypeDescription
msgstringMessage

Response

KeyTypeDescription
-anyResult

locus_closeAccount

Close Account.

Request

KeyTypeDescription
frombase32From Account
tobase32To Account
signbase64Signature
signedHeightintsignedHeight from the 1st response

Response

KeyTypeDescription
hashbase64Tx Hash
txobjectCreated Tx
successboolSuccess
signedHeightintSigned tx height
feeTypeintFee Type (AUTO:0, GRANT_ONLY:1)

locus_createAssetObject

Create Asset Object.

Request

KeyTypeDescription
accountbase32Account
assetTypestringAsset Type
amountstringAmount
operatorstringOperator
metaDatastringMetadata
signbase64Signature
signedHeightintsignedHeight from the 1st response
feeTypeintFee Type (AUTO:0, GRANT_ONLY:1)

Response

KeyTypeDescription
hashbase64Tx Hash
txobjectCreated Tx
successboolSuccess
signedHeightintSigned tx height
feeTypeintFee Type (AUTO:0, GRANT_ONLY:1)

locus_createVme

Create VME(Virtual Machine Environment).

Request

KeyTypeDescription
accountbase32Account
sysIdbase32System ID
sysTypestringSystem Type
lockAmountstringLock Amount
signbase64Signature
signedHeightintsignedHeight from the 1st response

Response

KeyTypeDescription
hashbase64Tx Hash
txobjectCreated Tx
successboolSuccess
signedHeightintSigned tx height
feeTypeintFee Type (AUTO:0, GRANT_ONLY:1)

locus_downloadAccountTxs

Download Account Transactions.

Request

KeyTypeDescription
accountbase32Account
heightChunks[]types.HeightChunkHeight Chunk List
heights[]intHeights

Response

KeyTypeDescription
heights[]intHeight List
txs[]stringTx List

locus_findDuplicateSubscriber

Find Duplicate Subscriber.

Request

KeyTypeDescription
publishedstringPublisher

Response

KeyTypeDescription
existboolExistence

locus_getAccountAssetList

Get Account Asset List.

Request

KeyTypeDescription
accountbase32Account
maxCountintMax Count

Response

KeyTypeDescription
assetList[]types.AccountAssetAsset List

types.AccountAsset

KeyTypeDescription
assetIdstringAsset ID
amountstringAmount
objects[]types.AssetObjectAsset Object List
unactAmountstringInactive Amount
unactObjects[]types.AssetObjectInactive Asset Object List

locus_getAccountAssetObject

Get Account Asset Object.

Request

KeyTypeDescription
accountbase32Account
assetId[]stringAsset ID List

Response

KeyTypeDescription
objects[]types.AssetObjectObject List
unactObjects[]types.AssetObjectUnavailable Object List

types.AssetObject

KeyTypeDescription
idstringAsset Object ID
valuestringValue
ownerbase32Owner
operatorbase32Operator
rentStartintRental Start Height
rentEndintRental End Height

locus_getConciseNodeStatus

Get Concise Node Status.

Request

[None]

Response

KeyTypeDescription
nodeIdbase32Node ID
hostbase32Host
reliableboolIs Reliable
roundintRound
epochintEpoch
shardIdintShard ID
networkIdintNetwork ID
totalHeightstringTotal Height
intraPeerCountintIntra Peer Count
interPeerCountintInter Peer Count
syncStatestringSync State
detailStatestringDetail State
presyncStatestringPresync State
buildTimestringBuild Time
rsNextRoundintRS Next Round
wrsNextRoundintWRS Next Round

locus_getNodeStatus

Get Node Status.

Request

[None]

Response

KeyTypeDescription
nodeIdbase32Node ID
baseTimeintBase Time
hostbase32Host
reliableboolIs Reliable
roundTimeintRound Time
roundCycleintRound Cycle
prunedRoundintPruned Round
roundintRound
epochintEpoch
shardIdintShard ID
homeShardIdintHome Shard ID
totalShardintTotal Shard
networkIdintNetwork ID
totalHeightstringTotal Height
intraPeerCountintIntra Peer Count
interPeerCountintInter Peer Count
syncStatestringSync State
detailStatestringDetail State
presyncStatestringPresync State
buildTimestringBuild Time
avgTxTimestringAverage Tx Time
rsNextRoundintRS Next Round
rsfintRSF
vmInfostringVM Info
wrsNextRoundintWRS Next Round
wrsHeightintWRS Height

locus_getOwnerBalance

Get Owner Balance.

Request

[None]

Response

KeyTypeDescription
-[]types.OwnerBalanceOwner Balance List

types.OwnerBalance

KeyTypeDescription
accountstringAccount
balancestringBalance

locus_getRoundState

Get Round State.

Request

KeyTypeDescription
roundintRound

Response

KeyTypeDescription
nextRoundintNext Round
prevNextRoundintPrev Next Round
hashstringHash
totalHeightintTotal Height
proposerbase32Proposer
validatorsWeightintValidators Weight
validators[]types.VoteInfoRPCValidators List
incentiveExistboolIncentive Existence
totalIncentivestringTotal Incentive
startRoundintStart Round
endRoundintEnd Round
newEpochintNew Epoch
newEpochRoundintNew Epoch Round

types.VoteInfoRPC

KeyTypeDescription
addrbase32Validator Address
weightuint16Weight
signstringSignature

locus_getRoundStatesList

Get Round State List.

Request

KeyTypeDescription
roundintRound
countintCount

Response

KeyTypeDescription
-[]types.RoundStateAbstractRound State List

types.RoundStateAbstract

KeyTypeDescription
roundintRound
hashstringHash
totalHeightintTotal Height

locus_getShardOfAccount

Get Account Shard Info.

Request

KeyTypeDescription
accountbase32Account

Response

KeyTypeDescription
shardintShard
acceptableboolAcceptable

locus_makeTxProof

Make Tx Proof.

Request

KeyTypeDescription
accountbase32Account
txs[]stringTx List
countintCount

Response

KeyTypeDescription
accountbase32Account
txs[]stringTx string List
proofstringMerkle Proof of requested Txs
checkRoundP1intRound + 1 where proof created

locus_requestDataTrade

Request Data Trade.

Request

KeyTypeDescription
requesterbase32Requester
dataTypeintData Type
reqHashstringRequest Hash
rewardstringReward
keystringKey
traderbase32Trader
signbase64Signature
signedHeightintsignedHeight from the 1st response

Response

KeyTypeDescription
hashbase64Tx Hash
txobjectCreated Tx
successboolSuccess
signedHeightintSigned tx height
feeTypeintFee Type (AUTO:0, GRANT_ONLY:1)
keystringKey
targetstringTarget

locus_setHost

Set Host.

Request

KeyTypeDescription
accountbase32Account
otpstringOTP

Response

KeyTypeDescription
-boolSuccess status

locus_subscribeAddress

Subscription.

Request

KeyTypeDescription
publishedstringPublisher
addboolAdd status

Response

[None]


locus_transferAssetObject

Transfer Asset Object.

Request

KeyTypeDescription
frombase32Sender Account
tobase32Receiver Account
assetIdstringAsset ID
amountstringAmount
signbase64Signature
signedHeightintsignedHeight from the 1st response
feeTypeintFee Type (AUTO:0, GRANT_ONLY:1)

Response

KeyTypeDescription
hashbase64Tx Hash
txobjectCreated Tx
successboolSuccess
signedHeightintSigned tx height
feeTypeintFee Type (AUTO:0, GRANT_ONLY:1)

locus_transferCoinExpress

Transfer Coin Express.

Request

KeyTypeDescription
frombase32Sender Account
tobase32Receiver Account
amountstringAmount
signbase64Signature
signedHeightintsignedHeight from the 1st response
feeTypeintFee Type (AUTO:0, GRANT_ONLY:1)
sourcetypes.SourceFund Source

types.Source

KeyTypeDescription
ownerstringOwner
heightintHeight

Response

KeyTypeDescription
hashbase64Tx Hash
txobjectCreated Tx
successboolSuccess
signedHeightintSigned tx height
feeTypeintFee Type (AUTO:0, GRANT_ONLY:1)

locus_uploadAccountTxs

Upload Account Transactions.

Request

KeyTypeDescription
accountbase32Account
txs[]stringTx List

Response

KeyTypeDescription
-[]intResult