Fetch and decode V4 reports using the Go SDK

Guide Versions

This guide is available in multiple versions. Choose the one that matches your needs.

In this guide, you'll learn how to use Chainlink Data Streams with the Streams Direct implementation and the Data Streams SDK for Go to fetch and decode V4 reports for Real World Assets (RWAs) streams from the Data Streams Aggregation Network. You'll set up your Go project, retrieve reports, decode them, and log their attributes.

Requirements

  • Git: Make sure you have Git installed. You can check your current version by running git --version in your terminal and download the latest version from the official Git website if necessary.
  • Go Version: Make sure you have Go version 1.21 or higher. You can check your current version by running go version in your terminal and download the latest version from the official Go website if necessary.
  • API Credentials: Access to the Streams Direct implementation requires API credentials. If you haven't already, contact us to request mainnet or testnet early access.

Guide

You'll start with the set up of your Go project. Next, you'll fetch and decode reports for both single and multiple RWA streams, and log their attributes to your terminal.

Set up your Go project

  1. Create a new directory for your project and navigate to it:

    mkdir my-data-streams-project
cd my-data-streams-project

  2. Initialize a new Go module:

    go mod init my-data-streams-project

  3. Install the Data Streams SDK:

    go get github.com/smartcontractkit/data-streams-sdk/go

Fetch and decode a report with a single stream

  1. Create a new Go file, single-stream.go, in your project directory:

    touch single-stream.go

  2. Insert the following code example and save your single-stream.go file:

     package main

 import (
     "context"
     "fmt"
     "os"
     "time"

     streams "github.com/smartcontractkit/data-streams-sdk/go"
     feed "github.com/smartcontractkit/data-streams-sdk/go/feed"
     report "github.com/smartcontractkit/data-streams-sdk/go/report"
     v4 "github.com/smartcontractkit/data-streams-sdk/go/report/v4" // Import the v4 report schema for RWA streams. For Crypto streams, use the v3 schema.
 )

 func main() {
     // Validate command-line arguments
     if len(os.Args) < 2 {
         fmt.Printf("Usage: go run main.go [FeedID]\nExample: go run main.go 0x000434a5b30cafe7e853832a458ea1591dc2f5fb5e4cf80b9979b8248065a7ea\n")
         os.Exit(1)
     }
     feedIDInput := os.Args[1]

     // Get API credentials from environment variables
     apiKey := os.Getenv("API_KEY")
     apiSecret := os.Getenv("API_SECRET")
     if apiKey == "" || apiSecret == "" {
         fmt.Printf("API_KEY and API_SECRET environment variables must be set\n")
         os.Exit(1)
     }

     // Define the configuration for the SDK client
     cfg := streams.Config{
         ApiKey:    apiKey,
         ApiSecret: apiSecret,
         RestURL:   "https://api.testnet-dataengine.chain.link",
         Logger:    streams.LogPrintf,
     }

     // Initialize the SDK client
     client, err := streams.New(cfg)
     if err != nil {
         cfg.Logger("Failed to create client: %v\n", err)
         os.Exit(1)
     }

     // Create context with timeout
     ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
     defer cancel()

     // Parse the feed ID
     var feedID feed.ID
     if err := feedID.FromString(feedIDInput); err != nil {
         cfg.Logger("Invalid feed ID format '%s': %v\n", feedIDInput, err)
         os.Exit(1)
     }

     // Fetch the latest report
     reportResponse, err := client.GetLatestReport(ctx, feedID)
     if err != nil {
         cfg.Logger("Failed to get latest report: %v\n", err)
         os.Exit(1)
     }

     // Log the raw report data
     cfg.Logger("Raw report data: %+v\n", reportResponse)

     // Decode the report
     decodedReport, err := report.Decode[v4.Data](reportResponse.FullReport)
     if err != nil {
         cfg.Logger("Failed to decode report: %v\n", err)
         os.Exit(1)
     }

     // Format and display the decoded report
     fmt.Printf("\nDecoded Report for Stream ID %s:\n"+
         "------------------------------------------\n"+
         "Observations Timestamp: %d\n"+
         "Benchmark Price       : %s\n"+
         "Valid From Timestamp  : %d\n"+
         "Expires At            : %d\n"+
         "Link Fee              : %s\n"+
         "Native Fee            : %s\n"+
         "Market Status         : %d\n"+
         "------------------------------------------\n",
         feedIDInput,
         decodedReport.Data.ObservationsTimestamp,
         decodedReport.Data.BenchmarkPrice.String(),
         decodedReport.Data.ValidFromTimestamp,
         decodedReport.Data.ExpiresAt,
         decodedReport.Data.LinkFee.String(),
         decodedReport.Data.NativeFee.String(),
         decodedReport.Data.MarketStatus,
     )
 }

  3. Download the required dependencies and update the go.mod and go.sum files:

    go mod tidy

  4. Set up the SDK client configuration within single-stream.go with your API credentials and the REST endpoint:

    cfg := streams.Config{
    ApiKey:    os.Getenv("API_KEY"),
    ApiSecret: os.Getenv("API_SECRET"),
    RestURL:   "https://api.testnet-dataengine.chain.link",
    Logger: streams.LogPrintf,
}

    • Set your API credentials as environment variables:

      export API_KEY="<YOUR_API_KEY>"
export API_SECRET="<YOUR_API_SECRET>"

      Replace <YOUR_API_KEY> and <YOUR_API_SECRET> with your API credentials.

    • RestURL is the REST endpoint to poll for specific reports. See the Streams Direct Interface page for more information.

    See the SDK Reference page for more configuration options.

  5. For this example, you will read from the AUD/USD stream. This stream ID is 0x000434a5b30cafe7e853832a458ea1591dc2f5fb5e4cf80b9979b8248065a7ea. See the Data Streams RWA streams page for a complete list of available Real World Assets.

    Execute your application:

    go run single-stream.go 0x000434a5b30cafe7e853832a458ea1591dc2f5fb5e4cf80b9979b8248065a7ea

    Expect output similar to the following in your terminal:

    2024-12-14T17:50:49-05:00 Raw report data: {"fullReport":"0x0006aee203ef23a892e75b579f8c3f26fd933d9ca45de95c2f8ac470f4ddcd76000000000000000000000000000000000000000000000000000000000b75880c000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000e00000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000026001000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000100000434a5b30cafe7e853832a458ea1591dc2f5fb5e4cf80b9979b8248065a7ea00000000000000000000000000000000000000000000000000000000675e0bc900000000000000000000000000000000000000000000000000000000675e0bc90000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000675f5d4900000000000000000000000000000000000000000000000008d460e8b7e50000000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000023f21e9d219ae8e279d13a36b09a439ed71c0d1118561a93987c665fbad13cb6e37bd3763d7ef840b05fda0671b01f26f3c073bef1f3b53fcd9429836ba25eae600000000000000000000000000000000000000000000000000000000000000026bd87b2293422e41ec242088d8feedbe126474b791a85e54450af84e21d017fd59158fbe4adf47dcabe54c11a8ca606659e060839474545eb9b13bf5e7c902df","feedID":"0x000434a5b30cafe7e853832a458ea1591dc2f5fb5e4cf80b9979b8248065a7ea","validFromTimestamp":1734216649,"observationsTimestamp":1734216649}

2024-12-14T17:50:49-05:00
Decoded Report for Stream ID 0x000434a5b30cafe7e853832a458ea1591dc2f5fb5e4cf80b9979b8248065a7ea:
------------------------------------------
Observations Timestamp: 1734216649
Benchmark Price       : 636240000000000000
Valid From Timestamp  : 1734216649
Expires At            : 1734303049
Link Fee              : 0
Native Fee            : 0
Market Status         : 1
------------------------------------------

Decoded report details

The decoded report details include:

AttributeValueDescription
Stream ID0x000434a5b30cafe7e853832a458ea1591dc2f5fb5e4cf80b9979b8248065a7eaThe unique identifier for the stream. In this example, the stream is for AUD/USD.
Observations Timestamp1734216649The timestamp indicating when the data was captured.
Benchmark Price636240000000000000The observed price in the report, with 18 decimals. For readability: 0.63624 USD per AUD.
Valid From Timestamp1734216649The start validity timestamp for the report, indicating when the data becomes relevant.
Expires At1734303049The expiration timestamp of the report, indicating the point at which the data becomes outdated.
Link Fee0The fee to pay in LINK tokens for the onchain verification of the report data. With 18 decimals. Note: This example fee is not indicative of actual fees.
Native Fee0The fee to pay in the native blockchain token (e.g., ETH on Ethereum) for the onchain verification of the report data. With 18 decimals. Note: This example fee is not indicative of actual fees.
Market Status1The DON's consensus on whether the market is currently open. Possible values: 0 (Unknown), 1 (Closed), 2 (Open).

Payload for onchain verification

In this guide, you log and decode the fullReport payload to extract the report data. In a production environment, you should verify the data to ensure its integrity and authenticity. Refer to the Verify report data onchain guide.

Fetch and decode reports for multiple streams

  1. Create a new Go file, multiple-streams.go, in your project directory:

    touch multiple-streams.go

  2. Insert the following code example in your multiple-streams.go file:

     package main

 import (
     "context"
     "fmt"
     "os"
     "time"

     streams "github.com/smartcontractkit/data-streams-sdk/go"
     feed "github.com/smartcontractkit/data-streams-sdk/go/feed"
     report "github.com/smartcontractkit/data-streams-sdk/go/report"
     v4 "github.com/smartcontractkit/data-streams-sdk/go/report/v4" // Import the v4 report schema for RWA streams
 )

 func main() {
     // Validate command-line arguments
     if len(os.Args) < 3 {
         fmt.Printf("Usage: go run multiple-streams.go [StreamID1] [StreamID2] ...\n"+
             "Example: go run multiple-streams.go "+
             "0x000434a5b30cafe7e853832a458ea1591dc2f5fb5e4cf80b9979b8248065a7ea "+
             "0x0004b9905d8337c34e00f8dbe31619428bac5c3937e73e6af75c71780f1770ce\n")
         os.Exit(1)
     }

     // Get API credentials from environment variables
     apiKey := os.Getenv("API_KEY")
     apiSecret := os.Getenv("API_SECRET")
     if apiKey == "" || apiSecret == "" {
         fmt.Printf("API_KEY and API_SECRET environment variables must be set\n")
         os.Exit(1)
     }

     // Define the configuration for the SDK client
     cfg := streams.Config{
         ApiKey:    apiKey,
         ApiSecret: apiSecret,
         RestURL:   "https://api.testnet-dataengine.chain.link",
         Logger:    streams.LogPrintf,
     }

     // Initialize the SDK client
     client, err := streams.New(cfg)
     if err != nil {
         cfg.Logger("Failed to create client: %v\n", err)
         os.Exit(1)
     }

     // Create context with timeout
     ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
     defer cancel()

     // Parse Feed IDs
     var ids []feed.ID
     for _, arg := range os.Args[1:] {
         var fid feed.ID
         if err := fid.FromString(arg); err != nil {
             cfg.Logger("Invalid feed ID format '%s': %v\n", arg, err)
             continue
         }
         ids = append(ids, fid)
     }

     if len(ids) == 0 {
         cfg.Logger("No valid feed IDs provided\n")
         os.Exit(1)
     }

     // Fetch reports for all streams
     timestamp := uint64(time.Now().Unix())
     reportResponses, err := client.GetReports(ctx, ids, timestamp)
     if err != nil {
         cfg.Logger("Failed to get reports: %v\n", err)
         os.Exit(1)
     }

     // Process reports
     for _, reportResponse := range reportResponses {
         // Log the raw report data
         cfg.Logger("Raw report data for Stream ID %s: %+v\n",
             reportResponse.FeedID.String(), reportResponse)

         // Decode the report
         decodedReport, err := report.Decode[v4.Data](reportResponse.FullReport)
         if err != nil {
             cfg.Logger("Failed to decode report for Stream ID %s: %v\n",
                 reportResponse.FeedID.String(), err)
             continue // Skip to next report if decoding fails
         }

         // Format and display the decoded report
         fmt.Printf("\nDecoded Report for Stream ID %s:\n"+
             "------------------------------------------\n"+
             "Observations Timestamp: %d\n"+
             "Benchmark Price       : %s\n"+
             "Valid From Timestamp  : %d\n"+
             "Expires At            : %d\n"+
             "Link Fee              : %s\n"+
             "Native Fee            : %s\n"+
             "Market Status         : %d\n"+
             "------------------------------------------\n",
             reportResponse.FeedID.String(),
             decodedReport.Data.ObservationsTimestamp,
             decodedReport.Data.BenchmarkPrice.String(),
             decodedReport.Data.ValidFromTimestamp,
             decodedReport.Data.ExpiresAt,
             decodedReport.Data.LinkFee.String(),
             decodedReport.Data.NativeFee.String(),
             decodedReport.Data.MarketStatus,
         )
     }
 }

  3. Before running the example, verify that your API credentials are still set in your current terminal session:

    echo $API_KEY
echo $API_SECRET

    If the commands above don't show your credentials, set them again:

    export API_KEY="<YOUR_API_KEY>"
export API_SECRET="<YOUR_API_SECRET>"

  4. For this example, you will read from the AUD/USD and EUR/USD RWA streams. Run your application:

    go run multiple-streams.go 0x000434a5b30cafe7e853832a458ea1591dc2f5fb5e4cf80b9979b8248065a7ea 0x0004b9905d8337c34e00f8dbe31619428bac5c3937e73e6af75c71780f1770ce

    Expect to see output similar to the following in your terminal:

    2024-12-14T17:53:30-05:00 Raw report data for Stream ID 0x000434a5b30cafe7e853832a458ea1591dc2f5fb5e4cf80b9979b8248065a7ea: {"fullReport":"0x0006aee203ef23a892e75b579f8c3f26fd933d9ca45de95c2f8ac470f4ddcd76000000000000000000000000000000000000000000000000000000000b75a101000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000e00000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000026000010000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000100000434a5b30cafe7e853832a458ea1591dc2f5fb5e4cf80b9979b8248065a7ea00000000000000000000000000000000000000000000000000000000675e0c6900000000000000000000000000000000000000000000000000000000675e0c690000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000675f5de900000000000000000000000000000000000000000000000008d460e8b7e500000000000000000000000000000000000000000000000000000000000000000001000000000000000000000000000000000000000000000000000000000000000255d50eabaa1620b13c01d671b4b8478cbbf3c00a66c96652de0a4abd033447d4077c56723b911f683224b08615cb37103422a0c72f10930f2b2cf5d69ffa7a4100000000000000000000000000000000000000000000000000000000000000022139022d94d5ba9a5d7257866ab5ac2a892de57532a6d15f4d3bb4e0616fc89f26fcf652f60f3227466f986db7a494fdb2e71e7921eaedbfa7e6248220770373","feedID":"0x000434a5b30cafe7e853832a458ea1591dc2f5fb5e4cf80b9979b8248065a7ea","validFromTimestamp":1734216809,"observationsTimestamp":1734216809}


Decoded Report for Stream ID 0x000434a5b30cafe7e853832a458ea1591dc2f5fb5e4cf80b9979b8248065a7ea:
------------------------------------------
Observations Timestamp: 1734216809
Benchmark Price       : 636240000000000000
Valid From Timestamp  : 1734216809
Expires At            : 1734303209
Link Fee              : 0
Native Fee            : 0
Market Status         : 1
------------------------------------------
2024-12-14T17:53:30-05:00 Raw report data for Stream ID 0x0004b9905d8337c34e00f8dbe31619428bac5c3937e73e6af75c71780f1770ce: {"fullReport":"0x00062f2fdc48a5bb737dad7fac44e3d35f5d0a0c43091fea90011dbcd3ca39ff000000000000000000000000000000000000000000000000000000000d25a501000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000e000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000000260000100000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001000004b9905d8337c34e00f8dbe31619428bac5c3937e73e6af75c71780f1770ce00000000000000000000000000000000000000000000000000000000675e0c6900000000000000000000000000000000000000000000000000000000675e0c690000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000675f5de90000000000000000000000000000000000000000000000000e933ccf7f5aa00000000000000000000000000000000000000000000000000000000000000000010000000000000000000000000000000000000000000000000000000000000002266357ecc8bccb8199db1d62be6b26ff251e51d821abac59095ffa3bd53f2b671ba72e1f0157b7269578f24574d75f21f4e16340e924a39966385a9204c7f5c5000000000000000000000000000000000000000000000000000000000000000258e69e20a244ec3dc6bcb309d08479656b37160e2210dd7278b6be12296456184d3871968c7511af5beec82528e6f8a9caedffd12f93ca65425850a400343299","feedID":"0x0004b9905d8337c34e00f8dbe31619428bac5c3937e73e6af75c71780f1770ce","validFromTimestamp":1734216809,"observationsTimestamp":1734216809}


Decoded Report for Stream ID 0x0004b9905d8337c34e00f8dbe31619428bac5c3937e73e6af75c71780f1770ce:
------------------------------------------
Observations Timestamp: 1734216809
Benchmark Price       : 1050250000000000000
Valid From Timestamp  : 1734216809
Expires At            : 1734303209
Link Fee              : 0
Native Fee            : 0
Market Status         : 1
------------------------------------------

    Your application has successfully fetched and decoded data for both streams.

Payload for onchain verification

In this guide, you log and decode the fullReport payloads to extract the report data. In a production environment, you should verify the data to ensure its integrity and authenticity. Refer to the Verify report data onchain guide.

Explanation

Initializing the client and configuration

The Data Streams client is initialized in two steps:

  1. Configure the client with streams.Config:

    cfg := streams.Config{
    ApiKey:    os.Getenv("API_KEY"),
    ApiSecret: os.Getenv("API_SECRET"),
    RestURL:   "https://api.testnet-dataengine.chain.link",
    Logger:    streams.LogPrintf,
}

    The configuration requires:

    • ApiKey and ApiSecret for authentication (required)
    • RestURL for the API endpoint (required)
    • Logger for debugging and error tracking (optional, defaults to streams.LogPrintf)

  2. Create the client with streams.New:

    client, err := streams.New(cfg)

    The client handles:

    • Authentication with HMAC signatures
    • Connection management and timeouts
    • Error handling and retries

Fetching reports

The SDK provides two main methods to fetch reports:

  1. Latest report for a single stream with GetLatestReport:

    reportResponse, err := client.GetLatestReport(ctx, feedID)
    • Takes a context and feed ID
    • Returns a single ReportResponse with the most recent data
    • No timestamp parameter needed
    • Useful for real-time price monitoring

  2. Latest reports for multiple streams with GetReports:

    reportResponses, err := client.GetReports(ctx, ids, timestamp)
    • Takes context, feed IDs array, and Unix timestamp
    • Returns array of ReportResponse, one per feed ID
    • Timestamp determines the point in time for the reports
    • Efficient for monitoring multiple assets simultaneously

Each API request automatically:

  • Handles authentication with API credentials
  • Manages request timeouts via context
  • Processes responses into structured types

Decoding reports

Reports are decoded in two steps:

  1. Report decoding with report.Decode:

    decodedReport, err := report.Decode[v4.Data](reportResponse.FullReport)

    This step:

    • Takes the raw FullReport bytes from the response
    • Uses v4.Data schema for RWA streams (use v3.Data for Crypto streams)
    • Validates the format and decodes using Go generics
    • Returns a structured report with typed data

  2. Data access:

    data := decodedReport.Data
price := data.BenchmarkPrice.String()  // Convert big number to string
validFrom := data.ValidFromTimestamp  // Unix timestamp
expiresAt := data.ExpiresAt          // Unix timestamp
marketStatus := data.MarketStatus    // Market status (0: Unknown, 1: Closed, 2: Open)

    Provides access to:

    • Benchmark price (as big number)
    • Fee information (LINK and native token fees)
    • Timestamp data (validity period)
    • Market status information
    • All numeric values require .String() for display

Error handling

The SDK uses Go's standard error handling patterns with some enhancements:

  1. Context management:

    ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
    • Sets request timeouts for API calls
    • defer cancel() ensures cleanup of resources
    • Same context pattern for both single and multiple reports

  2. Error checking:

    if err != nil {
    cfg.Logger("Failed to decode report: %v\n", err)
    os.Exit(1)           // Fatal errors: exit the program
    // or
    continue            // Non-fatal errors: skip this report
}
    • Fatal errors (client creation, no valid feeds) use os.Exit(1)
    • Non-fatal errors (single report decode) use continue
    • All errors are logged before handling

  3. SDK logging:

    cfg.Logger("Raw report data: %+v\n", reportResponse)
    • Uses configured logger for SDK operations
    • fmt.Printf for user-facing output
    • Debug information includes raw report data
    • Structured error messages with context

The decoded data can be used for further processing or display in your application. For production environments, you must verify the data onchain using the provided fullReport payload.

What's next

Get the latest Chainlink content straight to your inbox.