> For the complete documentation index, see [llms.txt](https://docs.picketapi.com/picket-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.picketapi.com/picket-docs/reference/libraries-and-sdks/go-library-picket-go.md).

# Go Library - picket-go

## picket-go

The official Picket API Go library. View it on [Github](https://github.com/picketapi/picket-go).

### Installation

```bash
go get -u github.com/picketapi/picket-go
```

### Usage - Quick Start

Use the `picketapi.NewClient` to create the Picket API client. It takes a *secret API key* as a parameter.

```go
import (
	picketapi "github.com/picketapi/picket-go"
)

picket := picketapi.NewClient("YOUR_SECRET_API_KEY")
```

### Nonce

A `nonce` is random value generated by the Picket API to that user must sign to prove ownership a wallet address. The `nonce` function can be used to implement your own wallet authentication flow.

A nonce is unique to a project and wallet address. If a `nonce` doesn't exist for the project and wallet address, Picket will generate a new nonce; otherwise, Picket will return the existing nonce. A nonce is valid for two minutes before self-destructing.

```go
resp, err := picket.Nonce(picketapi.NonceArgs{
		Chain:         "solana",
		WalletAddress: "wAllEtadDresS",
})
fmt.Printf("received nonce: %s", resp.Nonce)
```

### Auth

`auth` is the server-side equivalent of login. `auth` should only be used in a trusted server environment. The most common use-case for `auth` is [linking a wallet to an existing application account](https://docs.picketapi.com/picket-docs/tutorials/link-a-wallet-to-a-web-2.0-account).

```go
resp, err := picket.Auth(picketapi.AuthArgs{
		Chain:         "ethereum",
		WalletAddress: "0x1234567890",
		Signature:     "abcdefghijklmnop",
})
fmt.Printf("received access token: %s", resp.AccessToken)
```

### Authz (Authorize)

{% hint style="info" %}
**Incremental Authorization (Authz)**

To understand the use-cases for using `authz` over `auth`, read about [Incremental Authorization](/picket-docs/reference/concepts/incremental-authorization.md)
{% endhint %}

`authz` stands for authorization. Unlike Auth, which handles both authentication and authorization, Authz only handles authorization. Given an authenticated user's access token and authorization requirements, `authz` will issue a new access token on success (user is authorized) or, on failure, it will return a 4xx HTTP error code.

```go
resp, err := picket.Authz(picketapi.AuthzArgs{
		AccessToken: "aaa.bbb.ccc",
		Requirements: picketapi.AuthorizationRequirements{
			ContractAddress: "0xContract",
			MinTokenBalance: "100",
		},
})
fmt.Printf("received updated access token: %s", resp.AccessToken)
```

### Validate

`validate` validates an access token. `validate` should be called, or manually access token validation should be done, server-side before trusting a request's access token. It's common to move access token validation and decoding logic to a shared middleware across API endpoints. If the access token is valid, validate returns the decoded claims of the access token.

```go
resp, err := picket.Validate(picketapi.ValidateArgs{
		AccessToken: "aaa.bbb.ccc",
		// Authorizatopn args are optional
		Requirements: picketapi.AuthorizationRequirements{
			ContractAddress: "0xContract",
			MinTokenBalance: "100",
		},
})
fmt.Printf("decoded access token: %v", resp)
```

### Verify Token Ownership

If you only want to verify token ownership server side for a given wallet, `tokenOwnership` allows you to do just that.

```go
resp, err := picket.TokenOwnership(picketapi.TokenOwnershipArgs{
		Chain:         "solana",
		WalletAddress: "waLLeTaddrESs",
		Requirements: picketapi.AuthorizationRequirements{
			Collection: "METAPLEX_COLLECTION",
			MinTokenBalance: "3",
		},
})
fmt.Printf("wallet has sufficient tokens: %s", resp.Allowed)
```


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.picketapi.com/picket-docs/reference/libraries-and-sdks/go-library-picket-go.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.