Go API reference

Package path: github.com/ajbeach2/stoka-go

Types

type Env

String alias picking which stoka deployment to target.

Value	Meaning
stoka.Production	https://api.stoka.space on stellar:pubnet
stoka.Testnet	https://test.api.stoka.space on stellar:testnet

Env.BaseURL() returns the canonical origin.

type Options

Field	Type	Purpose
Env	Env	Deployment picker. Default: Production.
BaseURL	string	Overrides Env's URL. Used for forks / CI.
Secret	string	Stellar S… seed. Used to sign x402 payments.
Signer	Signer	Custom payment signer (HSM, remote, test stub). Wins over native.
HTTPClient	*http.Client	Transport. Default: 60s-timeout stdlib client.
RPCURL	string	Soroban RPC override. Required for pubnet.

type Signer

type Signer interface {
    SignPayment(ctx context.Context, pr x402.PaymentRequirements) (string, error)
}

Implementations must be safe for concurrent use. Return the base64 X-PAYMENT header value.

type Client

The main entry point. Construct with stoka.New(Options{…}). Clients are goroutine-safe. Methods:

Method	Purpose
Store	POST /v1/store — create a new blob. Paid.
Update	PUT /v1/object/{key} — overwrite an existing blob. Paid.
Retrieve	GET /v1/retrieve/{key} — fetch a blob. Paid.
Delete	DELETE /v1/object/{key} — free, wallet-signed (not yet wired).
WellKnown	GET /.well-known/stoka.json — manifest + pricing. Free.
PublicKey()	Return the G… address derived from Secret.
BaseURL()	Return the HTTP origin in use.
Close()	Release idle transport connections.

type StoreOptions

type StoreOptions struct {
    TTLSeconds int // 0 = server default (30 days)
}

type RetrieveOptions

type RetrieveOptions struct {
    OwnerHint string // "-" to skip the X-Stoka-Owner hint
}

type StoreResponse

type StoreResponse struct {
    OwnerPubkey   string          `json:"owner_pubkey"`
    Key           string          `json:"key"`
    ExpiresAt     time.Time       `json:"expires_at"`
    TTLSeconds    int             `json:"ttl_seconds"`
    ChargedAtomic int64           `json:"charged_atomic"`
    Raw           json.RawMessage `json:"-"`
}

Errors

type StokaError

Non-2xx the client cannot retry. .Status and .Body carry the server's response verbatim.

type PaymentRequired

Returned when the server responds 402 and the client cannot auto-pay (no signer, insufficient funds, unknown asset). .Requirements is the parsed accepts[0] entry.

Subpackages

github.com/ajbeach2/stoka-go/x402

Standalone x402 "exact" scheme signer for Stellar. Usable outside stoka if you're integrating x402 into your own service.

res, err := x402.BuildExactPayment(ctx, secret, x402.PaymentRequirements{
    Scheme:            "exact",
    Network:           "stellar:testnet",
    Asset:             "CBIE…",
    PayTo:             "GAA…",
    MaxAmountRequired: "1170",
    Extra:             map[string]any{"areFeesSponsored": true},
}, x402.Options{})

req.Header.Set("X-PAYMENT", res.XPayment)