-
Notifications
You must be signed in to change notification settings - Fork 45
Common API Specification
Sheldon edited this page Nov 18, 2019
·
1 revision
All supported API can be seen by Swagger Client. We can open browser and input URL with http://<node ip>:9922 to use Swagger, for example, http://test.v.systems:9922.
Calling method POST /vsys/broadcast/payment
JSON request schema
{
"timestamp": (Type: Number) timestamp with nanosecond
"amount": (Type: Number) amount of payment with minimum unit (1 VSYS = 10^8)
"fee": (Type: Number) transaction fee. The unit is minimum unit. Currently the payment transaction fee is fixed value 0.1 VSYS = 10000000.
"feeScale": (Type: Number) transaction fee scale percentage. Currently it is fixed value 100 (=100%).
"recipient": (Type: String) recipient address with Base58 encoding
"senderPublicKey": (Type: String) sender public key with Base58 encoding
"attachment": (Type: String) payment attachment (limited with 140 bytes) with Base58 encoding.
"signature": (Type: String) signature of this transaction from sender with Base58 encoding
}
Sample Requst
{
"timestamp": 1544083814291691000,
"amount": 100000000,
"fee": 10000000,
"feeScale": 100,
"senderPublicKey": "3orvgyRKf45FRyiCkcA3CzAGDvyEpBpXZzYGEGZnpZK5",
"attachment": "",
"recipient": "ATt6P4vSpBvBTHdV5V9PJEHMFp4msJ1fkkX",
"signature": "t1X2zmw5a2b9iaLgtsHyHKgEmKo6GCFuMFQsZNqj8ZkzpVbRKhWUttqUDfcjzcn5w7VgVVvf8cetr1mh2d2xypQ"
}
JSON response schema
{
"type": (Type: Number) transaction type ID (2 = payment transaction)
"id": (Type: String) transaction ID
"fee": (Type: Number) transaction fee. The unit is minimum unit.
"timestamp": (Type: Number) timestamp with nanosecond
"proofs": (Type: Array of Object) transaction proofs from sender(s)
"recipient": (Type: String) recipient address with Base58 encoding
"feeScale": (Type: Number) transaction fee scale percentage.
"amount": (Type: Number) amount of payment with minimum unit (1 VSYS = 10^8)
"attachment": (Type: String) payment attachment (limited with 140 bytes) with Base58 encoding.
}
Sample Response for success
{
"type": 2,
"id": "EoNQyNouEKg8pDcEEPY2dJL9FMQx61YFk1Sn5EJN8H7K",
"fee": 10000000,
"timestamp": 1544083814291691000,
"proofs": [
{
"proofType": "Curve25519",
"address": "ATwi9fALjKTPfvSe7qJ2418huNd6SSYRuQu",
"publicKey": "3orvgyRKf45FRyiCkcA3CzAGDvyEpBpXZzYGEGZnpZK5",
"signature": "t1X2zmw5a2b9iaLgtsHyHKgEmKo6GCFuMFQsZNqj8ZkzpVbRKhWUttqUDfcjzcn5w7VgVVvf8cetr1mh2d2xypQ"
}
],
"recipient": "ATt6P4vSpBvBTHdV5V9PJEHMFp4msJ1fkkX",
"feeScale": 100,
"amount": 100000000,
"attachment": ""
}
Sample Response for fail
{
"error": 102,
"message": "invalid address"
}
Calling method GET /transactions/info/{id}
JSON response schema
{
"type": (Type: Number) transactions type ID (2 = payment, 3 = lease, 4 = cancel lease, 5 = minting, 8 = register contract, 9 = execute contract funtion)
"id": (Type: String) transactions ID
"fee": (Type: Number) transaction fee. The unit is minimum unit.
"timestamp": (Type: Number) timestamp with nanosecond
"proofs": (Type: Array of Object) transaction proofs from sender(s)
"recipient":(Type: String) recipient address with Base58 encoding
"feeScale": (Type: Number) transaction fee scale percentage
"amount": (Type: Number) amount of transaction with minimum unit (1 VSYS = 10^8)
"attachment": (Type: String) transaction attachment (limited with 140 bytes) with Base58 encoding.
"status": (Type: String) transaction result. If success, it will show "Success". Other status will regards as fail.
"feeCharged": (Type: Number) the actual charged transaction fee
"height": (Type: Number) the block height which store this transaction
"leaseStatus": (Type: String) if it is lease transation (type = 3), the status will show in this field.
"leaseId": (Type: String) if it is cancel lease transation (type = 4), the lease id will show in this field.
"lease": (Type: Object) if it is cancel lease transation (type = 4), the lease detail will show in this field.
}
Sample Response for success
{
"type": 2,
"id": "EhmLJA5H5LG8a69eQEpKtbPZf8KGMCSH5w4MPDMoaGR3",
"fee": 10000000,
"timestamp": 1562339456608000000,
"proofs": [
{
"proofType": "Curve25519",
"address": "ATwi9fALjKTPfvSe7qJ2418huNd6SSYRuQu",
"publicKey": "EaxkrqBySftSD7M9WJiBKxLPjugtjUqDCJK3Lf3aTq1E",
"signature": "4zxLLLpBmERW7zwTTyRamrQDgeQPSe2gwFwsUKoVtBvsPjz73n2fHFLBxAyYtJop3yrKs9LFiirNZ5VUDahD4ao7"
}
],
"recipient": "AU83FKKzTYCue5ZQPweCzJ68dQE4HtdMv5U",
"feeScale": 100,
"amount": 50000000,
"attachment": "",
"status": "Success",
"feeCharged": 10000000,
"height": 5414065
}
Sample Response for fail
{
"status": "error",
"details": "Transaction is not in blockchain"
}
PS: If a transaction if packaged into a block from Unconfirmed transaction pool, this API will return the height of transaction. We can confirm a transaction if node block height is 31 blocks higher than the height of transaction.
Calling method GET /transactions/address/{address}/limit/{limit}
JSON response schema type is Array of Array of Object. And schema of Object is as the following:
{
"type": (Type: Number) transactions type ID (2 = payment, 3 = lease, 4 = cancel lease, 5 = minting, 8 = register contract, 9 = execute contract funtion)
"id": (Type: String) transactions ID
"fee": (Type: Number) transaction fee. The unit is minimum unit.
"timestamp": (Type: Number) timestamp with nanosecond
"proofs": (Type: Array of Object) transaction proofs from sender(s)
"recipient":(Type: String) recipient address with Base58 encoding
"feeScale": (Type: Number) transaction fee scale percentage
"amount": (Type: Number) amount of transaction with minimum unit (1 VSYS = 10^8)
"attachment": (Type: String) transaction attachment (limited with 140 bytes) with Base58 encoding.
"status": (Type: String) transaction result. If success, it will show "Success". Other status will regards as fail.
"feeCharged": (Type: Number) the actual charged transaction fee
"height": (Type: Number) the block height which store this transaction
"leaseStatus": (Type: String) if it is lease transation (type = 3), the status will show in this field.
"leaseId": (Type: String) if it is cancel lease transation (type = 4), the lease id will show in this field.
"lease": (Type: Object) if it is cancel lease transation (type = 4), the lease detail will show in this field.
}
Sample Response for success
[
[
{
"type": 2,
"id": "EoNQyNouEKg8pDcEEPY2dJL9FMQx61YFk1Sn5EJN8H7K",
"fee": 10000000,
"timestamp": 1544083814291691000,
"proofs": [
{
"proofType": "Curve25519",
"address": "ATwi9fALjKTPfvSe7qJ2418huNd6SSYRuQu",
"publicKey": "3orvgyRKf45FRyiCkcA3CzAGDvyEpBpXZzYGEGZnpZK5",
"signature": "t1X2zmw5a2b9iaLgtsHyHKgEmKo6GCFuMFQsZNqj8ZkzpVbRKhWUttqUDfcjzcn5w7VgVVvf8cetr1mh2d2xypQ"
}
],
"recipient": "ATt6P4vSpBvBTHdV5V9PJEHMFp4msJ1fkkX",
"feeScale": 100,
"amount": 100000000,
"attachment": "",
"status": "Success",
"feeCharged": 10000000
},
{
"type": 4,
"id": "FiMiErppddPfFCmehu1ziKNTqyzBFsLRj6gh9y45JKKD",
"fee": 10000000,
"timestamp": 1543569020372515800,
"proofs": [
{
"proofType": "Curve25519",
"publicKey": "B2Khd89jtnpuzGdnyGRcnKycZMBCo6PsotFcWWi1wMDV",
"signature": "2hpsVXZVs2Wmg5ixD8PqvMJoC3CAqgTqvapYkuFAxbLvoyXRu45q9HXZQyqCzHeiHocGFM8phPkmDuM566Xu59em"
}
],
"feeScale": 100,
"leaseId": "D8mGb2YSGyKr5Q3WATnpQP8JvyDdteXwieo5khwsTEyY",
"status": "Success",
"feeCharged": 10000000,
"lease": {
"type": 3,
"id": "D8mGb2YSGyKr5Q3WATnpQP8JvyDdteXwieo5khwsTEyY",
"fee": 10000000,
"timestamp": 1543569009108564000,
"proofs": [
{
"proofType": "Curve25519",
"publicKey": "B2Khd89jtnpuzGdnyGRcnKycZMBCo6PsotFcWWi1wMDV",
"signature": "8TDUgnkNbrPL6VMLFzDnhZvABfRqXitFX46mmvpohsdeRHKaNtWCs5C7m6avaUH2NjiFS7jGFov1CY5s3W8Zc5V"
}
],
"amount": 100000000,
"recipient": "AU6GsBinGPqW8zUuvmjgwpBNLfyyTU3p83Q",
"feeScale": 100
}
},
{
"type": 3,
"id": "D8mGb2YSGyKr5Q3WATnpQP8JvyDdteXwieo5khwsTEyY",
"fee": 10000000,
"timestamp": 1543569009108564000,
"proofs": [
{
"proofType": "Curve25519",
"publicKey": "B2Khd89jtnpuzGdnyGRcnKycZMBCo6PsotFcWWi1wMDV",
"signature": "8TDUgnkNbrPL6VMLFzDnhZvABfRqXitFX46mmvpohsdeRHKaNtWCs5C7m6avaUH2NjiFS7jGFov1CY5s3W8Zc5V"
}
],
"amount": 100000000,
"recipient": "AU6GsBinGPqW8zUuvmjgwpBNLfyyTU3p83Q",
"feeScale": 100,
"status": "Success",
"feeCharged": 10000000
}
]
]
Sample Response for fail
{
"error": 102,
"message": "invalid address"
}
Calling method POST /leasing/broadcast/lease
JSON request schema
{
"timestamp": (Type: Number) timestamp with nanosecond
"amount": (Type: Number) lease amount with minimum unit (1 VSYS = 10^8)
"fee": (Type: Number) transaction fee. The unit is minimum unit. Currently the payment transaction fee is fixed value 0.1 VSYS = 10000000.
"feeScale": (Type: Number) transaction fee scale percentage. Currently it is fixed value 100 (=100%).
"recipient": (Type: String) recipient address with Base58 encoding
"senderPublicKey": (Type: String) sender public key with Base58 encoding
"signature": (Type: String) signature of this transaction from sender with Base58 encoding
}
Sample Requst
{
"timestamp": 1563963312897000000
"amount": 100000000,
"fee": 10000000,
"feeScale": 100,
"senderPublicKey": "DREQ2s3dQzaKTsvnmKWTnj59ptM1NzXwmap8jYVdPeLC",
"recipient": "ATt6P4vSpBvBTHdV5V9PJEHMFp4msJ1fkkX",
"signature": "54Z48cQ6XEtpmZaN1zXPiL4JqDCjRytc4UkYTHnH2bPZiKm3iyTVhkRacrAADb3jCP2sBQi4cxuZCxQnWYnvRao2"
}
JSON response schema
{
"type": (Type: Number) transactions type ID (3 = lease)
"id": (Type: String) transactions ID
"fee": (Type: Number) transaction fee. The unit is minimum unit.
"timestamp": (Type: Number) timestamp with nanosecond
"proofs": (Type: Array of Object) transaction proofs from sender(s)
"recipient": (Type: String) recipient address with Base58 encoding
"feeScale": (Type: Number) transaction fee scale percentage.
"amount": (Type: Number) lease amount with minimum unit (1 VSYS = 10^8)
}
Sample Response for success
{
"type": 3,
"id": "F1hy4f4GGJzgjZm4CB6cgRSWTFgTYjwfe8tmYL2sgXqE",
"fee": 10000000,
"timestamp": 1563963339028000000,
"proofs": [
{
"proofType": "Curve25519",
"publicKey": "DREQ2s3dQzaKTsvnmKWTnj59ptM1NzXwmap8jYVdPeLC",
"signature": "54Z48cQ6XEtpmZaN1zXPiL4JqDCjRytc4UkYTHnH2bPZiKm3iyTVhkRacrAADb3jCP2sBQi4cxuZCxQnWYnvRao2"
}
],
"amount": 100000000,
"recipient": "AU83FKKzTYCue5ZQPweCzJ68dQE4HtdMv5U",
"feeScale": 100,
"status": "Success",
"feeCharged": 10000000,
"height": 5950151
}
Sample Response for fail
{
"error": 102,
"message": "invalid address"
}
Calling method POST /leasing/broadcast/cancel
JSON request schema
{
"timestamp": (Type: Number) timestamp with nanosecond
"fee": (Type: Number) transaction fee. The unit is minimum unit. Currently the payment transaction fee is fixed value 0.1 VSYS = 10000000.
"feeScale": (Type: Number) transaction fee scale percentage. Currently it is fixed value 100 (=100%).
"txId": (Type: String) the lease transaction ID that you want to cancel
"senderPublicKey": (Type: String) sender public key with Base58 encoding
"signature": (Type: String) signature of this transaction from sender with Base58 encoding
}
Sample Requst
{
"senderPublicKey": "DREQ2s3dQzaKTsvnmKWTnj59ptM1NzXwmap8jYVdPeLC",
"txId": "AzutjAvyW47L4poTUvxZB1T9nmwyaKbGtZdjX4hDKNeN",
"timestamp": 1563963377829000000,
"signature": "t2GmqG5cYHDAHzwZsVoQ6oXnFyASdAFGjjRbc1QwHrz7k9SJHHUmNJLd2ExciR5p2hwncC6MoXs8FGVb28Jet51",
"fee": 10000000,
"feeScale": 100
}
JSON response schema
{
"type": (Type: Number) transactions type ID (4 = cancel lease)
"id": (Type: String) transactions ID of cancel lease
"fee": (Type: Number) transaction fee. The unit is minimum unit
"timestamp": (Type: Number) timestamp with nanosecond
"proofs": (Type: Array of Object) transaction proofs from sender(s)
"leaseId": (Type: String) transactions ID of lease
"feeScale": (Type: Number) transaction fee scale percentage
}
Sample Response for success
{
"type" : 4,
"id" : "8WFK8hfkogaJGzsmCpZp7NTWFGM8GupWbojz7kMHj9qb",
"fee" : 10000000,
"timestamp" : 1564395560154000000,
"proofs" : [ {
"proofType" : "Curve25519",
"publicKey" : "DREQ2s3dQzaKTsvnmKWTnj59ptM1NzXwmap8jYVdPeLC",
"signature" : "5mmqXKLdqhBayuvueoJJv39HiqyNZKVP9A6HUbox4fGGGxZmfG4GefPmuQ6NzN49b2TKDyo1T4XZgw6vY9AVg9Qt"
} ],
"feeScale" : 100,
"leaseId" : "GRNXBduX4goyePH8HyNRZZT4wyWTHoEVHPLJQ1p8Mn8V"
}
Sample Response for fail
{
"error": 102,
"message": "invalid address"
}
Calling method GET /blocks/height
JSON response schema
{
"height" (Type: Number) block height
}
Sample Response
{
"height": 14554
}
Calling method GET /blocks/at/{height}
JSON response schema
{
"version" (Type: Number) Block version
"timestamp" (Type: Number) the block generation timestamp
"reference" (Type: String) last block signature with Base58 encoding
"SPOSConsensus" (Type: Object) consensus mechanism
"resourcePricingData" (Type: Number)
"TransactionMerkleRoot":(Type: String)
"transactions": (Type: Array of Object) the transactions that packed in this block
"generator": (Type: String) the address that create this block
"signature": (Type: String) the signature of this block. It is also the ID of this block.
"fee": (Type: Number) the fee that the generating block cost.
"blocksize": (Type: Number) block size in Byte
"height": (Type: Number) block height
"transaction count": (Type: Number) the transaction number that this block contains.
}
Sample Response for success
{
"version": 1,
"timestamp": 1543310672000509700,
"reference": "3Fb832ZiXQpbpWFn2aFwBqtyN4xKsfpmB4Zbj2tRJdtGsBhj8jiNJxjJJkHqGcfG7ycZCLFXjxodx9c7GmrbRg5X",
"SPOSConsensus": {
"mintTime": 1543310672000000000,
"mintBalance": 0
},
"resourcePricingData": {
"computation": 0,
"storage": 0,
"memory": 0,
"randomIO": 0,
"sequentialIO": 0
},
"TransactionMerkleRoot": "8Rfgrmwz9zV7ffCgqPkgViNjPnjyJxZWufCetgWprJUZ",
"transactions": [
{
"type": 5,
"id": "HfoEiQgV6YVPcCRFbVLsuT1EBE6uVD96vG3T6BUPA4mR",
"recipient": "ARCt4ovNZVZEP3RvB9txQZF923kxXXxuBzB",
"timestamp": 1543310672000509700,
"amount": 3600000000,
"currentBlockHeight": 500,
"status": "Success",
"feeCharged": 0
}
],
"generator": "AR9fDBBdQzeGmQY2ZikX2yUZMEMyjKEC5EW",
"signature": "3REE8WZCG2QedSot75rcGq78wsjcMbybLTgjvSLXKJHKtDshmpkUmFsVnzgrcHmo2ZBhSRa3zSsJm8GjPVCEVmSd",
"fee": 0,
"blocksize": 330,
"height": 500,
"transaction count": 1
}
Sample Response for fail
{
"error": 301,
"message": "block does not exist"
}
Calling method GET /addresses/balance/details/{address}
JSON response schema
{
'address': (Type: String) Base58 address of account
'regular': (Type: Number) regular balance
'available': (Type: Number) available balance (regular - leased out)
'effective': (Type: Number) effective balance (regular - leases out + leased in)
'mintingAverage': (Type: Number) MAB value (for minter used)
'height': (Type: Number) the height of node when enquiry this balance
}
Sample Response for success
{
'address': 'AU8R9ri7eG968zuJuLQVLMiUzRNXvQwNPwE',
'regular': 109010000000,
'available': 108910000000,
'effective': 108910000000,
'mintingAverage': 108909964800,
'height': 643936
}
Sample Response for fail
{
"error": 102,
"message": "invalid address"
}
| Error ID | Message |
|---|---|
| 1 | failed to parse json message |
| 2 | Provided API key is not correct |
| 10 | Too big sequences requested |
| 101 | invalid signature |
| 102 | invalid address |
| 103 | invalid seed |
| 104 | invalid amount |
| 105 | invalid fee |
| 106 | invalid sender |
| 107 | invalid recipient |
| 108 | invalid public key |
| 109 | argument is not a number |
| 110 | invalid message |
| 111 | invalid name |
| 112 | State check failed. Reason: XXXXX |
| 113 | overflow error |
| 114 | Transaction to yourself |
| 115 | no private key for sender address in wallet |
| 117 | invalid db key |
| 118 | The XXXX is not a valid utf8 string |
| 119 | Invalid Proof Bytes |
| 120 | Invalid Proof Length |
| 121 | Invalid Proof Type |
| 122 | Invalid Contract |
| 123 | Invalid DataEntry |
| 124 | Invalid DataEntry Length |
| 125 | Invalid Contract Address |
| 126 | Invalid Token Index |
| 301 | block does not exist |
| 401 | Contract is not in blockchain |
| 402 | Token is not in blockchain |
| 403 | contract XXXXX already disabled |
| 501 | nameSpace XXXXX is not valid |
| 502 | the entry for XXXXX does not exist for the nameSpace XXXXX |
| 503 | invalid database entry, this entry might be corruptted |
| 504 | invalid database datatype XXXX |
| 505 | The data is too long for database put. |