> For the complete documentation index, see [llms.txt](https://docs.nextblock.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nextblock.io/api/examples/golang/connection.md).

# Connection

Establish a connection to NextBlock's gRPC API from Go.

This page shows the connection pattern and API-key credentials wiring. Replace the generated client import and constructor with the client generated from [`nextblock-proto`](https://github.com/nextblock-ag/nextblock-proto).

## Prerequisites

```bash
go mod init nextblock-example
go get google.golang.org/grpc
go get github.com/gagliardetto/solana-go

# Clone the proto specs and generate the Go client
git clone https://github.com/nextblock-ag/nextblock-proto
# Follow the Go generation instructions in that repository
```

## Example

```go
package main

import (
	"context"
	"crypto/x509"
	"time"

	"google.golang.org/grpc"
	"google.golang.org/grpc/credentials"
	"google.golang.org/grpc/credentials/insecure"
	"google.golang.org/grpc/keepalive"
)

type ApiKeyCredentials struct {
	apiKey     string
	requireTLS bool
}

func NewApiKeyCredentials(apiKey string, requireTLS bool) *ApiKeyCredentials {
	return &ApiKeyCredentials{
		apiKey:     apiKey,
		requireTLS: requireTLS,
	}
}

func (a *ApiKeyCredentials) RequireTransportSecurity() bool {
	return a.requireTLS
}

func (a *ApiKeyCredentials) GetRequestMetadata(context.Context, ...string) (map[string]string, error) {
	return map[string]string{
		"authorization": a.apiKey,
	}, nil
}

var keepAliveParams = keepalive.ClientParameters{
	Time:                time.Minute,
	Timeout:             15 * time.Second,
	PermitWithoutStream: true,
}

func ConnectToNextblock(address string, apiKey string, useTLS bool) (*grpc.ClientConn, error) {
	var opts []grpc.DialOption

	if useTLS {
		pool, err := x509.SystemCertPool()
		if err != nil {
			return nil, err
		}

		creds := credentials.NewClientTLSFromCert(pool, "")
		opts = append(opts, grpc.WithTransportCredentials(creds))
	} else {
		opts = append(opts, grpc.WithTransportCredentials(insecure.NewCredentials()))
	}

	opts = append(opts, grpc.WithKeepaliveParams(keepAliveParams))
	opts = append(opts, grpc.WithPerRPCCredentials(NewApiKeyCredentials(apiKey, useTLS)))

	return grpc.NewClient(address, opts...)
}
```

## Usage Example

```go
func main() {
	const FrankfurtEndpoint = "frankfurt.nextblock.io:443"

	apiKey := "<your-api-key-here>"

	// Prefer TLS by default.
	conn, err := ConnectToNextblock(FrankfurtEndpoint, apiKey, true)
	if err != nil {
		panic(err)
	}
	defer conn.Close()

	// Replace this with your generated client type.
	// nextblockApiClient := api.NewApiClient(conn)

	// You can now use the generated client for API calls.
}
```

## Connection Best Practices

1. **Use TLS by default**: prefer `useTLS: true` unless you intentionally operate in a trusted internal environment
2. **Keep connections alive**: reuse a single gRPC connection for multiple requests
3. **Handle errors gracefully**: implement retry logic around transient network failures
4. **Close connections cleanly**: use `defer conn.Close()` when the process exits
5. **Choose the closest endpoint**: lower network latency usually improves performance

## Available Endpoints

* **Frankfurt**: `frankfurt.nextblock.io:443` (Europe)
* **Amsterdam**: `amsterdam.nextblock.io:443` (Europe)
* **London**: `london.nextblock.io:443` (Europe)
* **Singapore**: `singapore.nextblock.io:443` (Asia)
* **Tokyo**: `tokyo.nextblock.io:443` (Asia)
* **New York**: `ny.nextblock.io:443` (US East)
* **Salt Lake City**: `slc.nextblock.io:443` (US West)
* **Dublin**: `dublin.nextblock.io:443` (Europe)
* **Vilnius**: `vilnius.nextblock.io:443` (Europe)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.nextblock.io/api/examples/golang/connection.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.