Go quickstart

Write and read a blob against testnet in under a minute.

1. Install

go get github.com/ajbeach2/stoka-go

2. Fund a testnet wallet

1. Generate a Stellar wallet (anywhere that produces a S… seed — a demo page, Freighter, the stellar-sdk CLI).
2. Open https://faucet.circle.com/ and pick Stellar Testnet.
3. Paste the wallet's G… public address. You'll receive testnet USDC plus the trustline, both of which the client needs.

Set the seed in your environment:

export STELLAR_SECRET=SXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

3. Store and retrieve

package main

import (
	"context"
	"fmt"
	"os"

	"github.com/ajbeach2/stoka-go"
)

func main() {
	c, err := stoka.New(stoka.Options{
		Env:    stoka.Testnet,
		Secret: os.Getenv("STELLAR_SECRET"),
	})
	if err != nil {
		panic(err)
	}
	defer c.Close()

	ctx := context.Background()

	if _, err := c.Store(ctx, "greeting", []byte("hello from go"), nil); err != nil {
		panic(err)
	}

	body, err := c.Retrieve(ctx, "greeting", nil)
	if err != nil {
		panic(err)
	}
	fmt.Println(string(body))
}

The first call triggers a 402 challenge; the client signs it and retries. You'll see ~2–3s of wall time the first time (Soroban RPC simulate). Subsequent calls of the same size are bounded by the same RPC round-trip.

4. Handle insufficient funds

body, err := c.Retrieve(ctx, "greeting", nil)
if pr, ok := err.(*stoka.PaymentRequired); ok {
    // 402 the client couldn't satisfy. pr.Requirements carries the
    // amount / asset / payTo so you can surface it in UI or fund the
    // wallet and retry.
    fmt.Printf("fund %s with %s %s\n", c.PublicKey(), pr.Requirements.MaxAmountRequired, pr.Requirements.Asset)
    return
}
if se, ok := err.(*stoka.StokaError); ok {
    fmt.Printf("HTTP %d: %s\n", se.Status, se.Body)
    return
}

5. Pointing at your own host

c, err := stoka.New(stoka.Options{
    BaseURL: "https://stoka.example.com",
    Secret:  os.Getenv("STELLAR_SECRET"),
    RPCURL:  "https://stellar-rpc.example.com",  // required for pubnet
})