Skip to main content
The Go SDK provides typed clients, authentication lifecycle management, and pre-built recipes for the Zeam API. It is the recommended way to integrate from Go.

Install

go get github.com/ZeamMoney/zeam-sdk-go

Create a client

import "github.com/ZeamMoney/zeam-sdk-go"

client, err := zeam.New(
    zeam.WithEnvironment(zeam.EnvironmentProduction),
)
if err != nil {
    log.Fatal(err)
}
The client enforces TLS 1.3, applies request redaction, and propagates X-Request-Id automatically.

Authentication

Ed25519 (backend services)

import "github.com/ZeamMoney/zeam-sdk-go/recipes"

sess, err := recipes.ConnectLogin(ctx, client, recipes.ConnectLoginInput{
    StellarSeed: seed,       // from your secret manager
    PublicKey:   publicKey,
})
// sess is stored in the client's token store and used for subsequent calls

OTP (user sign-in)

sess, err := recipes.LoginOTP(ctx, client, recipes.LoginOTPInput{
    MobileNumber: "+27821234567",
    AskCode: func(ctx context.Context, hint recipes.OTPHint) (string, error) {
        fmt.Printf("OTP sent to %s. Enter code: ", hint.MaskedDestination)
        // Collect code from user
        return code, nil
    },
})

Making API calls

Typed sub-clients are available via the facade:
// List associations
associations, err := client.Business().ListAssociations(ctx, session)

// Get a wallet
wallet, err := client.Business().GetWallet(ctx, session, walletID)

// Query connectors
connectors, err := client.Connect().QueryConnectors(ctx, connectSession, connect.ConnectorQueryInput{
    CountryISO: "ZA",
    Method:     "BANK",
})

Error handling

The SDK returns typed *zeam.Error values with classified kinds:
import "errors"

result, err := client.Business().ListAssociations(ctx, session)
if err != nil {
    if errors.Is(err, zeam.KindAuth) {
        // Token expired — re-authenticate
    }
    if errors.Is(err, zeam.KindTransient) {
        // Retry with backoff
    }
    var sdkErr *zeam.Error
    if errors.As(err, &sdkErr) {
        log.Printf("Error: %s (request_id=%s)", sdkErr.Code, sdkErr.RequestID)
    }
}

Configuration options

OptionDescription
WithEnvironment(env)Target endpoint. Use EnvironmentProduction for all API access. EnvironmentCustom(url) for local development only. Access mode is determined by credentials, not by this setting.
WithTokenStore(store)Token persistence backend (default: in-memory)
WithTimeout(d)Per-call deadline (default: 30s)
WithLogger(logger)Structured logger (receives redacted payloads only)
WithObservability(hook)OpenTelemetry event hook
WithInsecureTransport()Allow plain HTTP (local dev only)
WithPinnedRootCAs(pool)Pin TLS root certificates
WithStellarNetwork(passphrase)Override network passphrase (default: Public Main)
WithSkipVersionCheck()Disable /healthz version handshake

Version compatibility

The SDK performs a runtime handshake against /healthz to verify gateway compatibility. If the gateway is older than zeam.MinGatewayVersion, the SDK returns zeam.ErrIncompatibleGateway immediately.

Repository

Full source, examples, and detailed documentation: github.com/ZeamMoney/zeam-sdk-go See SDK recipes for complete workflow examples.