### Install UTxO RPC Go SDK

Source: https://github.com/utxorpc/go-sdk/blob/main/README.md

Install the SDK using the go get command. Requires Go 1.24.0 or later.

```bash
go get github.com/utxorpc/go-sdk
```

--------------------------------

### Quick Start: Cardano SDK Client

Source: https://github.com/utxorpc/go-sdk/blob/main/README.md

Shows how to use the Cardano-specific client for high-level helpers. This includes getting protocol parameters and UTxOs by transaction reference. Remember to set your API key.

```go
package main

import (
    "fmt"

    "github.com/utxorpc/go-sdk"
    "github.com/utxorpc/go-sdk/cardano"
)

func main() {
    // Create a Cardano-specific client
    client := cardano.NewClient(sdk.WithBaseUrl("https://preview.utxorpc-v0.demeter.run"))
    client.UtxorpcClient.SetHeader("dmtr-api-key", "your-api-key")

    // Get protocol parameters
    resp, err := client.GetProtocolParameters()
    if err != nil {
        panic(err)
    }

    fmt.Printf("Slot: %d\n", resp.Msg.GetLedgerTip().GetSlot())

    // Get a UTxO by transaction reference
    utxo, err := client.GetUtxoByRef(
        "24efe5f12d1d93bb419cfb84338d6602dfe78c614b489edb72df0594a077431c",
        0,
    )
    if err != nil {
        panic(err)
    }

    for _, item := range utxo.Msg.GetItems() {
        fmt.Printf("Coin: %d\n", item.GetCardano().GetCoin())
    }
}
```

--------------------------------

### Run Sync Example

Source: https://github.com/utxorpc/go-sdk/blob/main/README.md

Execute the sync example to demonstrate fetching blocks by hash and slot, following the chain tip with streaming, and handling Apply/Undo/Reset actions. No specific environment variables are mentioned for this example.

```bash
go run examples/sync/main.go
```

--------------------------------

### Run Query Example

Source: https://github.com/utxorpc/go-sdk/blob/main/README.md

Execute the query example to demonstrate fetching protocol parameters, UTxOs by reference, searching UTxOs by address, and filtering UTxOs by native assets. Requires setting UTXORPC_URL and DMTR_API_KEY environment variables.

```bash
export UTXORPC_URL="https://preview.utxorpc-v0.demeter.run"
export DMTR_API_KEY="your-api-key"
go run examples/query/main.go
```

--------------------------------

### Quick Start: Generic SDK Client

Source: https://github.com/utxorpc/go-sdk/blob/main/README.md

Demonstrates how to create a generic, blockchain-agnostic client and query protocol parameters. Ensure you have the necessary imports and provide your API key.

```go
package main

import (
    "context"
    "fmt"

    "connectrpc.com/connect"
    "github.com/utxorpc/go-codegen/utxorpc/v1beta/query"
    "github.com/utxorpc/go-sdk"
)

func main() {
    // Create a client with options
    client := sdk.NewClient(
        sdk.WithBaseUrl("https://preview.utxorpc-v0.demeter.run"),
        sdk.WithHeaders(map[string]string{
            "dmtr-api-key": "your-api-key",
        }),
    )

    // Query protocol parameters
    req := connect.NewRequest(&query.ReadParamsRequest{})
    client.AddHeadersToRequest(req)

    resp, err := client.Query.ReadParams(context.Background(), req)
    if err != nil {
        panic(err)
    }

    fmt.Printf("Ledger Tip Slot: %d\n", resp.Msg.GetLedgerTip().GetSlot())
}
```

--------------------------------

### Run Submit Example

Source: https://github.com/utxorpc/go-sdk/blob/main/README.md

Execute the submit example to demonstrate submitting transactions, reading mempool state, waiting for transaction confirmation, and watching mempool for changes. No specific environment variables are mentioned for this example.

```bash
go run examples/submit/main.go
```

--------------------------------

### Development Commands

Source: https://github.com/utxorpc/go-sdk/blob/main/README.md

Common development commands for the Go SDK. Includes running tests, formatting code, building examples, and tidying dependencies using make targets.

```bash
# Run tests
make test

# Format code
make format

# Build examples
make build

# Tidy dependencies
make mod-tidy
```

--------------------------------

### Cardano Sync Methods

Source: https://github.com/utxorpc/go-sdk/blob/main/README.md

Cardano-specific synchronization methods. Fetch blocks by reference, get the current tip, read and validate blocks, and stream to follow blocks or watch transactions from a specific point.

```go
// Get current tip
client.GetTip()

// Fetch block by reference
client.GetBlockByRef(hash, slot)

// Read and validate a block
client.ReadBlock(blockRef)

// Stream: Follow blocks from a point
stream, _ := client.WatchBlocksByRef(hash, slot)

// Stream: Watch transactions
stream, _ := client.WatchTransaction(hash, slot)
```

--------------------------------

### Cardano Package Sync Methods

Source: https://github.com/utxorpc/go-sdk/blob/main/README.md

Convenience methods for Cardano synchronization, including fetching blocks, getting chain tips, and streaming block updates.

```APIDOC
## Cardano Package API - Sync Methods

### Description
Convenience methods for Cardano synchronization.

### Methods
- `GetTip() (*GetTipResponse, error)`: Gets the current chain tip.
- `GetBlockByRef(hash string, slot uint64) (*GetBlockByRefResponse, error)`: Fetches a block by its hash and slot.
- `ReadBlock(blockRef *BlockRef) (*ReadBlockResponse, error)`: Reads and validates a block.
- `WatchBlocksByRef(hash string, slot uint64) (Sync_FollowTipClient, error)`: Stream: Follows blocks starting from a specific reference (hash and slot).
- `WatchTransaction(hash string, slot uint64) (Watch_WatchTxClient, error)`: Stream: Watches for transactions from a specific block reference.
```

--------------------------------

### Client Configuration Options

Source: https://github.com/utxorpc/go-sdk/blob/main/README.md

Demonstrates configuring the SDK client using a functional options pattern. This includes setting the base URL, custom headers, and timeouts for connections and requests.

```go
client := sdk.NewClient(
    sdk.WithBaseUrl("https://your-utxorpc-server.com"),
    sdk.WithHeaders(map[string]string{
        "Authorization": "Bearer token",
    }),
    sdk.WithDialTimeout(10 * time.Second),
    sdk.WithRequestTimeout(30 * time.Second),
)
```

--------------------------------

### Using v1alpha (Legacy) SDK

Source: https://github.com/utxorpc/go-sdk/blob/main/README.md

Illustrates how to import and use the legacy v1alpha version of the SDK for compatibility with older servers. Note that the cardano helper subpackage is only available for v1beta.

```go
import (
    sdk "github.com/utxorpc/go-sdk/v1alpha"
    "github.com/utxorpc/go-codegen/utxorpc/v1alpha/query"
)
```

--------------------------------

### Working with Streams

Source: https://github.com/utxorpc/go-sdk/blob/main/README.md

Demonstrates how to use streaming methods to receive real-time updates, such as following the chain tip and processing incoming blocks, rollbacks, or resets.

```APIDOC
## Working with Streams

### Description
Provides guidance on utilizing streaming methods for real-time data synchronization, including handling different types of stream messages like block applications, rollbacks, and chain resets.

### Example Usage
```go
stream, err := client.WatchBlocksByRef(blockHash, slot)
if err != nil {
    log.Fatal(err)
}
defer stream.Close()

for stream.Receive() {
    resp := stream.Msg()
    action := resp.GetAction()

    switch a := action.(type) {
    case *sync.FollowTipResponse_Apply:
        fmt.Println("New block applied")
        // Handle new block
    case *sync.FollowTipResponse_Undo:
        fmt.Println("Block rolled back")
        // Handle rollback
    case *sync.FollowTipResponse_Reset_:
        fmt.Println("Chain reset")
        // Handle reset
    }
}

if err := stream.Err(); err != nil {
    log.Fatal("Stream error:", err)
}
```
```

--------------------------------

### Sync Service Methods

Source: https://github.com/utxorpc/go-sdk/blob/main/README.md

Engage with the Sync service for blockchain synchronization. Fetch specific blocks, read the current chain tip, and stream to follow the chain tip for real-time updates.

```go
// Fetch a specific block
client.Sync.FetchBlock(ctx, req)

// Read current chain tip
client.Sync.ReadTip(ctx, req)

// Stream: Follow the chain tip
stream, _ := client.Sync.FollowTip(ctx, req)
```

--------------------------------

### Watch Service Methods

Source: https://github.com/utxorpc/go-sdk/blob/main/README.md

Use the Watch service to monitor for specific transactions. This service provides streaming capabilities to watch for transaction events.

```go
// Stream: Watch for specific transactions
stream, _ := client.Watch.WatchTx(ctx, req)
```

--------------------------------

### Query Service Methods

Source: https://github.com/utxorpc/go-sdk/blob/main/README.md

Interact with the Query service to read blockchain data. Supports reading UTxOs by reference, searching UTxOs with patterns, reading protocol parameters, and reading chain data.

```go
// Read UTxOs by reference
client.Query.ReadUtxos(ctx, req)

// Search UTxOs with patterns
client.Query.SearchUtxos(ctx, req)

// Read protocol parameters
client.Query.ReadParams(ctx, req)

// Read chain data
client.Query.ReadData(ctx, req)
```

--------------------------------

### Cardano Query Methods

Source: https://github.com/utxorpc/go-sdk/blob/main/README.md

Convenience methods for Cardano-specific queries. Retrieve protocol parameters, UTxOs by various criteria (reference, address, asset), and filter UTxOs by asset details.

```go
// Protocol parameters
client.GetProtocolParameters()

// UTxO queries
client.GetUtxoByRef(txHash, index)
client.GetUtxosByRefs(refs)
client.GetUtxosByAddress(address)
client.GetUtxosByAddressWithAsset(address, policyId, assetName)
client.GetUtxosByAsset(policyId, assetName)
```

--------------------------------

### Submit Service Methods

Source: https://github.com/utxorpc/go-sdk/blob/main/README.md

Utilize the Submit service for transaction management. Includes submitting transactions, evaluating them in a dry run, reading the mempool, and streaming for transaction confirmations or mempool changes.

```go
// Submit a transaction
client.Submit.SubmitTx(ctx, req)

// Evaluate a transaction (dry run)
client.Submit.EvalTx(ctx, req)

// Read current mempool
client.Submit.ReadMempool(ctx, req)

// Stream: Wait for transaction confirmation
stream, _ := client.Submit.WaitForTx(ctx, req)

// Stream: Watch mempool changes
stream, _ := client.Submit.WatchMempool(ctx, req)
```

--------------------------------

### Cardano Package Query Methods

Source: https://github.com/utxorpc/go-sdk/blob/main/README.md

Convenience methods for Cardano-specific queries, including protocol parameters and various UTxO retrieval options.

```APIDOC
## Cardano Package API - Query Methods

### Description
Convenience methods for Cardano-specific queries.

### Methods
- `GetProtocolParameters() (*GetProtocolParametersResponse, error)`: Retrieves protocol parameters.
- `GetUtxoByRef(txHash string, index uint32) (*GetUtxoByRefResponse, error)`: Retrieves a UTxO by its transaction hash and index.
- `GetUtxosByRefs(refs []*UtxoRef) (*GetUtxosByRefsResponse, error)`: Retrieves multiple UTxOs by their references.
- `GetUtxosByAddress(address string) (*GetUtxosByAddressResponse, error)`: Retrieves UTxOs associated with a given address.
- `GetUtxosByAddressWithAsset(address string, policyId string, assetName string) (*GetUtxosByAddressWithAssetResponse, error)`: Retrieves UTxOs for a specific address and native asset.
- `GetUtxosByAsset(policyId string, assetName string) (*GetUtxosByAssetResponse, error)`: Retrieves UTxOs associated with a specific native asset.
```

--------------------------------

### Sync Service Methods

Source: https://github.com/utxorpc/go-sdk/blob/main/README.md

Methods for synchronizing with the blockchain, including fetching blocks, reading chain tips, and streaming chain tip updates.

```APIDOC
## Sync Service

### Description
Synchronize with the blockchain.

### Methods
- `FetchBlock(ctx context.Context, req *FetchBlockRequest) (*FetchBlockResponse, error)`: Fetch a specific block.
- `ReadTip(ctx context.Context, req *ReadTipRequest) (*ReadTipResponse, error)`: Read current chain tip.
- `FollowTip(ctx context.Context, req *FollowTipRequest) (Sync_FollowTipClient, error)`: Stream: Follow the chain tip.
```

--------------------------------

### Submit Service Methods

Source: https://github.com/utxorpc/go-sdk/blob/main/README.md

Methods for submitting and managing transactions, including submitting, evaluating, and reading mempool state, as well as streaming for transaction confirmations and mempool changes.

```APIDOC
## Submit Service

### Description
Submit and manage transactions.

### Methods
- `SubmitTx(ctx context.Context, req *SubmitTxRequest) (*SubmitTxResponse, error)`: Submit a transaction.
- `EvalTx(ctx context.Context, req *EvalTxRequest) (*EvalTxResponse, error)`: Evaluate a transaction (dry run).
- `ReadMempool(ctx context.Context, req *ReadMempoolRequest) (*ReadMempoolResponse, error)`: Read current mempool.
- `WaitForTx(ctx context.Context, req *WaitForTxRequest) (Submit_WaitForTxClient, error)`: Stream: Wait for transaction confirmation.
- `WatchMempool(ctx context.Context, req *WatchMempoolRequest) (Submit_WatchMempoolClient, error)`: Stream: Watch mempool changes.
```

--------------------------------

### Manage Request Headers

Source: https://github.com/utxorpc/go-sdk/blob/main/README.md

Set, remove, and retrieve headers for API requests. Use SetHeader for single headers and SetHeaders for multiple. Headers can be accessed using the Headers() method.

```go
// Set a single header
client.SetHeader("dmtr-api-key", "your-key")

// Set multiple headers
client.SetHeaders(map[string]string{
    "dmtr-api-key": "your-key",
    "X-Custom":     "value",
})

// Remove a header
client.RemoveHeader("X-Custom")

// Get current headers
headers := client.Headers()
```

--------------------------------

### Handle Connect RPC Errors

Source: https://github.com/utxorpc/go-sdk/blob/main/README.md

Implement error handling for Connect RPC errors when submitting transactions. Use errors.As to check for connect.Error and extract details like error code, message, and specific details.

```go
resp, err := client.SubmitTransaction(txCbor)
if err != nil {
    var connectErr *connect.Error
    if errors.As(err, &connectErr) {
        fmt.Printf("Error Code: %v\n", connectErr.Code())
        fmt.Printf("Message: %s\n", connectErr.Message())
        fmt.Printf("Details: %v\n", connectErr.Details())
    }
}
```

--------------------------------

### Cardano Transaction Methods

Source: https://github.com/utxorpc/go-sdk/blob/main/README.md

Methods for submitting and managing Cardano transactions. Includes submitting signed transactions, evaluating them, reading mempool, and streaming for confirmations or mempool changes.

```go
// Submit a signed transaction (hex-encoded CBOR)
client.SubmitTransaction(txCbor)

// Evaluate a transaction
client.EvaluateTransaction(txCbor)

// Read mempool
client.GetMempoolTransactions()

// Stream: Wait for confirmation
stream, _ := client.WaitForTransaction(txRef)

// Stream: Watch mempool
stream, _ := client.WatchMempoolTransactions()
```

--------------------------------

### Error Handling

Source: https://github.com/utxorpc/go-sdk/blob/main/README.md

Utilities for handling Connect RPC errors, showing how to check for specific error types and extract error details.

```APIDOC
## Error Handling

### Description
Provides utilities for handling Connect RPC errors, demonstrating how to identify and extract detailed information from error responses.

### Example Usage
```go
resp, err := client.SubmitTransaction(txCbor)
if err != nil {
    var connectErr *connect.Error
    if errors.As(err, &connectErr) {
        fmt.Printf("Error Code: %v\n", connectErr.Code())
        fmt.Printf("Message: %s\n", connectErr.Message())
        fmt.Printf("Details: %v\n", connectErr.Details())
    }
}
```
```

--------------------------------

### Watch Service Methods

Source: https://github.com/utxorpc/go-sdk/blob/main/README.md

Methods for watching transactions on the blockchain.

```APIDOC
## Watch Service

### Description
Watch for transactions.

### Methods
- `WatchTx(ctx context.Context, req *WatchTxRequest) (Watch_WatchTxClient, error)`: Stream: Watch for specific transactions.
```

--------------------------------

### Query Service Methods

Source: https://github.com/utxorpc/go-sdk/blob/main/README.md

Methods for reading blockchain data without modifying state, such as reading UTxOs, protocol parameters, and chain data.

```APIDOC
## Query Service

### Description
Read blockchain data without modifying state.

### Methods
- `ReadUtxos(ctx context.Context, req *ReadUtxosRequest) (*ReadUtxosResponse, error)`: Read UTxOs by reference.
- `SearchUtxos(ctx context.Context, req *SearchUtxosRequest) (*SearchUtxosResponse, error)`: Search UTxOs with patterns.
- `ReadParams(ctx context.Context, req *ReadParamsRequest) (*ReadParamsResponse, error)`: Read protocol parameters.
- `ReadData(ctx context.Context, req *ReadDataRequest) (*ReadDataResponse, error)`: Read chain data.
```

--------------------------------

### Process Streaming Blocks

Source: https://github.com/utxorpc/go-sdk/blob/main/README.md

Handle real-time blockchain updates using streaming methods like WatchBlocksByRef. Process incoming blocks, including new block applications, rollbacks, and chain resets. Ensure proper stream closure and error handling.

```go
// Start following the chain tip
stream, err := client.WatchBlocksByRef(blockHash, slot)
if err != nil {
    log.Fatal(err)
}
defer stream.Close()

// Process incoming blocks
for stream.Receive() {
    resp := stream.Msg()
    action := resp.GetAction()

    switch a := action.(type) {
    case *sync.FollowTipResponse_Apply:
        fmt.Println("New block applied")
        // Handle new block
    case *sync.FollowTipResponse_Undo:
        fmt.Println("Block rolled back")
        // Handle rollback
    case *sync.FollowTipResponse_Reset_:
        fmt.Println("Chain reset")
        // Handle reset
    }
}

if err := stream.Err(); err != nil {
    log.Fatal("Stream error:", err)
}
```

--------------------------------

### Dynamic Header Management

Source: https://github.com/utxorpc/go-sdk/blob/main/README.md

Methods for managing request headers, including setting single or multiple headers, removing headers, and retrieving current headers.

```APIDOC
## Dynamic Header Management

### Description
Methods for managing request headers, including setting single or multiple headers, removing headers, and retrieving current headers.

### Methods
- `SetHeader(key string, value string)`: Sets a single header.
- `SetHeaders(headers map[string]string)`: Sets multiple headers.
- `RemoveHeader(key string)`: Removes a header.
- `Headers() map[string]string`: Retrieves the current headers.
```

--------------------------------

### Cardano Package Transaction Methods

Source: https://github.com/utxorpc/go-sdk/blob/main/README.md

Convenience methods for Cardano transaction management, including submission, evaluation, mempool access, and transaction watching.

```APIDOC
## Cardano Package API - Transaction Methods

### Description
Convenience methods for Cardano transaction management.

### Methods
- `SubmitTransaction(txCbor string) (*SubmitTransactionResponse, error)`: Submits a signed transaction (hex-encoded CBOR).
- `EvaluateTransaction(txCbor string) (*EvaluateTransactionResponse, error)`: Evaluates a transaction (dry run).
- `GetMempoolTransactions() (*GetMempoolTransactionsResponse, error)`: Reads the current mempool state.
- `WaitForTransaction(txRef *TransactionRef) (Submit_WaitForTxClient, error)`: Stream: Waits for a transaction to be confirmed.
- `WatchMempoolTransactions() (Submit_WatchMempoolClient, error)`: Stream: Watches for changes in the mempool.
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.