github.com/0chain/gosdk@v1.17.11/docs/README.md (about) 1 # 0CHAIN REST ENDPOINTS 2 --- 3 4 0Chain rest endpoints can be broadly divided into Wallet Transactions endpoints and Storage Transactions endpoints. Depending on what endpoints you are using, you may want to choose the right SDK. Storage Transactions endpoints are currently supported only on 0Chain's *gosdk* while Wallet Transactions endpoints are supported on both *gosdk* and *js-client-sdk*. 5 6 **Note1:** Not all rest endpoints are supported on all of 0Chain nodes. Some are supported on Miners, and some are on Sharders, while others on Blobbers. The endpoints documentation below clearly mentions that. 7 8 9 ## ENDPOINT: `/v1/client/put` 10 11 **Purpose** To register a wallet on Blockchain 12 13 **METHOD** POST 14 15 **Send To** Miners 16 17 **Input** 18 19 "id": wallet.ClientID 20 21 "public_key": wallet.ClientKey 22 23 **Output** 24 25 Newly created wallet information 26 27 ***Sample Output*** 28 ``` 29 "{\"client_id\":\"701fa94a02141e33c8fee526852a4bfa54ba4cb230af3ee5b3885a804956e941\",\"client_key\":\"81a864b6e0059074a1adfcfd71eae4cab154f9dee906ed81eba858882709b673\",\"keys\":[{\"public_key\":\"81a864b6e0059074a1adfcfd71eae4cab154f9dee906ed81eba858882709b673\",\"private_key\":\"5126ac5a56e65c7010d72b71054564620ace408ac1d2ea66929392f422d449bb81a864b6e0059074a1adfcfd71eae4cab154f9dee906ed81eba858882709b673\"}],\"mnemonics\":\"drip include antique differ what gentle where bicycle junior crime outer dilemma member fine drip series train certain black abuse female direct grant alcohol\",\"version\":\"1.0\",\"date_created\":\"2019-06-26 20:07:54.4614548 +0000 UTC m=+0.041726101\"}" 30 ``` 31 --- 32 33 ## ENDPOINT: `/v1/transaction/put` 34 35 **Purpose** To create a transaction on Blockchain 36 37 **METHOD** POST 38 39 **Send To** Miners 40 41 **Input** 42 43 Transaction with below details 44 45 ``` go 46 type Transaction struct { 47 Hash string `json:"hash,omitempty"` 48 Version string `json:"version,omitempty"` 49 ClientID string `json:"client_id,omitempty"` 50 PublicKey string `json:"public_key,omitempty"` 51 ToClientID string `json:"to_client_id,omitempty"` 52 ChainID string `json:"chain_id,omitempty"` 53 TransactionData string `json:"transaction_data,omitempty"` 54 Value int64 `json:"transaction_value,omitempty"` 55 Signature string `json:"signature,omitempty"` 56 CreationDate int64 `json:"creation_date,omitempty"` 57 TransactionType int `json:"transaction_type,omitempty"` 58 TransactionOutput string `json:"transaction_output,omitempty"` 59 OutputHash string `json:"txn_output_hash"` 60 } 61 ``` 62 63 **Output** 64 65 HTTP response status codes 66 67 Returned Transaction Details sent along with the transaction hash on the blockchain. 68 69 70 ***Sample Input*** 71 ``` 72 {a8986181e09f01813ee6226c4605cc34654000d1bb70f20bcca0d590cb8511cb 1.0 721de8aeb895f9b6404ad3e3b0ea38e2cf5e27b304a310bfb9bd990c27d804e3 1926b6c84f89b50da73cca6ed9984f091ed5a084e7baf041d4fcb823f70ef15b 6dba10422e368813802877a85039d3985d96760ed844092319743fb3a76712d7 0afc093ffb509f059c55478bc1a60351cef7b4e9c008a53a6cc8241ca8617dfe {"name":"new_allocation_request","input":{"data_shards":3,"expiration_date":1569363680,"parity_shards":1,"size":20480}} 0 1919efe33850df82ea2be23b0de69742a036f90f4ebfa2a4c7fa53e3aa5d0af68345687fb76bc79a22c7310b67f91849abf505bb18120a38182118ff3a23dd0b 1561587680 1000 } 73 ``` 74 75 ***Sample Output*** 76 ``` 77 [{http://vira.devb.testnet-0chain.net:7071/v1/transaction/put 200 200 OK {"async":true,"entity":{"hash":"a8986181e09f01813ee6226c4605cc34654000d1bb70f20bcca0d590cb8511cb","version":"1.0","client_id":"721de8aeb895f9b6404ad3e3b0ea38e2cf5e27b304a310bfb9bd990c27d804e3","to_client_id":"6dba10422e368813802877a85039d3985d96760ed844092319743fb3a76712d7","chain_id":"0afc093ffb509f059c55478bc1a60351cef7b4e9c008a53a6cc8241ca8617dfe","transaction_data":"{\"name\":\"new_allocation_request\",\"input\":{\"data_shards\":3,\"expiration_date\":1569363680,\"parity_shards\":1,\"size\":20480}}","transaction_value":0,"signature":"1919efe33850df82ea2be23b0de69742a036f90f4ebfa2a4c7fa53e3aa5d0af68345687fb76bc79a22c7310b67f91849abf505bb18120a38182118ff3a23dd0b","creation_date":1561587680,"transaction_fee":0,"transaction_type":1000,"txn_output_hash":"","transaction_status":0}}] 78 ``` 79 --- 80 81 ## ENDPOINT: `/v1/transaction/get/confirmation` 82 83 **Purpose** To search for a transaction on the blockchain 84 85 **METHOD** GET 86 87 **Send To** Sharders 88 89 **Input** 90 91 Transaction Hash of the interested transaction 92 93 **Output** 94 95 On success: Transaction details on the blockchain 96 97 On failure: Error 98 99 ***Sample Input*** 100 ``` 101 http://cala.devb.testnet-0chain.net:7171/v1/transaction/get/confirmation?hash=bee436b5e9753cf6c1170202bb874bd539cdb3319740828c23efa62360c40632 102 ``` 103 104 ***Sample Success Output*** 105 ``` 106 {"version":"1.0","hash":"bee436b5e9753cf6c1170202bb874bd539cdb3319740828c23efa62360c40632","block_hash":"bbcb7670b955221167dcd90d79ba186b5ed08edebba0e3ccdc69a52c4f524996","txn":{"hash":"bee436b5e9753cf6c1170202bb874bd539cdb3319740828c23efa62360c40632","version":"1.0","client_id":"721de8aeb895f9b6404ad3e3b0ea38e2cf5e27b304a310bfb9bd990c27d804e3","to_client_id":"6dba10422e368813802877a85039d3985d96760ed844092319743fb3a76712d7","chain_id":"0afc093ffb509f059c55478bc1a60351cef7b4e9c008a53a6cc8241ca8617dfe","transaction_data":"{\"name\":\"new_allocation_request\",\"input\":{\"data_shards\":3,\"expiration_date\":1569363772,\"parity_shards\":1,\"size\":20480}}","transaction_value":0,"signature":"cdcf63b52eb35eed6efb81f50093b5e28419d8c5e6fc997b1cbeef05d79509d3f828d6351f7b44c9de3afa57b1f24d039c9e4f13f686d42a349a6b76d7adaf0a","creation_date":1561587772,"transaction_fee":0,"transaction_type":1000,"transaction_output":"{\"id\":\"bee436b5e9753cf6c1170202bb874bd539cdb3319740828c23efa62360c40632\",\"data_shards\":3,\"parity_shards\":1,\"size\":20480,\"expiration_date\":1569363772,\"blobbers\":[{\"id\":\"3de9840655ddded756b1e0a4229d71cf09ecdc9b90af2d76ec1752075628b251\",\"url\":\"http://vira.devb.testnet-0chain.net:5051\"},{\"id\":\"72d94629908fe904c2a0e3ef00435efe8e6826e6b2a5b4072600298aa9da6d20\",\"url\":\"http://virb.devb.testnet-0chain.net:5051\"},{\"id\":\"76509b2f5b411900bca1461960d66be316acd219f4a6de8287a54c88db153bde\",\"url\":\"http://calb.devb.testnet-0chain.net:5051\"},{\"id\":\"a60b743a7196ce75d4faf991d128ff97eeb6f62aa320c522dd0afd927312fef9\",\"url\":\"http://cala.devb.testnet-0chain.net:5051\"}],\"owner_id\":\"721de8aeb895f9b6404ad3e3b0ea38e2cf5e27b304a310bfb9bd990c27d804e3\",\"owner_public_key\":\"1926b6c84f89b50da73cca6ed9984f091ed5a084e7baf041d4fcb823f70ef15b\",\"stats\":{\"used_size\":0,\"num_of_writes\":0,\"num_of_reads\":0,\"total_challenges\":0,\"num_open_challenges\":0,\"num_success_challenges\":0,\"num_failed_challenges\":0,\"latest_closed_challenge\":\"\"},\"blobber_details\":[{\"blobber_id\":\"3de9840655ddded756b1e0a4229d71cf09ecdc9b90af2d76ec1752075628b251\",\"allocation_id\":\"bee436b5e9753cf6c1170202bb874bd539cdb3319740828c23efa62360c40632\",\"size\":5120,\"allocation_root\":\"\",\"write_marker\":null,\"stats\":{\"used_size\":0,\"num_of_writes\":0,\"num_of_reads\":0,\"total_challenges\":0,\"num_open_challenges\":0,\"num_success_challenges\":0,\"num_failed_challenges\":0,\"latest_closed_challenge\":\"\"}},{\"blobber_id\":\"72d94629908fe904c2a0e3ef00435efe8e6826e6b2a5b4072600298aa9da6d20\",\"allocation_id\":\"bee436b5e9753cf6c1170202bb874bd539cdb3319740828c23efa62360c40632\",\"size\":5120,\"allocation_root\":\"\",\"write_marker\":null,\"stats\":{\"used_size\":0,\"num_of_writes\":0,\"num_of_reads\":0,\"total_challenges\":0,\"num_open_challenges\":0,\"num_success_challenges\":0,\"num_failed_challenges\":0,\"latest_closed_challenge\":\"\"}},{\"blobber_id\":\"76509b2f5b411900bca1461960d66be316acd219f4a6de8287a54c88db153bde\",\"allocation_id\":\"bee436b5e9753cf6c1170202bb874bd539cdb3319740828c23efa62360c40632\",\"size\":5120,\"allocation_root\":\"\",\"write_marker\":null,\"stats\":{\"used_size\":0,\"num_of_writes\":0,\"num_of_reads\":0,\"total_challenges\":0,\"num_open_challenges\":0,\"num_success_challenges\":0,\"num_failed_challenges\":0,\"latest_closed_challenge\":\"\"}},{\"blobber_id\":\"a60b743a7196ce75d4faf991d128ff97eeb6f62aa320c522dd0afd927312fef9\",\"allocation_id\":\"bee436b5e9753cf6c1170202bb874bd539cdb3319740828c23efa62360c40632\",\"size\":5120,\"allocation_root\":\"\",\"write_marker\":null,\"stats\":{\"used_size\":0,\"num_of_writes\":0,\"num_of_reads\":0,\"total_challenges\":0,\"num_open_challenges\":0,\"num_success_challenges\":0,\"num_failed_challenges\":0,\"latest_closed_challenge\":\"\"}}]}","txn_output_hash":"99f5d1354b0859f1ec683cc215f1d32bd4d858cb6dc9c84d79daf74a95409068","transaction_status":1},"creation_date":1561587773,"miner_id":"347495f9f2915f3205772cf444320f6cf1a8d0c7cd1da9d621c116d8bcb18e90","round":504863,"transaction_status":1,"round_random_seed":-55809941478188169,"merkle_tree_root":"b827a913c5637d68cd556e3a0be901c1fbe9cba1c3517cc619a17dc707339d6a","merkle_tree_path":{"nodes":["fa6b4cc136ec3438b1aefaef6b0173154c3544a55fe58cf5256c5cadcadf552a","562605f404b7b6d6e9481f598c13c445c73508f51fa29b3a295e0de60ee74f07","1823199b9203f566a551020728bdec12764772a00ee32a6866cbb5e58ca36e65","af182db90bda4912bc5fb38d45c22b01b7fd2fe4a7b6b88bf2c25f85f14e4036"],"leaf_index":0},"receipt_merkle_tree_root":"f3647bfc07074ece2715ff2d317f1e9d7fcc51214126d42f07e68b032927a826","receipt_merkle_tree_path":{"nodes":["a7ffc6f8bf1ed76651c14756a061d662f580ff4de43b49fa82d80a4b80f8434a","c23f89dc588f71b1181366a014eae26b051d35ebea620cf0cd2a8466a758d8e1","9d12ea745f03257d4b1d6cc53ea2075d18e47f03c9f80c134cb8082253abc07f","cde5a1a83098b9438617129a187e69f1c1c6e493adf24a8649fb476b1cc27b4b"],"leaf_index":0}} 107 ``` 108 109 ***Sample Failure Output*** 110 ``` 111 {"code":"entity_not_found","error":"entity_not_found: txn_summary not found with id = eee436b5e9753cf6c1170202bb874bd539cdb3319740828c23efa62360c40632"} 112 ``` 113 --- 114 115 ## ENDPOINT: `/v1/client/get/balance` 116 117 **Purpose** To query balance of a wallet 118 119 **METHOD** GET 120 121 **Send To** Miners 122 123 **Input** 124 125 Wallet's client_id 126 127 **Output** 128 129 transaction hash of the pour transaction, 130 131 round when the transaciton is processed, 132 133 wallet balance 134 135 ***Sample Input*** 136 ``` 137 http://cala.devb.testnet-0chain.net:7071/v1/client/get/balance?client_id=701fa94a02141e33c8fee526852a4bfa54ba4cb230af3ee5b3885a804956e941 138 ``` 139 140 ***Sample Success Output*** 141 {"txn":"a7621db1018234699888113a19377a6bafeee6a178366c31112c5946eb1941f8","round":150255,"balance":10000000000} 142 143 ***Sample Failure Output*** 144 {"error":"value not present"} 145 146 --- 147 148 ## ENDPOINT: `/v1/scstate/get` 149 150 **METHOD** GET 151 152 **Purpose** To get the lock token configuration information such as interest rate from blockchain. 153 154 **Send To** Sharders 155 156 **Input** 157 158 Address of Interest Pool SmartContract 159 160 Key of Interest Pool SmartContract 161 162 Currently, both of them are predefined. See sample input for more details. 163 164 **Output** 165 166 lock token configuration information 167 168 ***Sample Input*** 169 ``` 170 http://cala.devb.testnet-0chain.net:7171/v1/scstate/get?sc_address=6dba10422e368813802877a85039d3985d96760ed844092319743fb3a76712d9&key=6dba10422e368813802877a85039d3985d96760ed844092319743fb3a76712d9 171 ``` 172 --- 173 174 ## ENDPOINT : `/v1/screset/` + StorageSmartContractAddress + `getblobbers` 175 176 **Purpose** To get the list of blobbers registered in blockchain 177 178 **METHOD** GET 179 180 **Send To** Sharder 181 182 **Input** 183 184 Storage SmartContract Address, 185 186 **Output** List of blobbers with ID and URL 187 188 ***Sample Input*** 189 ``` 190 http://pedro.alphanet-0chain.net:7171/v1/screst/6dba10422e368813802877a85039d3985d96760ed844092319743fb3a76712d7/getblobbers 191 ``` 192 193 ***Sample Output*** 194 ``` 195 {"Nodes":[{"id":"0afc093ffb509f059c55478bc1a60351cef7b4e9c008a53a6cc8241ca8617dfe","url":"http://pedro.alphanet-0chain.net:5051"}, 196 {"id":"d374fc5b55a496d26e9d642ed0708746fd64a24bd59139dacf50b4a4ec4c9b51","url":"http://pedro.alphanet-0chain.net:5052"]} 197 ``` 198 --- 199 200 ## ENDPOINT: "/v1/file/upload/" 201 202 **Purpose** To send a upload request 203 204 **METHOD** POST' 205 206 **Send To** Blobbers 207 208 **Input** allocation id, File Reader 209 210 ***Sample Input*** 211 ``` 212 {POST http://vira.devb.testnet-0chain.net:5051/v1/file/upload/ffb8114204029cc556e0d3f99b3c40a1c0d79f1f75240ef3c9da29f8ff474622 HTTP/1.1 1 1 map[X-App-Client-Id:[6202c8db2657205ce28515ba7c0e65b5acbd55aca4eae3feded3d4d6e8693743] X-App-Client-Key:[245859ccdb88628180de02482aeaac8c56d6ee1035d151a6119593fdaff7f7f4]] 0xc00000e360 <nil> 0 [] false vira.devb.testnet-0chain.net:5051 map[] map[] <nil> map[] <nil> <nil> <nil> <nil>} 213 ``` 214 --- 215 216 ## ENDPOINT: "/v1/file/download/" 217 218 **Purpose** To download a file from remote 219 220 **METHOD** GET 221 222 **Send To** Blobbers 223 224 **Input** Allocation ID, File Reader 225 226 ***Sample Input*** 227 ``` 228 GET http://virb.devb.testnet-0chain.net:5051/v1/file/referencepath/adf87db53288d0f97ed2ec7db96db1d95376981eeefe4bee8e688e2270e234ab?path=%2FV%2FJ%2FC%2FJ%2FhYzRy.txt HTTP/1.1 1 1 map[X-App-Client-Id:[6202c8db2657205ce28515ba7c0e65b5acbd55aca4eae3feded3d4d6e8693743] X-App-Client-Key:[245859ccdb88628180de02482aeaac8c56d6ee1035d151a6119593fdaff7f7f4]] <nil> <nil> 0 [] false virb.devb.testnet-0chain.net:5051 map[] map[] <nil> map[] <nil> <nil> <nil> <nil>} 229 ``` 230 --- 231 232 ## ENDPOINT: '/v1/file/list/' 233 234 **Purpose** To get folder structure and file details from blobbers 235 236 **METHOD** GET 237 238 **Send To** Blobbers 239 240 **Input** Allocation ID, remote path 241 242 **Output** folders and files at the remote path 243 244 ***Sample Input*** 245 ``` 246 GET http://cala.devb.testnet-0chain.net:5051/v1/file/list/adf87db53288d0f97ed2ec7db96db1d95376981eeefe4bee8e688e2270e234ab?path=%2F HTTP/1.1 1 1 map[] <nil> <nil> 0 [] false cala.devb.testnet-0chain.net:5051 map[] map[] <nil> map[] <nil> <nil> <nil> <nil> 247 ``` 248 249 --- 250 251 ## ENDPOINT: '/v1/file/referencepath/' 252 253 **Purpose** To get reference path for a given file 254 255 **METHOD** GET 256 257 **Send To** Blobbers 258 259 **Input** 260 Allocation ID, 261 262 absolute remote path 263 264 ***Sample Input*** 265 ``` 266 GET http://virb.devb.testnet-0chain.net:5051/v1/file/referencepath/adf87db53288d0f97ed2ec7db96db1d95376981eeefe4bee8e688e2270e234ab?path=%2FV%2FJ%2FC%2FJ%2FhYzRy.txt HTTP/1.1 1 1 map[X-App-Client-Id:[6202c8db2657205ce28515ba7c0e65b5acbd55aca4eae3feded3d4d6e8693743] X-App-Client-Key:[245859ccdb88628180de02482aeaac8c56d6ee1035d151a6119593fdaff7f7f4]] <nil> <nil> 0 [] false virb.devb.testnet-0chain.net:5051 map[] map[] <nil> map[] <nil> <nil> <nil> <nil>} 267 ``` 268 ***Sample Output*** 269 ``` 270 [Reference path: {"meta_data":{"hash":"","lookup_hash":"","name":"/","num_of_blocks":0,"path":"/","path_hash":"","type":"d"},"latest_write_marker":null} 271 ``` 272 --- 273 274 ## ENDPOINT: "/v1/connection/commit/" 275 276 **Purpose** To commit the upload transaction 277 278 **METHOD** POST 279 280 **Send To** BLOBBERS 281 282 **Input** allocation id 283 284 ***Sample Input*** 285 ``` 286 http://calb.devb.testnet-0chain.net:5051/v1/connection/commit/c471ab76b0bb2766b29cd97830d310d9f45d3a8c0e9bee979a029af37d9acbe3 287 ``` 288 --- 289 290 ## ENDPOINT: "/v1/file/meta/" 291 292 **Purpose** To get meta data of a file 293 294 **METHOD** POST 295 296 **Send To** Blobbers 297 298 **Input** allocation id 299 300 ***Sample Input*** 301 ``` 302 POST http://cala.devb.testnet-0chain.net:5051/v1/file/meta/c471ab76b0bb2766b29cd97830d310d9f45d3a8c0e9bee979a029af37d9acbe3 303 ``` 304 --- 305 ## ENDPOINT: "/getstats" 306 307 **Purpose** To get the statistics from the Blobber 308 309 **METHOD** GET 310 311 **Send To** Blobbers 312 313 **Input** NULL 314 315 ***Sample Input*** 316 ``` 317 http://pedro.alphanet-0chain.net:5051/getstats 318 ``` 319 320 ***Sample Output*** 321 ``` 322 {"used_size":5159361,"files_size":4222197,"thumbnails_size":937164,"num_of_block_writes":69,"num_of_writes":8,"num_of_reads":28,"total_challenges":6,"num_open_challenges":0,"num_success_challenges":6,"num_failed_challenges":0,"num_redeemed_challenges":6,"num_of_allocations":1} 323 ``` 324 --- 325 ## ENDPOINT: `/getstats?allocations=1` 326 327 **Purpose** To get the list of allocations from the Blobber 328 329 **METHOD** GET 330 331 **Send To** Blobbers 332 333 **Input** NULL 334 335 ***Sample Input*** 336 ``` 337 http://pedro.alphanet-0chain.net:5051/getstats?allocations=1 338 ``` 339 340 ***Sample Output*** 341 ``` 342 [{"id":"c99ddc66089b7444529a94e4440d30953c2d008ffa74dea1b60d29476ea7376d"},{"id":"6ba0042bc93fb0c9bea2fec02228c3e71004e0f482d6d3da9e9dd9d55d51c560"}] 343 ``` 344 --- 345 ## ENDPOINT: `/getstats?allocation_id=` + <allocationid> 346 347 **Purpose** To get the statistics from the Blobber 348 349 **METHOD** GET 350 351 **Send To** Blobbers 352 353 **Input** Allocation ID 354 355 ***Sample Input*** 356 ``` 357 http://pedro.alphanet-0chain.net:5051/getstats?allocation_id=c99ddc66089b7444529a94e4440d30953c2d008ffa74dea1b60d29476ea7376d 358 ``` 359 360 ***Sample Output*** 361 ``` 362 {"allocation_id":"c99ddc66089b7444529a94e4440d30953c2d008ffa74dea1b60d29476ea7376d","used_size":54385,"files_size":54385,"thumbnails_size":0,"disk_size_used":54385,"num_of_block_writes":1,"num_of_writes":1,"num_of_reads":0,"total_challenges":0,"num_open_challenges":0,"num_success_challenges":0,"num_failed_challenges":0,"num_redeemed_challenges":0} 363 ``` 364 ---