Sia coin-API Quickstart Guide





  • This guide will walk you through uploading a file to Sia using the API. Complete API documentation can be found at https://github.com/NebulousLabs/Sia/blob/master/doc/API.md

    Examples are given in Curl and Sia.js

    Setup and Configuration

    If you haven’t already, download the Sia Daemon. The Sia Daemon runs a Sia node as well as hosts the API.

    By default the API listens on <strong>localhost:9980</strong>. You can change this using the <strong>--api-addr</strong> flag. Be sure to specify <strong>localhost:port</strong>, otherwise you may be exposing your daemon’s API to the internet, which can result in stolen coins.

    By default the daemon stores persist data (such as your wallet) in the current directory. You can specify a directory to use with the -d flag. Go ahead and start the Sia Daemon. <strong>siad -d sia-data</strong>

    You can also start the daemon form sia.js. All of the following examples given in SiaJS will assume that the daemon has been launched like so.

    <code class="language-javascript">import { launch } from 'sia.js'
    try {  
      const daemon = launch('/path/to/your/siad', {
        'sia-directory': 'sia-data',
      })
      daemon.on('error', (err) => console.log('siad encountered an error ' + err))
    } catch (e) {
      console.error('error launching siad: ' + e.toString())
    }
    </code>
    

    Basics

    Let’s check the status of blockchain download using the /consensus endpoint.

    Curl
    <code>$curl -i -A “Sia-Agent” localhost:9980/consensus
    HTTP/1.1 200 OK  
    Content-Type: application/json; charset=utf-8  
    Date: Mon, 17 Oct 2016 05:50:47 GMT  
    Content-Length: 186
    {
        "synced": false,
        "height": 0,
        "currentblock": "25f6e3b9295a61f69fcb956aca9f0076234ecf2e02d399db5448b6e22f26e81c",
        "target": [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]
    }
    </code>
    
    SiaJS
    <code class="language-javascript">try {  
      const consensus = await daemon.call('/consensus')
      // do something with result consensus
    } catch (e) {
      // do something with error e
    }
    </code>
    

    Note that the user agent needs to be set to “Sia-Agent”. This happens automatically in Sia.js. This is necessary to prevent certain classes of browser based attacks.

    The consensus endpoint returns the current state of the blockchain. You should not attempt to spend coins or upload files until the blockchain has been downloaded. This may take several hours. When the /consensus endpoints returns “synced”: true the blockchain has been downloaded.

    While we are waiting we can setup the wallet. If this is your first time running the daemon you’ll need to initialize a new wallet.

    Curl
    <code>$curl -i -A “Sia-Agent” -X POST localhost:9980/wallet/init
    HTTP/1.1 200 OK  
    Content-Type: application/json; charset=utf-8  
    Date: Mon, 17 Oct 2016 06:48:24 GMT  
    Content-Length: 209
    {
        "primaryseed": "foo bar baz foo bar baz foo bar baz foo bar baz foo bar baz foo bar baz foo bar baz foo bar baz foo bar baz foo bar“
    }
    </code>
    
    SiaJS
    <code class="language-javascript">try {  
      const wallet = await daemon.call({
        url: '/wallet/init',
        method: 'POST',
      })
    } catch (e) {
      // do something with error e
    }
    </code>
    

    The primary seed can be used to recover your wallet should you lose the sia-data directory. Write it down and keep it in a safe place. By default the seed is also used as the encryption password.

    Now that we have initialize a wallet, we need to unlock it. The wallet needs to be unlocked to spend Siacoins, including uploading files. You’ll need to unlock the wallet every time you start Sia Daemon. This call will block while the wallet is unlocking and may therefore take several minutes to complete.

    Curl
    <code>$curl -i -A “Sia-Agent” -X POST localhost:9980/wallet/unlock?encryptionpassword=foo%20bar%20baz%20foo%20bar%20baz%20foo%20bar%20baz%20foo%20bar%20baz%20foo%20bar%20baz%20foo%20bar%20baz%20foo%20bar%20baz%20foo%20bar%20baz%20foo%20bar%20baz%20foo%20bar
    HTTP/1.1 204 No Content  
    Date: Mon, 17 Oct 2016 07:01:12 GMT  
    </code>
    
    SiaJS
    <code class="language-javascript">try {  
      await daemon.call({
        url: '/wallet/unlock',
        method: 'POST',
        qs: {
          encryptionpassword: 'foo bar baz foo bar baz foo bar baz foo bar baz foo bar baz foo bar baz foo bar baz foo bar baz foo bar baz foo bar',
        },
      })
    } catch (e) {
      // do something with error e
    }
    </code>
    

    You'll need Siacoins in your wallet before you can upload any files to the network. To do this you must send coins to your wallet. The wallet provides an endpoint for getting a new wallet address. Send coins to this address.

    Curl
    <code>$ curl -i -A "Sia-Agent" localhost:9980/wallet/address
    HTTP/1.1 200 OK  
    Content-Type: application/json; charset=utf-8  
    Date: Mon, 17 Oct 2016 20:15:13 GMT  
    Content-Length: 91
    {
        "address": "1234567890abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789ab"
    }
    </code>
    
    SiaJS
    <code class="language-javascript">try {  
      const wallet = await daemon.call('/wallet/address')
      // do something with wallet.address
    } catch (e) {
      // do something with error e
    }
    </code>
    

    Before continuing, wait for /consensus to return "synced": true.

    Uploading and Downloading Files

    Before we can upload files we must configure the renter. Primarily, we need to allocate funds and specify the contract period. The contract period is the minimum duration of time we want to store files, and is also the minimum amount of time you pay for at once. For example, to allocate 1000 SC (1000000000000000000000000000 Hastings) for the renter with a 1 month (4320 blocks) contract period:

    Curl
    <code>$ curl -i -A "Sia-Agent" -X POST "localhost:9980/renter?funds=1000000000000000000000000000&period=4320"
    HTTP/1.1 204 No Content  
    Date: Mon, 17 Oct 2016 07:01:12 GMT  
    </code>
    
    SiaJS
    <code class="language-javascript">try {  
      await daemon.call({
        url: '/renter',
        method: 'POST',
        qs: {
          funds: '1000000000000000000000000000',
          period: 4320,
        },
      })
    } catch (e) {
      // do something with error e
    }
    </code>
    

    This call will block until the Sia Daemon has formed contracts with a sufficient number of hosts.

    We can now upload files to the network. The following call will upload the local file /home/foo/bar.txt to /qux/bar.txt on the network.

    Curl
    <code>$ curl -i -A "Sia-Agent" -X POST localhost:9980/renter/upload/qux/bar.txt?source=/home/foo/bar.txt
    HTTP/1.1 204 No Content  
    Date: Mon, 17 Oct 2016 07:01:12 GMT  
    </code>
    
    SiaJS
    <code class="language-javascript">try {  
      await daemon.call({
        url: '/renter/upload/qux/bar.txt',
        method: 'POST',
        qs: {
          source: '/home/foo/bar.txt',
        },
      })
    } catch (e) {
      // do something with error e
    }
    </code>
    

    This call will return immediately. We can check the progress of the upload with the following call

    Curl
    <code>$ curl -i -A "Sia-Agent" localhost:9980/renter/files
    HTTP/1.1 200 OK  
    Content-Type: application/json; charset=utf-8  
    Date: Wed, 19 Oct 2016 22:26:36 GMT  
    Content-Length: 125
    {
        "files": [
          {
            "siapath":        "qux/bar.txt",
            "filesize":       8192,
            "available":      false,
            "renewing":       true,
            "redundancy":     0.5,
            "uploadprogress": 10
          }
        ]
    }
    </code>
    
    SiaJS
    <code class="language-javascript">try {  
      const renter = await daemon.call('/renter/files')
      // use renter.files to check the upload progress
    } catch (e) {
      // do something with error e
    }
    </code>
    

    Once /renter/files returns "available": true, that file can be downloaded. Files may become available for download before uploadprogress reaches 100. This is because files are uploaded with redundancy.

    We can download files with the /renter/download endpoint.

    Curl
    <code>$ curl -i -A "Sia-Agent" localhost:9980/renter/download/qux/bar.txt?destination=/home/foo/bar.txt
    HTTP/1.1 204 No Content  
    Date: Mon, 17 Oct 2016 07:01:12 GMT  
    </code>
    
    SiaJS
    <code>try {  
      await daemon.call({
        url: '/renter/download/qux/bar.txt',
        qs: {
          source: '/home/foo/bar.txt',
        },
      })
    } catch (e) {
      // do something with error e
    }
    </code>
    

    The call will block until the file has been downloaded. While the file is downloading you can check the progress with the /renter/downloads endpoint.

    Curl
    <code>$ curl -i -A "Sia-Agent" localhost:9980/renter/downloads
    HTTP/1.1 200 OK  
    Content-Type: application/json; charset=utf-8  
    Date: Wed, 19 Oct 2016 22:26:36 GMT  
    Content-Length: 125
    {
        "downloads": [
          {
            "siapath":     "qux/bar.txt",
            "destination": "/home/foo/bar.txt",
            "filesize":    8192,
            "received":    4096,
            "starttime":   "2009-11-10T23:00:00Z",
          },
        ]
    }
    </code>
    
    SiaJS
    <code class="language-javascript">try {  
      const renter = await daemon.call('/renter/downloads')
      // use renter.downloads to check the download progress
    } catch (e) {
      // do something with error e
    }
    </code>
    

    Now that we've covered the basics of using the API, you can find the complete API documentation at https://github.com/NebulousLabs/Sia/blob/master/doc/API.md