StreamCardano API primer

24 Oct 2022

Here we will show you how to try out your StreamCardano.com access key!

Check that service is online

I suggest that you start by testing our API is online.

First setup the environment variables:

STREAMCARDANO_HOST=beta.streamcardano.dev
STREAMCARDANO_KEY="...your API key here..."

To make sure your internet connection works:

curl https://${STREAMCARDANO_HOST}/api/v1/status

You should see something like this:

{"postgresWorking":true
,"triggers":..
,"pgbouncerWorking":true
,"appVersion":"0.1.0.0"
,"appCommit":"ad2f9544d23ca2d93e0923695c761f1aeaf4763a"}

You can also use this endpoint to check you work on the latest version of the application API library.

This is the only call that does not require autorization. You may also see the API status here

To pretty-print the query result you may use json_pp or aeson_pretty:

curl https://beta.streamcardano.dev/api/v1/status | json_pp
{
   "appVersionInfo" : {
      "appCommit" : "9e544eae29f6451af22224206eefc540b043d73d",
      "appVersion" : "0.1.0.0",
      "envName" : "ProductionEnv"
   },
   "pgbouncerWorking" : true,
   "postgresWorking" : true,
   "triggers" : [
      {
         "triggerEventManipulation" : "INSERT",
         "triggerEventTable" : "block",
         "triggerName" : "blocks_changed"
      },
      {
         "triggerEventManipulation" : "DELETE",
         "triggerEventTable" : "block",
         "triggerName" : "blocks_changed"
      },
      {
         "triggerEventManipulation" : "UPDATE",
         "triggerEventTable" : "block",
         "triggerName" : "blocks_changed"
      }
   ]
}

Checking if StreamCardano is up-to-date with Cardano network?

You need to set API key for anything else:

export STREAMCARDANO_KEY=${STREAMCARDANO_KEY}

You may now check what is the last block id recorded in the database:

curl -H "Authorization: Bearer ${STREAMCARDANO_KEY}" \
     https://${STREAMCARDANO_HOST}/api/v1/last/block

Authorization

Note the -H "Authorization: Bearer $STREAMCARDANO_KEY" header that authorizes use of the interface.

You have developer key with a unique id for your application. For now you may use all developer API at limited rate. To deploy in production, you will get a key with only limited functionality by much higher allowed query rate to permit thousands of users simultaneously.

Make a custom query

You may learn more about the last Cardano block using custom query:

curl -q -X POST "https://${STREAMCARDANO_HOST}/api/v1/query" \
     -H "Authorization: Bearer $TOKEN"                            \
     -H 'Content-Type: text/plain;charset=utf-8'                  \
     --data 'SELECT block_no,hash,tx_count from block order by id desc LIMIT 1' -w "\n%{http_code}\n"
[
   {
      "block_no" : 3680594,
      "hash" : "\\xd931221f9bc4cae34de422d9f4281a2b0344e86aac6b31eb54e2ee90f44a09b9",
      "tx_count" : 10
   }
]

Listing transactions of your smart contract

Let’s search for recent transaction outputs from smart contracts on the Testnet:

curl -q -X POST "https://${STREAMCARDANO_HOST}/api/v1/query" \
     -H "Authorization: Bearer $TOKEN"                               \
     -H 'Content-Type: text/plain;charset=utf-8'                     \
     --data "SELECT tx_id, value \
             FROM datum \
             ORDER BY tx_id DESC LIMIT 1"
[
   {
      "tx_id" : 4978278,
      "value" : {
         "constructor" : 0,
         "fields" : [
            {
               "constructor" : 0,
               "fields" : [
                  {
                     "int" : 29
                  },
                  {
                     "int" : 64500655
                  }
               ]
            },
            {
               "constructor" : 0,
               "fields" : [
                  {
                     "constructor" : 0,
                     "fields" : [
                        {
                           "bytes" : "966f83adda6b0514102ad923910ffdfb463a16b7783eeb63e5b663a3"
                        }
                     ]
                  },
                  {
                     "constructor" : 0,
                     "fields" : [
                        {
                           "constructor" : 0,
                           "fields" : [
                              {
                                 "constructor" : 0,
                                 "fields" : [
                                    {
                                       "bytes" : "b0f969c22d45b4ad36fbbb521513fbdf5351a84ab21083ca270d94fb"
                                    }
                                 ]
                              }
                           ]
                        }
                     ]
                  }
               ]
            },
            {
               "constructor" : 0,
               "fields" : [
                  {
                     "int" : 2341347195813345
                  },
                  {
                     "int" : 1073741824
                  }
               ]
            },
            {
               "int" : 1656879710000
            },
            {
               "constructor" : 0,
               "fields" : [
                  {
                     "bytes" : "d073fba04de32cdea8e37de2ba6348850415e7adbafd1407ff77e124"
                  }
               ]
            }
         ]
      }
   }
]

Debug your query

curl -q -X POST "https://${STREAMCARDANO_HOST}/api/v1/debug/query" \
     -H "Authorization: Bearer $TOKEN"                               \
     -H 'Content-Type: text/plain;charset=utf-8'                     \
     --data "WITH dats AS (SELECT datum.tx_id, datum.value \
             FROM datum, tx_out \
             WHERE datum.tx_id=tx_out.tx_id) \
             SELECT * FROM dats ORDER BY tx_id DESC LIMIT 1"
{
   "CompileTime" : 0.003751576,
   "EXPLAIN" : [
      "Limit  (cost=3106846.97..3106846.97 rows=1 width=40)",
      "  CTE dats",
      "    ->  Merge Join  (cost=1690196.68..2675203.90 rows=17265723 width=917)",
      "          Merge Cond: (tx_out.tx_id = datum.tx_id)",
      "          ->  Index Only Scan using idx_tx_out_tx_id on tx_out  (cost=0.43..786046.51 rows=13825337 width=8)",
      "          ->  Materialize  (cost=1592925.03..1598390.94 rows=1093182 width=917)",
      "                ->  Sort  (cost=1592925.03..1595657.99 rows=1093182 width=917)",
      "                      Sort Key: datum.tx_id",
      "                      ->  Seq Scan on datum  (cost=0.00..160561.82 rows=1093182 width=917)",
      "  ->  Sort  (cost=431643.08..474807.38 rows=17265723 width=40)",
      "        Sort Key: dats.tx_id DESC",
      "        ->  CTE Scan on dats  (cost=0.00..345314.46 rows=17265723 width=40)"
   ],
   "OrigSQL" : "WITH dats AS (SELECT datum.tx_id, datum.value              FROM datum, tx_out              WHERE datum.tx_id=tx_out.tx_id)              SELECT * FROM dats ORDER BY tx_id DESC LIMIT 1",
   "Params" : [],
   "SQL" : "SELECT json_agg(t) FROM (WITH dats AS (SELECT datum.tx_id, datum.value FROM (SELECT datum.* FROM datum INNER JOIN tx ON datum.tx_id = tx.id INNER JOIN (SELECT * FROM block WHERE block_no <= $1) AS block ON block.id = tx.block_id ORDER BY datum.id DESC LIMIT $2) AS datum, (SELECT tx_out.* FROM tx_out INNER JOIN tx ON tx_out.tx_id = tx.id INNER JOIN (SELECT * FROM block WHERE block_no <= $1) AS block ON block.id = tx.block_id ORDER BY tx_out.id DESC LIMIT $2) AS tx_out WHERE datum.tx_id = tx_out.tx_id) SELECT * FROM dats ORDER BY tx_id DESC LIMIT 1) AS t"
}

To see all data from smart contract transactions on the testnet use:

curl -q -X POST "https://${STREAMCARDANO_HOST}/api/v1/query" \
     -H "Authorization: Bearer $TOKEN"                               \
     -H 'Content-Type: text/plain;charset=utf-8'                     \
     --data "WITH dats AS (SELECT datum.tx_id, datum.value \
             FROM datum, tx_out \
             WHERE datum.tx_id=tx_out.tx_id) \
             SELECT * FROM dats ORDER BY tx_id DESC LIMIT 1" | json_pp
[
   {
      "tx_id" : 4978278,
      "value" : {
         "constructor" : 0,
         "fields" : [
            {
               "constructor" : 0,
               "fields" : [
                  {
                     "bytes" : "4d9ff149bb3e9812f9a3cc2a70656a8394485b45595cac743c7ff74d034b86576469eb9b7cb34c487c2ef3345a947d33e7ec0900b8ea8ef25be878de9ab34707"
                  },
                  {
                     "constructor" : 0,
                     "fields" : [
                        {
                           "constructor" : 0,
                           "fields" : [
                              {
                                 "int" : 2341347195813345
                              },
                              {
                                 "int" : 1073741824
                              }
                           ]
                        },
                        {
                           "constructor" : 0,
                           "fields" : [
                              {
                                 "constructor" : 0,
                                 "fields" : [
                                    {
                                       "constructor" : 1,
                                       "fields" : [
                                          {
                                             "int" : 1656878768001
                                          }
                                       ]
                                    },
                                    {
                                       "constructor" : 1,
                                       "fields" : []
                                    }
                                 ]
                              },
                              {
                                 "constructor" : 0,
                                 "fields" : [
                                    {
                                       "constructor" : 1,
                                       "fields" : [
                                          {
                                             "int" : 1656880568001
                                          }
                                       ]
                                    },
                                    {
                                       "constructor" : 1,
                                       "fields" : []
                                    }
                                 ]
                              }
                           ]
                        },
                        {
                           "bytes" : "555344"
                        }
                     ]
                  },
                  {
                     "constructor" : 0,
                     "fields" : [
                        {
                           "bytes" : "85915ed66d676887fd4f3f4b628b07acf8f8858588b7f4169f5fd6c3"
                        },
                        {
                           "bytes" : "446a65644f7261636c654e4654"
                        }
                     ]
                  }
               ]
            }
         ]
      }
   }
]

Please note that during beta version you may want to avoid SQL JOIN syntax, instead of FROM datum JOIN tx_out by datum.tx_id=tx_out.tx_id you may use FROM datum, tx_out WHERE datum.tx_id=tx_out.tx_id.

Coming soon…

Soon we will contact you again about:

  • testing scripts on the mainnet
  • viewing script data (redeemer data)
  • effortless live updates
  • Elm, JavaScript demos!