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

# Go SDK

> Idiomatic Go client for Macropay — checkout, billing, usage events, and agent signals on the v1 API.

A type-safe Go client for the Macropay v1 API. It follows Go conventions you
already know: every call takes a `context.Context`, responses are strongly
typed, and list endpoints return iterators that page for you.

One client covers the whole platform — one-time and subscription products,
usage-based metering, and agent billing. Because Macropay is the **merchant of
record**, the same integration also makes us the seller of record on your
customers' statements: we calculate and remit sales tax and VAT worldwide, so
that liability never lands on you.

## Install

```bash Terminal theme={null}
go get github.com/macropay/macropay-go
```

## Quickstart

Authenticate with an access token, then iterate your organizations. Set
`MACROPAY_ACCESS_TOKEN` in your environment first — the client reads your token
from there and talks to `https://api.macropay.ai` by default.

```go icon="golang" main.go theme={null}
package main

import (
	"context"
	"log"
	"os"

	macropaygo "github.com/macropay/macropay-go"
)

func main() {
	ctx := context.Background()

	client := macropaygo.New(
		macropaygo.WithSecurity(os.Getenv("MACROPAY_ACCESS_TOKEN")),
	)

	// page 1, 10 items per page
	res, err := client.Organizations.List(
		ctx,
		nil,
		macropaygo.Pointer[int64](1),
		macropaygo.Pointer[int64](10),
		nil,
	)
	if err != nil {
		log.Fatalf("listing organizations: %v", err)
	}

	// Walk every page — Next() returns nil when there's nothing left.
	for res != nil {
		if res.ListResourceOrganization != nil {
			for _, org := range res.ListResourceOrganization.Items {
				log.Printf("organization: %s", org.Name)
			}
		}

		res, err = res.Next()
		if err != nil {
			log.Fatalf("paging organizations: %v", err)
		}
	}
}
```

<Note>
  **snake\_case in docs, Go fields in code**

  The API and these docs use `snake_case` (e.g. `created_at`). The Go SDK exposes
  the same fields as exported Go struct members, so your IDE will surface them via
  the generated types — keep that mapping in mind when moving between the
  reference and your editor.
</Note>

## Sandbox environment

Point the client at the [sandbox environment](/integrate/sandbox) to build and
test against a fully isolated copy of the API — no real money, no real tax
events. Select the server when you construct the client:

```go icon="golang" theme={null}
client := macropaygo.New(
	macropaygo.WithServer("sandbox"),
	macropaygo.WithSecurity(os.Getenv("MACROPAY_ACCESS_TOKEN")),
)
```

When you're ready to go live, switch to the production server (the default) and
swap in a production access token.

## Beyond the basics

The same client reaches the rest of the platform:

* **Usage-based billing** — ingest metered events and bill by usage, then let
  Macropay aggregate them against your meters and prices.
* **Agent billing** — send activity and outcome signals through the Signals API
  to bill autonomous agents by what they *do* and what they *deliver*, and to
  certify ROI with value receipts.

Both run through the same authenticated client, so there's nothing extra to wire
up once the quickstart works.

## Examples

* [Go with Gin](https://docs.macropay.ai/tree/main/with-golang-gin) — a minimal
  HTTP service wiring checkout and webhooks into a Gin router.