Sia uses semantic versioning and is backwards compatible to version v1.0.0.
API calls return either JSON or no content. Success is indicated by 2xx HTTP status codes, while errors are indicated by 4xx and 5xx HTTP status codes. If an endpoint does not specify its expected status code refer to #standard-responses.
There may be functional API calls which are not documented. These are not guaranteed to be supported beyond the current release, and should not be used in production.
Notes:
- Requests must set their User-Agent string to contain the substring "Sia-Agent".
- By default, siad listens on "localhost:9980". This can be changed using the
--api-addrflag when running siad. - Do not bind or expose the API to a non-loopback address unless you are aware of the possible dangers.
Example GET curl call:
curl -A "Sia-Agent" "localhost:9980/wallet/transactions?startheight=1&endheight=250"
Example POST curl call:
curl -A "Sia-Agent" --data "amount=123&destination=abcd" "localhost:9980/wallet/siacoins"
The standard response indicating the request was successfully processed is HTTP
status code 204 No Content. If the request was successfully processed and the
server responded with JSON the HTTP status code is 200 OK. Specific endpoints
may specify other 2xx status codes on success.
The standard error response indicating the request failed for any reason, is a 4xx or 5xx HTTP status code with an error JSON object describing the error.
{
"message": String
// There may be additional fields depending on the specific error.
}API authentication can be enabled with the --authenticate-api siad flag.
Authentication is HTTP Basic Authentication as described in
RFC 2617, however, the username is the
empty string. The flag does not enforce authentication on all API endpoints.
Only endpoints that expose sensitive information or modify state require
authentication.
For example, if the API password is "foobar" the request header should include
Authorization: Basic OmZvb2Jhcg==
Unless otherwise specified, all parameters should be specified in their smallest possible unit. For example, size should always be specified in bytes and Siacoins should be specified in hastings. JSON values returned by the API will also use the smallest possible unit, unless otherwise specified.
If a numbers is returned as a string in JSON, it should be treated as an arbitrary-precision number (bignum), and it should be parsed with your language's corresponding bignum library. Currency values are the most common example where this is necessary.
| Route | HTTP verb |
|---|---|
| /daemon/constants | GET |
| /daemon/stop | GET |
| /daemon/version | GET |
For examples and detailed descriptions of request and response parameters, refer to Daemon.md.
returns the set of constants in use.
JSON Response (with comments)
{
"blockfrequency": 600, // seconds per block
"blocksizelimit": 2000000, // bytes
"extremefuturethreshold": 10800, // seconds
"futurethreshold": 10800, // seconds
"genesistimestamp": 1257894000, // Unix time
"maturitydelay": 144, // blocks
"mediantimestampwindow": 11, // blocks
"siafundcount": "10000",
"siafundportion": "39/1000",
"targetwindow": 1000, // blocks
"initialcoinbase": 300000, // Siacoins (see note in Daemon.md)
"minimumcoinbase": 30000, // Siacoins (see note in Daemon.md)
"roottarget": [0,0,0,0,32,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],
"rootdepth": [255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255,255],
"maxtargetadjustmentup": "5/2",
"maxtargetadjustmentdown": "2/5",
"siacoinprecision": "1000000000000000000000000" // hastings per siacoin
}cleanly shuts down the daemon. May take a few seconds.
standard success or error response. See #standard-responses.
returns the version of the Sia daemon currently running.
JSON Response (with comments)
{
"version": "1.0.0"
}| Route | HTTP verb |
|---|---|
| /consensus | GET |
| /consensus/blocks | GET |
| /consensus/validate/transactionset | POST |
For examples and detailed descriptions of request and response parameters, refer to Consensus.md.
returns information about the consensus set, such as the current block height.
JSON Response (with comments)
{
"synced": true,
"height": 62248,
"currentblock": "00000000000008a84884ba827bdc868a17ba9c14011de33ff763bd95779a9cf1",
"target": [0,0,0,0,0,0,11,48,125,79,116,89,136,74,42,27,5,14,10,31,23,53,226,238,202,219,5,204,38,32,59,165],
"difficulty": "1234"
}Returns the block for a given id or height.
One of the following parameters can be specified.
// BlockID of the requested block.
id
// BlockHeight of the requested block.
height
The JSON formatted block or a standard error response.
{
"height": 20032,
"id": "00000000000033b9eb57fa63a51adeea857e70f6415ebbfe5df2a01f0d0477f4",
"minerpayouts": [
{
"unlockhash": "c199cd180e19ef7597bcf4beecdd4f211e121d085e24432959c42bdf9030e32b9583e1c2727c",
"value": "279978000000000000000000000000"
}
],
"nonce": [4,12,219,7,0,0,0,0],
"parentid": "0000000000009615e8db750eb1226aa5e629bfa7badbfe0b79607ec8b918a44c",
"timestamp": 1444516982,
"transactions": [
{
// ...
},
{
"arbitrarydata": [],
"filecontractrevisions": [],
"filecontracts": [],
"id": "3c98ec79b990461f353c22bb06bcfb10e702f529ad7d27a43c4448273553d90a",
"minerfees": [],
"siacoininputs": [
{
"parentid": "24cbeb9df7eb2d81d0025168fc94bd179909d834f49576e65b51feceaf957a64",
"unlockconditions": {
"publickeys": [
{
"algorithm": "ed25519",
"key": "QET8w7WRbGfcnnpKd1nuQfE3DuNUUq9plyoxwQYDK4U="
}
],
"signaturesrequired": 1,
"timelock": 0
}
}
],
"siacoinoutputs": [
{
"id": "1f9da81e23522f79590ac67ac0b668828c52b341cbf04df4959bb7040c072f29",
"unlockhash": "d54f500f6c1774d518538dbe87114fe6f7e6c76b5bc8373a890b12ce4b8909a336106a4cd6db",
"value": "1010000000000000000000000000"
},
{
"id": "14978a4c54f5ebd910ea41537de014f8423574c13d132e8713fab5af09ec08ca",
"unlockhash": "48a56b19bd0be4f24190640acbd0bed9669ea9c18823da2645ec1ad9652f10b06c5d4210f971",
"value": "5780000000000000000000000000"
}
],
"siafundinputs": [],
"siafundoutputs": [],
"storageproofs": [],
"transactionsignatures": [
{
"coveredfields": {
"arbitrarydata": [],
"filecontractrevisions": [],
"filecontracts": [],
"minerfees": [],
"siacoininputs": [],
"siacoinoutputs": [],
"siafundinputs": [],
"siafundoutputs": [],
"storageproofs": [],
"transactionsignatures": [],
"wholetransaction": true
},
"parentid": "24cbeb9df7eb2d81d0025168fc94bd179909d834f49576e65b51feceaf957a64",
"publickeyindex": 0,
"signature": "pByLGMlvezIZWVZmHQs/ynGETETNbxcOY/kr6uivYgqZqCcKTJ0JkWhcFaKJU+3DEA7JAloLRNZe3PTklD3tCQ==",
"timelock": 0
}
]
},
{
// ...
}
]
}
validates a set of transactions using the current utxo set.
Since transactions may be large, the transaction set is supplied in the POST body, encoded in JSON format.
standard success or error response. See #standard-responses.
| Route | HTTP verb |
|---|---|
| /gateway | GET |
| /gateway/connect/:netaddress | POST |
| /gateway/disconnect/:netaddress | POST |
For examples and detailed descriptions of request and response parameters, refer to Gateway.md.
/gateway [GET] (example)
returns information about the gateway, including the list of connected peers.
JSON Response (with comments)
{
"netaddress": String,
"peers": []{
"netaddress": String,
"version": String,
"inbound": Boolean
}
}/gateway/connect/:netaddress [POST] (example)
connects the gateway to a peer. The peer is added to the node list if it is not already present. The node list is the list of all nodes the gateway knows about, but is not necessarily connected to.
Path Parameters (with comments)
:netaddress
standard success or error response. See #standard-responses.
/gateway/disconnect/:netaddress [POST] (example)
disconnects the gateway from a peer. The peer remains in the node list.
Path Parameters (with comments)
:netaddress
standard success or error response. See #standard-responses.
| Route | HTTP verb |
|---|---|
| /host | GET |
| /host | POST |
| /host/announce | POST |
| /host/contracts | GET |
| /host/estimatescore | GET |
| /host/storage | GET |
| /host/storage/folders/add | POST |
| /host/storage/folders/remove | POST |
| /host/storage/folders/resize | POST |
| /host/storage/sectors/delete/:merkleroot | POST |
For examples and detailed descriptions of request and response parameters, refer to Host.md.
fetches status information about the host.
JSON Response (with comments)
{
"externalsettings": {
"acceptingcontracts": true,
"maxdownloadbatchsize": 17825792, // bytes
"maxduration": 25920, // blocks
"maxrevisebatchsize": 17825792, // bytes
"netaddress": "123.456.789.0:9982",
"remainingstorage": 35000000000, // bytes
"sectorsize": 4194304, // bytes
"totalstorage": 35000000000, // bytes
"unlockhash": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789ab",
"windowsize": 144, // blocks
"collateral": "57870370370", // hastings / byte / block
"maxcollateral": "100000000000000000000000000000", // hastings
"contractprice": "30000000000000000000000000", // hastings
"downloadbandwidthprice": "250000000000000", // hastings / byte
"storageprice": "231481481481", // hastings / byte / block
"uploadbandwidthprice": "100000000000000", // hastings / byte
"revisionnumber": 0,
"version": "1.0.0"
},
"financialmetrics": {
"contractcount": 2,
"contractcompensation": "123", // hastings
"potentialcontractcompensation": "123", // hastings
"lockedstoragecollateral": "123", // hastings
"lostrevenue": "123", // hastings
"loststoragecollateral": "123", // hastings
"potentialstoragerevenue": "123", // hastings
"riskedstoragecollateral": "123", // hastings
"storagerevenue": "123", // hastings
"transactionfeeexpenses": "123", // hastings
"downloadbandwidthrevenue": "123", // hastings
"potentialdownloadbandwidthrevenue": "123", // hastings
"potentialuploadbandwidthrevenue": "123", // hastings
"uploadbandwidthrevenue": "123" // hastings
},
"internalsettings": {
"acceptingcontracts": true,
"maxdownloadbatchsize": 17825792, // bytes
"maxduration": 25920, // blocks
"maxrevisebatchsize": 17825792, // bytes
"netaddress": "123.456.789.0:9982",
"windowsize": 144, // blocks
"collateral": "57870370370", // hastings / byte / block
"collateralbudget": "2000000000000000000000000000000", // hastings
"maxcollateral": "100000000000000000000000000000", // hastings
"mincontractprice": "30000000000000000000000000", // hastings
"mindownloadbandwidthprice": "250000000000000", // hastings / byte
"minstorageprice": "231481481481", // hastings / byte / block
"minuploadbandwidthprice": "100000000000000" // hastings / byte
},
"networkmetrics": {
"downloadcalls": 0,
"errorcalls": 1,
"formcontractcalls": 2,
"renewcalls": 3,
"revisecalls": 4,
"settingscalls": 5,
"unrecognizedcalls": 6
},
"connectabilitystatus": "checking",
"workingstatus": "checking"
}configures hosting parameters. All parameters are optional; unspecified parameters will be left unchanged.
Query String Parameters (with comments)
acceptingcontracts // Optional, true / false
maxdownloadbatchsize // Optional, bytes
maxduration // Optional, blocks
maxrevisebatchsize // Optional, bytes
netaddress // Optional
windowsize // Optional, blocks
collateral // Optional, hastings / byte / block
collateralbudget // Optional, hastings
maxcollateral // Optional, hastings
mincontractprice // Optional, hastings
mindownloadbandwidthprice // Optional, hastings / byte
minstorageprice // Optional, hastings / byte / block
minuploadbandwidthprice // Optional, hastings / byte
standard success or error response. See #standard-responses.
Announces the host to the network as a source of storage. Generally only needs to be called once.
Query String Parameters (with comments)
netaddress string // Optional
standard success or error response. See #standard-responses.
gets a list of all contracts from the host database
JSON Response (with comments)
{
"contracts": [
{
"contractcost": "1234", // hastings
"datasize": 500000, // bytes
"lockedcollateral": "1234", // hastings
"obligationid": "fff48010dcbbd6ba7ffd41bc4b25a3634ee58bbf688d2f06b7d5a0c837304e13",
"potentialdownloadrevenue": "1234", // hastings
"potentialstoragerevenue": "1234", // hastings
"potentialuploadrevenue": "1234", // hastings
"riskedcollateral": "1234", // hastings
"sectorrootscount": 2,
"transactionfeesadded": "1234", // hastings
"expirationheight": 123456, // blocks
"negotiationheight": 123456, // blocks
"proofdeadline": 123456, // blocks
"obligationstatus": "obligationFailed",
"originconfirmed": true,
"proofconfirmed": true,
"proofconstructed": true
"revisionconfirmed": false,
"revisionconstructed": false,
}
]
}gets a list of folders tracked by the host's storage manager.
JSON Response (with comments)
{
"folders": [
{
"path": "/home/foo/bar",
"capacity": 50000000000, // bytes
"capacityremaining": 100000, // bytes
"failedreads": 0,
"failedwrites": 1,
"successfulreads": 2,
"successfulwrites": 3
}
]
}adds a storage folder to the manager. The manager may not check that there is enough space available on-disk to support as much storage as requested
Query String Parameters (with comments)
path // Required
size // bytes, Required
standard success or error response. See #standard-responses.
remove a storage folder from the manager. All storage on the folder will be moved to other storage folders, meaning that no data will be lost. If the manager is unable to save data, an error will be returned and the operation will be stopped.
Query String Parameters (with comments)
path // Required
force // bool, Optional, default is false
standard success or error response. See #standard-responses.
grows or shrink a storage folder in the manager. The manager may not check that there is enough space on-disk to support growing the storage folder, but should gracefully handle running out of space unexpectedly. When shrinking a storage folder, any data in the folder that needs to be moved will be placed into other storage folders, meaning that no data will be lost. If the manager is unable to migrate the data, an error will be returned and the operation will be stopped.
Query String Parameters (with comments)
path // Required
newsize // bytes, Required
standard success or error response. See #standard-responses.
deletes a sector, meaning that the manager will be unable to upload that sector and be unable to provide a storage proof on that sector. This endpoint is for removing the data entirely, and will remove instances of the sector appearing at all heights. The primary purpose is to comply with legal requests to remove data.
Path Parameters (with comments)
:merkleroot
standard success or error response. See #standard-responses.
returns the estimated HostDB score of the host using its current settings, combined with the provided settings.
JSON Response (with comments)
{
"estimatedscore": "123456786786786786786786786742133",
"conversionrate": 95
}Query String Parameters (with comments)
acceptingcontracts // Optional, true / false
maxdownloadbatchsize // Optional, bytes
maxduration // Optional, blocks
maxrevisebatchsize // Optional, bytes
netaddress // Optional
windowsize // Optional, blocks
collateral // Optional, hastings / byte / block
collateralbudget // Optional, hastings
maxcollateral // Optional, hastings
mincontractprice // Optional, hastings
mindownloadbandwidthprice // Optional, hastings / byte
minstorageprice // Optional, hastings / byte / block
minuploadbandwidthprice // Optional, hastings / byte
| Route | HTTP verb |
|---|---|
| /hostdb | GET |
| /hostdb/active | GET |
| /hostdb/all | GET |
| /hostdb/hosts/:pubkey | GET |
For examples and detailed descriptions of request and response parameters, refer to HostDB.md.
/hostdb [GET] (example)
shows some general information about the state of the hostdb.
JSON Response (with comments)
Either the following JSON struct or an error response. See #standard-responses.
{
"initialscancomplete": false
}/hostdb/active [GET] (example)
lists all of the active hosts known to the renter, sorted by preference.
Query String Parameters (with comments)
numhosts // Optional
JSON Response (with comments)
{
"hosts": [
{
"acceptingcontracts": true,
"maxdownloadbatchsize": 17825792, // bytes
"maxduration": 25920, // blocks
"maxrevisebatchsize": 17825792, // bytes
"netaddress": "123.456.789.2:9982",
"remainingstorage": 35000000000, // bytes
"sectorsize": 4194304, // bytes
"totalstorage": 35000000000, // bytes
"unlockhash": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789ab",
"windowsize": 144, // blocks
"publickey": {
"algorithm": "ed25519",
"key": "RW50cm9weSBpc24ndCB3aGF0IGl0IHVzZWQgdG8gYmU="
}
"publickeystring": "ed25519:1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
}
]
}/hostdb/all [GET] (example)
lists all of the hosts known to the renter. Hosts are not guaranteed to be in any particular order, and the order may change in subsequent calls.
JSON Response (with comments)
{
"hosts": [
{
"acceptingcontracts": true,
"maxdownloadbatchsize": 17825792, // bytes
"maxduration": 25920, // blocks
"maxrevisebatchsize": 17825792, // bytes
"netaddress": "123.456.789.0:9982",
"remainingstorage": 35000000000, // bytes
"sectorsize": 4194304, // bytes
"totalstorage": 35000000000, // bytes
"unlockhash": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789ab",
"windowsize": 144, // blocks
"publickey": {
"algorithm": "ed25519",
"key": "RW50cm9weSBpc24ndCB3aGF0IGl0IHVzZWQgdG8gYmU="
}
"publickeystring": "ed25519:1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
}
]
}/hostdb/hosts/:pubkey [GET] (example)
fetches detailed information about a particular host, including metrics regarding the score of the host within the database. It should be noted that each renter uses different metrics for selecting hosts, and that a good score on in one hostdb does not mean that the host will be successful on the network overall.
Path Parameters (with comments)
:pubkey
JSON Response (with comments)
{
"entry": {
"acceptingcontracts": true,
"maxdownloadbatchsize": 17825792, // bytes
"maxduration": 25920, // blocks
"maxrevisebatchsize": 17825792, // bytes
"netaddress": "123.456.789.0:9982",
"remainingstorage": 35000000000, // bytes
"sectorsize": 4194304, // bytes
"totalstorage": 35000000000, // bytes
"unlockhash": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789ab",
"windowsize": 144, // blocks
"publickey": {
"algorithm": "ed25519",
"key": "RW50cm9weSBpc24ndCB3aGF0IGl0IHVzZWQgdG8gYmU="
}
"publickeystring": "ed25519:1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
},
"scorebreakdown": {
"score": 1,
"ageadjustment": 0.1234,
"burnadjustment": 0.1234,
"collateraladjustment": 23.456,
"interactionadjustment": 0.1234,
"priceadjustment": 0.1234,
"storageremainingadjustment": 0.1234,
"uptimeadjustment": 0.1234,
"versionadjustment": 0.1234,
}
}| Route | HTTP verb |
|---|---|
| /miner | GET |
| /miner/start | GET |
| /miner/stop | GET |
| /miner/header | GET |
| /miner/header | POST |
For examples and detailed descriptions of request and response parameters, refer to Miner.md.
returns the status of the miner.
JSON Response (with comments)
{
"blocksmined": 9001,
"cpuhashrate": 1337,
"cpumining": false,
"staleblocksmined": 0,
}starts a single threaded cpu miner. Does nothing if the cpu miner is already running.
standard success or error response. See #standard-responses.
stops the cpu miner. Does nothing if the cpu miner is not running.
standard success or error response. See #standard-responses.
provides a block header that is ready to be grinded on for work.
For efficiency the header for work is returned as a raw byte encoding of the header, rather than encoded to JSON. Refer to Miner.md#byte-response for a detailed description of the byte encoding.
submits a header that has passed the POW.
For efficiency headers are submitted as raw byte encodings of the header in the
body of the request, rather than as a query string parameter or path parameter.
The request body should contain only the 80 bytes of the encoded header. The
encoding is the same encoding used in /miner/header [GET] endpoint. Refer to
Miner.md#byte-response for a detailed
description of the byte encoding.
| Route | HTTP verb |
|---|---|
| /renter | GET |
| /renter | POST |
| /renter/contracts | GET |
| /renter/downloads | GET |
| /renter/downloads/clear | POST |
| /renter/prices | GET |
| /renter/files | GET |
| /renter/file/*siapath | GET |
| /renter/delete/*siapath | POST |
| /renter/download/*siapath | GET |
| /renter/downloadasync/*siapath | GET |
| /renter/rename/*siapath | POST |
| /renter/stream/*siapath | GET |
| /renter/upload/*siapath | POST |
For examples and detailed descriptions of request and response parameters, refer to Renter.md.
returns the current settings along with metrics on the renter's spending.
JSON Response (with comments)
{
"settings": {
"allowance": {
"funds": "1234", // hastings
"hosts": 24,
"period": 6048, // blocks
"renewwindow": 3024 // blocks
},
"maxuploadspeed": 1234, // BPS
"maxdownloadspeed": 1234, // BPS
"streamcachesize": 4
},
"financialmetrics": {
"contractfees": "1234", // hastings
"contractspending": "1234", // hastings (deprecated, now totalallocated)
"downloadspending": "5678", // hastings
"storagespending": "1234", // hastings
"totalallocated": "1234", // hastings
"uploadspending": "5678", // hastings
"unspent": "1234" // hastings
},
"currentperiod": 200
}modify settings that control the renter's behavior.
Query String Parameters (with comments)
funds // hastings
hosts
period // block height
renewwindow // block height
maxdownloadspeed // bytes per second
maxuploadspeed // bytes per second
streamcachesize // number of data chunks cached when streaming
standard success or error response. See #standard-responses.
returns the renter's contracts. Active contracts are contracts that the Renter is currently using to store, upload, and download data, and are returned by default. Inactive contracts are contracts that are in the current period but are marked as not good for renew, these contracts have the potential to become active again but currently are not storing data. Expired contracts are contracts not in the current period, where not more data is being stored and excess funds have been released to the renter.
Contract Parameters (with comments)
inactive // true or false - Optional
expired // true or false - Optional
JSON Response (with comments)
{
"activecontracts": [
{
"downloadspending": "1234", // hastings
"endheight": 50000, // block height
"fees": "1234", // hastings
"hostpublickey": {
"algorithm": "ed25519",
"key": "RW50cm9weSBpc24ndCB3aGF0IGl0IHVzZWQgdG8gYmU="
},
"id": "1234567890abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
"lasttransaction": {},
"netaddress": "12.34.56.78:9",
"renterfunds": "1234", // hastings
"size": 8192, // bytes
"startheight": 50000, // block height
"StorageSpending": "1234",
"storagespending": "1234", // hastings
"totalcost": "1234", // hastings
"uploadspending": "1234" // hastings
"goodforupload": true,
"goodforrenew": false,
}
],
"inactivecontracts": [],
"expiredcontracts": [],
}lists all files in the download queue.
JSON Response (with comments)
{
"downloads": [
{
"destination": "/home/users/alice/bar.txt",
"destinationtype": "file",
"length": 8192,
"offset": 2000,
"siapath": "foo/bar.txt",
"completed": true,
"endtime": "2009-11-10T23:10:00Z", // RFC 3339 time
"error": "",
"received": 8192,
"starttime": "2009-11-10T23:00:00Z", // RFC 3339 time
"totaldatatransfered": 10031
}
]
}Clears the download history of the renter for a range of unix time stamps. Both parameters are optional, if no parameters are provided, the entire download history will be cleared. To clear a single download, provide the timestamp for the download as both parameters. Providing only the before parameter will clear all downloads older than the timestamp. Conversely, providing only the after parameter will clear all downloads newer than the timestamp.
Timestamp Parameters (with comments)
before // Optional
after // Optional
standard success or error response. See #standard-responses.
lists the status of all files.
JSON Response (with comments)
{
"files": [
{
"siapath": "foo/bar.txt",
"localpath": "/home/foo/bar.txt",
"filesize": 8192, // bytes
"available": true,
"renewing": true,
"redundancy": 5,
"bytesuploaded": 209715200, // total bytes uploaded
"uploadprogress": 100, // percent
"expiration": 60000
}
]
}lists the status of specified file.
JSON Response (with comments)
{
"file": {
"siapath": "foo/bar.txt",
"localpath": "/home/foo/bar.txt",
"filesize": 8192, // bytes
"available": true,
"renewing": true,
"redundancy": 5,
"bytesuploaded": 209715200, // total bytes uploaded
"uploadprogress": 100, // percent
"expiration": 60000
}
}lists the estimated prices of performing various storage and data operations.
JSON Response (with comments)
{
"downloadterabyte": "1234", // hastings
"formcontracts": "1234", // hastings
"storageterabytemonth": "1234", // hastings
"uploadterabyte": "1234" // hastings
}deletes a renter file entry. Does not delete any downloads or original files, only the entry in the renter.
Path Parameters (with comments)
*siapath
standard success or error response. See #standard-responses.
downloads a file to the local filesystem. The call will block until the file has been downloaded.
Path Parameters (with comments)
*siapath
Query String Parameters (with comments)
async
destination
httpresp
length
offset
standard success or error response. See #standard-responses.
downloads a file to the local filesystem. The call will return immediately.
Path Parameters (with comments)
*siapath
Query String Parameters (with comments)
destination
standard success or error response. See #standard-responses.
renames a file. Does not rename any downloads or source files, only renames the
entry in the renter. An error is returned if siapath does not exist or
newsiapath already exists.
Path Parameters (with comments)
*siapath
Query String Parameters (with comments)
newsiapath
standard success or error response. See #standard-responses.
downloads a file using http streaming. This call blocks until the data is received. The streaming endpoint also uses caching internally to prevent siad from redownloading the same chunk multiple times when only parts of a file are requested at once. This might lead to a substantial increase in ram usage and therefore it is not recommended to stream multiple files in parallel at the moment. This restriction will be removed together with the caching once partial downloads are supported in the future.
Path Parameters (with comments)
*siapath
standard success with the requested data in the body or error response. See #standard-responses.
uploads a file to the network from the local filesystem.
Path Parameters (with comments)
*siapath
Query String Parameters (with comments)
datapieces // int
paritypieces // int
source // string - a filepath
standard success or error response. See #standard-responses.
| Route | HTTP verb |
|---|---|
| /tpool/confirmed/:id | GET |
| /tpool/fee | GET |
| /tpool/raw/:id | GET |
| /tpool/raw | POST |
returns whether the requested transaction has been seen on the blockchain. Note, however, that the block containing the transaction may later be invalidated by a reorg.
{
"confirmed": true
}returns the minimum and maximum estimated fees expected by the transaction pool.
JSON Response (with comments)
{
"minimum": "1234", // hastings / byte
"maximum": "5678" // hastings / byte
}returns the ID for the requested transaction and its raw encoded parents and transaction data.
JSON Response (with comments)
{
// id of the transaction
"id": "124302d30a219d52f368ecd94bae1bfb922a3e45b6c32dd7fb5891b863808788",
// raw, base64 encoded transaction data
"transaction": "AQAAAAAAAADBM1ca/FyURfizmSukoUQ2S0GwXMit1iNSeYgrnhXOPAAAAAAAAAAAAQAAAAAAAABlZDI1NTE5AAAAAAAAAAAAIAAAAAAAAACdfzoaJ1MBY7L0fwm7O+BoQlFkkbcab5YtULa6B9aecgEAAAAAAAAAAQAAAAAAAAAMAAAAAAAAAAM7Ljyf0IA86AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAEAAAAAAAAACgAAAAAAAACe0ZTbGbI4wAAAAAAAAAAAAAABAAAAAAAAAMEzVxr8XJRF+LOZK6ShRDZLQbBcyK3WI1J5iCueFc48AAAAAAAAAAAAAAAAAAAAAAEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAEAAAAAAAAAA+z4P1wc98IqKxykTSJxiVT+BVbWezIBnIBO1gRRlLq2x/A+jIc6G7/BA5YNJRbdnqPHrzsZvkCv4TKYd/XzwBA==",
"parents": "AQAAAAAAAAABAAAAAAAAAJYYmFUdXXfLQ2p6EpF+tcqM9M4Pw5SLSFHdYwjMDFCjAAAAAAAAAAABAAAAAAAAAGVkMjU1MTkAAAAAAAAAAAAgAAAAAAAAAAHONvdzzjHfHBx6psAN8Z1rEVgqKPZ+K6Bsqp3FbrfjAQAAAAAAAAACAAAAAAAAAAwAAAAAAAAAAzvNDjSrme8gwAAA4w8ODnW8DxbOV/JribivvTtjJ4iHVOug0SXJc31BdSINAAAAAAAAAAPGHY4699vggx5AAAC2qBhm5vwPaBsmwAVPho/1Pd8ecce/+BGv4UimnEPzPQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAQAAAAAAAACWGJhVHV13y0NqehKRfrXKjPTOD8OUi0hR3WMIzAxQowAAAAAAAAAAAAAAAAAAAAABAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAABAAAAAAAAAABnt64wN1qxym/CfiMgOx5fg/imVIEhY+4IiiM7gwvSx8qtqKniOx50ekrGv8B+gTKDXpmm2iJibWTI9QLZHWAY=",
}submits a raw transaction to the transaction pool, broadcasting it to the transaction pool's peers.
Query String Parameters (with comments)
parents string // raw base64 encoded transaction parents
transaction string // raw base64 encoded transaction
standard success or error response. See #standard-responses.
| Route | HTTP verb |
|---|---|
| /wallet | GET |
| /wallet/033x | POST |
| /wallet/address | GET |
| /wallet/addresses | GET |
| /wallet/backup | GET |
| /wallet/init | POST |
| /wallet/init/seed | POST |
| /wallet/lock | POST |
| /wallet/seed | POST |
| /wallet/seeds | GET |
| /wallet/siacoins | POST |
| /wallet/siafunds | POST |
| /wallet/siagkey | POST |
| /wallet/sweep/seed | POST |
| /wallet/transaction/:id | GET |
| /wallet/transactions | GET |
| /wallet/transactions/:addr | GET |
| /wallet/unlock | POST |
| /wallet/verify/address/:addr | GET |
| /wallet/changepassword | POST |
For examples and detailed descriptions of request and response parameters, refer to Wallet.md.
returns basic information about the wallet, such as whether the wallet is locked or unlocked.
JSON Response (with comments)
{
"encrypted": true,
"unlocked": true,
"rescanning": false,
"confirmedsiacoinbalance": "123456", // hastings, big int
"unconfirmedoutgoingsiacoins": "0", // hastings, big int
"unconfirmedincomingsiacoins": "789", // hastings, big int
"siafundbalance": "1", // siafunds, big int
"siacoinclaimbalance": "9001", // hastings, big int
"dustthreshold": "1234", // hastings / byte, big int
}loads a v0.3.3.x wallet into the current wallet, harvesting all of the secret keys. All spendable addresses in the loaded wallet will become spendable from the current wallet.
Query String Parameters (with comments)
source
encryptionpassword
standard success or error response. See #standard-responses.
gets a new address from the wallet generated by the primary seed. An error will be returned if the wallet is locked.
JSON Response (with comments)
{
"address": "1234567890abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789ab"
}fetches the list of addresses from the wallet. If the wallet has not been created or unlocked, no addresses will be returned. After the wallet is unlocked, this call will continue to return its addresses even after the wallet is locked again.
JSON Response (with comments)
{
"addresses": [
"1234567890abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789ab",
"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
]
}creates a backup of the wallet settings file. Though this can easily be done manually, the settings file is often in an unknown or difficult to find location. The /wallet/backup call can spare users the trouble of needing to find their wallet file.
Parameters (with comments)
destination
standard success or error response. See #standard-responses.
initializes the wallet. After the wallet has been initialized once, it does not need to be initialized again, and future calls to /wallet/init will return an error. The encryption password is provided by the api call. If the password is blank, then the password will be set to the same as the seed.
Query String Parameters (with comments)
encryptionpassword
dictionary // Optional, default is english.
force // Optional, when set to true it will destroy an existing wallet and reinitialize a new one.
JSON Response (with comments)
{
"primaryseed": "hello world hello world hello world hello world hello world hello world hello world hello world hello world hello world hello world hello world hello world hello world hello"
}initializes the wallet using a preexisting seed. After the wallet has been initialized once, it does not need to be initialized again, and future calls to /wallet/init/seed will return an error. The encryption password is provided by the api call. If the password is blank, then the password will be set to the same as the seed. Note that loading a preexisting seed requires scanning the blockchain to determine how many keys have been generated from the seed. For this reason, /wallet/init/seed can only be called if the blockchain is synced.
Query String Parameters (with comments)
encryptionpassword
dictionary // Optional, default is english.
seed
force // Optional, when set to true it will destroy an existing wallet and reinitialize a new one.
standard success or error response. See #standard-responses.
gives the wallet a seed to track when looking for incoming transactions. The wallet will be able to spend outputs related to addresses created by the seed. The seed is added as an auxiliary seed, and does not replace the primary seed. Only the primary seed will be used for generating new addresses.
Query String Parameters (with comments)
encryptionpassword
dictionary
seed
standard success or error response. See #standard-responses.
returns the list of seeds in use by the wallet. The primary seed is the only seed that gets used to generate new addresses. This call is unavailable when the wallet is locked.
Query String Parameters (with comments)
dictionary
JSON Response (with comments)
{
"primaryseed": "hello world hello world hello world hello world hello world hello world hello world hello world hello world hello world hello world hello world hello world hello world hello",
"addressesremaining": 2500,
"allseeds": [
"hello world hello world hello world hello world hello world hello world hello world hello world hello world hello world hello world hello world hello world hello world hello",
"foo bar foo bar foo bar foo bar foo bar foo bar foo bar foo bar foo bar foo bar foo bar foo bar foo bar foo bar foo",
]
}sends siacoins to an address or set of addresses. The outputs are arbitrarily selected from addresses in the wallet. If 'outputs' is supplied, 'amount' and 'destination' must be empty.
Query String Parameters (with comments)
amount // hastings
destination // address
outputs // JSON array of {unlockhash, value} pairs
JSON Response (with comments)
{
"transactionids": [
"1234567890abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
]
}sends siafunds to an address. The outputs are arbitrarily selected from addresses in the wallet. Any siacoins available in the siafunds being sent (as well as the siacoins available in any siafunds that end up in a refund address) will become available to the wallet as siacoins after 144 confirmations. To access all of the siacoins in the siacoin claim balance, send all of the siafunds to an address in your control (this will give you all the siacoins, while still letting you control the siafunds).
Query String Parameters (with comments)
amount // siafunds
destination // address
JSON Response (with comments)
{
"transactionids": [
"1234567890abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
]
}loads a key into the wallet that was generated by siag. Most siafunds are currently in addresses created by siag.
Query String Parameters (with comments)
encryptionpassword
keyfiles
standard success or error response. See #standard-responses.
Function: Scan the blockchain for outputs belonging to a seed and send them to an address owned by the wallet.
Query String Parameters (with comments)
dictionary // Optional, default is english.
seed
JSON Response (with comments)
{
"coins": "123456", // hastings, big int
"funds": "1", // siafunds, big int
}locks the wallet, wiping all secret keys. After being locked, the keys are encrypted. Queries for the seed, to send siafunds, and related queries become unavailable. Queries concerning transaction history and balance are still available.
standard success or error response. See #standard-responses.
gets the transaction associated with a specific transaction id.
Path Parameters (with comments)
:id
JSON Response (with comments)
{
"transaction": {
"transaction": {
// See types.Transaction in https://github.com/NebulousLabs/Sia/blob/master/types/transactions.go
},
"transactionid": "1234567890abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
"confirmationheight": 50000,
"confirmationtimestamp": 1257894000,
"inputs": [
{
"parentid": "1234567890abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
"fundtype": "siacoin input",
"walletaddress": false,
"relatedaddress": "1234567890abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789ab",
"value": "1234", // hastings or siafunds, depending on fundtype, big int
}
],
"outputs": [
{
"id": "1234567890abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
"fundtype": "siacoin output",
"maturityheight": 50000,
"walletaddress": false,
"relatedaddress": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"value": "1234", // hastings or siafunds, depending on fundtype, big int
}
]
}
}returns a list of transactions related to the wallet in chronological order.
Query String Parameters (with comments)
startheight // block height
endheight // block height
JSON Response (with comments)
{
"confirmedtransactions": [
{
// See the documentation for '/wallet/transaction/:id' for more information.
}
],
"unconfirmedtransactions": [
{
// See the documentation for '/wallet/transaction/:id' for more information.
}
]
}returns all of the transactions related to a specific address.
Path Parameters (with comments)
:addr
JSON Response (with comments)
{
"transactions": [
{
// See the documentation for '/wallet/transaction/:id' for more information.
}
]
}unlocks the wallet. The wallet is capable of knowing whether the correct password was provided.
Query String Parameters (with comments)
encryptionpassword
standard success or error response. See #standard-responses.
takes the address specified by :addr and returns a JSON response indicating if the address is valid.
JSON Response (with comments)
{
"valid": true
}changes the wallet's encryption key.
Query String Parameters (with comments)
encryptionpassword
newpassword
standard success or error response. See #standard-responses.