> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truf.network/llms.txt
> Use this file to discover all available pages before exploring further.

# SDKs

> Learn how to interact with the TRUF.NETWORK using SDKs.

The TRUF.NETWORK offers SDKs in Go, TypeScript/JavaScript, and Python to facilitate seamless integration with its decentralized platform for economic data streams.

## Using the SDKs

To interact with a data stream you found in the explorer, your first step is to choose the SDK for your preferred language. Each repository contains the full installation instructions, API reference, and examples you'll need.

* [Go SDK](https://github.com/trufnetwork/sdk-go)
* [TypeScript/JavaScript SDK](https://github.com/trufnetwork/sdk-js)
* [Python SDK](https://github.com/trufnetwork/sdk-py)

### What is a `streamID`?

A `streamID` is the unique identifier for a data stream on the TRUF.NETWORK. You can find the `streamID` for any stream on its page in the TRUF.NETWORK Explorer. You will use this ID in the SDK functions to retrieve data.

### How to Fetch Data from a Stream

Once you have a **Stream ID** and **Data Provider** from the [TRUF.NETWORK Explorer](https://truf.network/explorer), you can use the SDKs to query its data. The SDKs provide several core methods for querying, depending on what you need to do.

#### Core Query Methods

The explorer may show a specific `SDK Method` for a stream (like `get_index_change`). These methods correspond to the core functions available in all our SDKs. Here are the most common ones:

* **`getRecord` / `get_records`**: Retrieves the raw, original numeric values from a stream. Use this when you need the exact, unaltered data. This is the most fundamental query.

* **`getIndex`**: Transforms the raw values into a normalized index (based to 100). This is useful for comparing the performance of different streams on the same scale.

* **`getIndexChange`**: Calculates the percentage change of a stream's index over a specified time interval (e.g., day-over-day, year-over-year).

* **Custom Procedures**: For advanced use cases, the SDKs provide a way to call any custom stored procedure defined on a stream's contract.

For the exact function names and parameters, always refer to the detailed API reference in each SDK's repository.

#### Conceptual Example: Fetching Raw Data (`getRecord`)

Here is a conceptual example of how to use the `getRecord` method to fetch the raw data points from a stream.

#### TypeScript/JavaScript

```ts theme={null}
// 1. Initialize the client
// Assumes you have a wallet and are in a Node.js environment
const client = new NodeTNClient({
	endpoint: "https://gateway.mainnet.truf.network",
	signerInfo: { address: wallet.address, signer: wallet },
});

// 2. Define stream details from the explorer
const streamLocator = {
	streamId: StreamId.fromString("stai00...").throw(),
	dataProvider: EthereumAddress.fromString("0x3210...").throw(),
};

// 3. Load the action client and get records
const streamAction = client.loadAction();
const records = await streamAction.getRecord({
	stream: streamLocator,
});

console.log("Records:", records);
```

#### Go

```go theme={null}
// 1. Initialize the client
// Assumes you have a signer configured
tnClient, err := tnclient.NewClient(
	ctx,
	"https://gateway.mainnet.truf.network",
	tnclient.WithSigner(signer),
)

// 2. Define stream details from the explorer
streamId := "stai00..."     // The stream's ID
dataProvider := "0x3210..." // The data provider address

// 3. Load the actions client and get records
// The method might differ for primitive/composed streams
actions, err := tnClient.LoadComposedActions()
records, err := actions.GetRecord(ctx, types.GetRecordInput{
	DataProvider: dataProvider,
	StreamId:     streamId,
})

fmt.Println("Records:", records)
```

#### Python

```python theme={null}
# 1. Initialize the client
client = TNClient(
    "https://gateway.mainnet.truf.network",
    "YOUR_PRIVATE_KEY"
)

# 2. Define stream details from the explorer
stream_id = "stai00..."
data_provider = "0x3210..."

# 3. Get records directly from the client
records = client.get_records(
    stream_id=stream_id,
    data_provider=data_provider
)

print(f"Records: {records}")
```

## SDK Capabilities

Each SDK provides comprehensive tools to interact with the TRUF.NETWORK, enabling operations such as:

* Deploying primitive and composed streams
* Inserting and retrieving records
* Managing stream metadata
* Handling stream permissions
* Performing batch operations

## Stream Deployment Permissions

To ensure the integrity and quality of data streams on the TRUF.NETWORK, the creation of new streams (both primitive and composed) is a permissioned operation. This process is governed by a **`system:network_writer`** role within the network's role-based access control (RBAC) system.

Only wallets that are members of the `system:network_writer` role are authorized to deploy new streams using the SDKs.

**How to get access:**

If you are a partner or data provider interested in deploying streams on the TRUF.NETWORK, please contact our team. We will guide you through the process of obtaining the necessary permissions by granting your wallet the `system:network_writer` role.

## Using SDKs with Your Local Node

<Note>
  This section is intended for node operators who are running a local
  TRUF.NETWORK node that is fully synced with the network. If your node is not
  connected to the network, queries will return empty results because your local
  database will not contain any data. Always ensure your node is synchronized
  before using it as an SDK endpoint. Follow the [Node Operator
  Guide](https://github.com/trufnetwork/node/blob/main/docs/node-operator-guide.md)
  for instructions on connecting to the network and syncing data.
</Note>

You can use any TRUF.NETWORK SDK (Go, TypeScript/JavaScript, Python) to interact with your own local node, not just the public gateway. This allows you to fetch data directly from your node, which is especially useful for node operators, validators, and developers.

Before you can fetch data from a stream using the SDKs, you need to know the stream's ID and the data provider address. The easiest way to discover these is by using the [TRUF.NETWORK Explorer](https://truf.network/explorer/0x4710a8d8f0d845da110086812a32de6d90d7ff5c/stai0000000000000000000000000000).

### Prerequisites

1. **Node is fully synced:**
   Ensure your node is fully synchronized with the network and has all data available.
   See the [Node Operator Guide](https://github.com/trufnetwork/node/blob/main/docs/node-operator-guide.md#7-verify-node-synchronization) for instructions on checking sync status.

2. **Local Endpoint:**
   Your node should be running and exposing the HTTP API at `http://localhost:8484` (the default).

### Configuration

To use the SDKs with your local node, you need to configure the client to point to your local endpoint (`http://localhost:8484`) instead of the default public gateway. For detailed instructions and code examples, refer to the guide in the README of the respective SDK repository:

* **Go:** [Local Node Guide](https://github.com/trufnetwork/sdk-go?tab=readme-ov-file#local-node-testing)
* **TypeScript/JavaScript:** [Local Node Guide](https://github.com/trufnetwork/sdk-js?tab=readme-ov-file#using-the-sdk-with-your-local-node)
* **Python:** [Local Node Guide](https://github.com/trufnetwork/sdk-py?tab=readme-ov-file#local-node-testing-and-development)

## Additional Resources

* [TRUF.NETWORK Whitepaper](https://raw.githubusercontent.com/trufnetwork/docs/main/pdfs/whitepaper.pdf)
* [Node Operator Guide](./node-operator-guide)

For support or questions, please open an issue in the respective SDK repository or contact our support team.