VerifyEntitlementResult.Granted had json tag "granted", but the real API (apps/api/src/routes/entitlements.ts -> packages/entitlements's EntitlementService.verify / ServiceVerifyResult) has only ever returned "allowed". encoding/json leaves unmatched fields at their zero value, so Granted silently decoded to false for every real response — any Go backend gating paid access via this SDK denied every real, fully-paid customer, with no error ever raised. Same bug shape as the already-fixed Python x402 verifier (a27d0051): an SDK's only production path silently rejecting everything real. Rename Granted -> Allowed (json:"allowed"), add the Entitlement and Value fields the API actually returns, and give Raw a real UnmarshalJSON instead of a json:"-" tag that silently excluded it from ever being populated despite the doc comment's "preserved in Raw" claim. Add Email support to VerifyEntitlementInput/ListEntitlementsOptions, matching the API's own "check by the buyer's checkout email instead of a customer id" capability, which the Go SDK had no way to express. Add the first regression tests for this file (sdks/go had none): one that would not even compile against the old field names, proving this isn't a cosmetic rename. Also fix a second real blocker for any Go developer trying to use this SDK at all: go.mod's module path (github.com/settlekit/settlekit-go) and every README/docs reference to it pointed at a GitHub org that does not exist (confirmed 404 on github.com and the Go module proxy) — `go get` of the documented path fails for everyone. Changed the module path to this repository's real path (github.com/caelum0x/settlekit/sdks/go) and updated sdks/go/README.md, docs/WEBHOOKS.md, docs/RELEASING-SDKS.md to match. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
settlekit-go
The official Go SDK for the SettleKit REST API.
- Standard library only — depends solely on
net/http,encoding/json,context,time,errors,crypto/rand, etc. No third-party modules, so it builds offline with zero external dependencies. - Typed envelope handling — every success response is the
{ "data": ... }envelope; every failure is{ "error": { code, message, details? } }with the HTTP status carrying the error. The SDK decodes both and returns a typed*APIErroron non-2xx. - Idempotent writes — every mutating request (
POST/PUT/PATCH/DELETE) automatically carries a randomIdempotency-Keyheader derived fromcrypto/rand.
Installation
go get github.com/caelum0x/settlekit/sdks/go
Module path: github.com/caelum0x/settlekit/sdks/go (Go 1.24+). This SDK lives
in a subdirectory of the main caelum0x/settlekit
monorepo rather than its own repo — the github.com/settlekit GitHub org this
README used to point at does not exist, so go get of the old path 404s.
Authentication
Requests are authenticated with a Bearer API key
(Authorization: Bearer <apiKey>). The public auth endpoints under /v1/auth
(register, login, magic links) do not require an API key. Session-scoped auth
calls (Session, Logout) take an explicit session token argument that is sent
as the Bearer token for that request.
Configuration
c := settlekit.New(
"sk_live_xxx",
settlekit.WithBaseURL("https://api.settlekit.dev"), // default: http://localhost:8787
settlekit.WithHTTPClient(&http.Client{Timeout: 10 * time.Second}),
)
Error handling
product, err := c.GetProduct(ctx, "prod_missing")
if err != nil {
var apiErr *settlekit.APIError
if errors.As(err, &apiErr) {
log.Printf("API error: status=%d code=%s message=%s",
apiErr.Status, apiErr.Code, apiErr.Message)
}
return err
}
Runnable example
package main
import (
"context"
"errors"
"fmt"
"log"
"time"
settlekit "github.com/caelum0x/settlekit/sdks/go"
)
func main() {
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()
client := settlekit.New(
"sk_live_your_api_key",
settlekit.WithBaseURL("http://localhost:8787"),
)
// 1. Create a product.
product, err := client.CreateProduct(ctx, settlekit.CreateProductInput{
MerchantID: "merchant_123",
OrganizationID: "org_123",
Name: "Pro Plan",
Description: "Everything in Pro",
Type: "saas_plan",
DeliveryMode: "saas_entitlement",
})
if err != nil {
log.Fatalf("create product: %v", err)
}
fmt.Printf("product: %s (%s)\n", product.ID, product.Status)
// 2. Attach a monthly price.
price, err := client.CreatePrice(ctx, product.ID, settlekit.CreatePriceInput{
Amount: "25.00",
Currency: "USDC",
Interval: "monthly",
})
if err != nil {
log.Fatalf("create price: %v", err)
}
// 3. Publish the product (requires an active price).
if _, err := client.PublishProduct(ctx, product.ID); err != nil {
log.Fatalf("publish product: %v", err)
}
// 4. Create a customer.
customer, err := client.CreateCustomer(ctx, settlekit.CreateCustomerInput{
OrganizationID: "org_123",
Email: "buyer@example.com",
WalletAddress: "0xabc...",
})
if err != nil {
log.Fatalf("create customer: %v", err)
}
// 5. Open a checkout session.
session, err := client.CreateCheckoutSession(ctx, settlekit.CreateCheckoutSessionInput{
OrganizationID: "org_123",
MerchantID: "merchant_123",
CustomerID: customer.ID,
Items: []settlekit.CheckoutLineItemInput{
{PriceID: price.ID, ProductID: product.ID, Quantity: 1},
},
PayToAddress: "0xmerchant...",
Network: "base",
})
if err != nil {
log.Fatalf("create checkout session: %v", err)
}
fmt.Printf("checkout: %s total=%s %s\n",
session.ID, session.Amount.Amount, session.Amount.Currency)
// 6. Record and confirm a payment; entitlements are granted on confirm.
payment, err := client.RecordPayment(ctx, settlekit.RecordPaymentInput{
CheckoutSessionID: session.ID,
})
if err != nil {
log.Fatalf("record payment: %v", err)
}
confirmed, err := client.ConfirmPayment(ctx, payment.ID, settlekit.ConfirmPaymentInput{
TxHash: "0xdeadbeef",
Confirmations: 12,
})
if err != nil {
log.Fatalf("confirm payment: %v", err)
}
fmt.Printf("payment %s confirmed; %d entitlement(s) granted\n",
confirmed.Payment.ID, len(confirmed.Entitlements))
// 7. Verify access on the hot path.
verdict, err := client.VerifyEntitlement(ctx, settlekit.VerifyEntitlementInput{
CustomerID: customer.ID,
ProductID: product.ID,
})
if err != nil {
var apiErr *settlekit.APIError
if errors.As(err, &apiErr) {
log.Fatalf("verify failed: %s (%s)", apiErr.Message, apiErr.Code)
}
log.Fatalf("verify: %v", err)
}
fmt.Printf("access granted: %t\n", verdict.Allowed)
}
Supported resources
| File | Methods (selected) |
|---|---|
products.go |
CreateProduct, ListProducts, GetProduct, PublishProduct, CreatePrice, ListPrices, CreateCustomer, ListCustomers, GetCustomer, CreateBundle, ListBundles, GetBundle, UpdateBundle, PublishBundle |
checkout.go |
CreateCheckoutSession, GetCheckoutSession, CollectCheckoutFields, CancelCheckoutSession, ExpireCheckoutSession |
payments.go |
RecordPayment, GetPayment, ConfirmPayment, FailPayment, RefundPayment, CreateRefund, ListRefunds, SucceedRefund, FailRefund, CreatePayout, ListPayouts, PayoutBalance, MarkPayoutPaid, FailPayout |
entitlements.go |
ListEntitlements, GetEntitlement, VerifyEntitlement, SpendCredits, RevokeEntitlement |
licensekeys.go |
IssueLicenseKey, VerifyLicenseKey, IssueLicenseToken, RevokeLicenseKey |
apikeys.go |
IssueApiKey, VerifyApiKey, RevokeApiKey |
coupons.go |
CreateCoupon, ListCoupons, GetCoupon, ValidateCoupon, RedeemCoupon |
invoices.go |
CreateInvoice, ListInvoices, GetInvoice, FinalizeInvoice, PayInvoice, VoidInvoice |
auth.go |
Register, Login, RequestMagicLink, CompleteMagicLink, Session, Logout |
marketplace.go |
CreateListing, ListListings, GetListing, PublishListing, RateListing, SellerProfile |
agentservices.go |
CreateAgentService, ListAgentServices, PublishAgentService, AgentServiceMetadata |
usage.go |
RecordUsage, GetCredits, GrantCredits, ConsumeCredits |
subscriptions.go |
CreateSubscription, ListSubscriptions |
payouts.go |
Payout status constants — payout methods (CreatePayout, ListPayouts, MarkPayoutPaid, PayoutBalance, FailPayout) live in payments.go |
webhooks.go |
CreateWebhookEndpoint, EmitEvent, ComputeSignature, VerifySignature |
Marketplace, agent services, usage & subscriptions
// Publish a marketplace listing and discover it.
listing, _ := c.CreateListing(ctx, settlekit.CreateListingInput{
OrganizationID: "org_123", MerchantID: "merchant_123", ProductID: product.ID,
Title: "Pro Plan", Tags: []string{"saas", "api"},
})
c.PublishListing(ctx, listing.ID)
top, _ := c.ListListings(ctx, settlekit.ListListingsOptions{Query: "pro", Tag: "saas", Sort: "top"})
profile, _ := c.SellerProfile(ctx, "merchant_123")
// Register a paid agent service and read its metadata.json.
svc, _ := c.CreateAgentService(ctx, settlekit.CreateAgentServiceInput{
OrganizationID: "org_123", MerchantID: "merchant_123",
Name: "summarize", Endpoint: "https://agents.example.com/summarize",
Amount: "0.01", Currency: "USDC", Network: "base",
})
c.PublishAgentService(ctx, svc.ID)
meta, _ := c.AgentServiceMetadata(ctx, svc.ID)
// Metered usage and prepaid credits.
c.RecordUsage(ctx, settlekit.RecordUsageInput{
OrganizationID: "org_123", CustomerID: customer.ID, ProductID: product.ID,
Metric: "api_calls", Quantity: 5,
})
c.GrantCredits(ctx, "org_123", 1000)
balance, _ := c.GetCredits(ctx, "org_123")
c.ConsumeCredits(ctx, "org_123", 10)
// Recurring subscriptions.
sub, _ := c.CreateSubscription(ctx, settlekit.CreateSubscriptionInput{
OrganizationID: "org_123", CustomerID: customer.ID,
ProductID: product.ID, PriceID: price.ID,
})
subs, _ := c.ListSubscriptions(ctx, customer.ID)
Webhooks
Register an endpoint, emit events, and verify delivered-event signatures. Each
delivery carries an X-SettleKit-Signature: v1=<hex> header, where the hex is
the HMAC-SHA256 of the raw request body keyed by the endpoint's signing
secret:
ep, _ := c.CreateWebhookEndpoint(ctx, settlekit.CreateWebhookEndpointInput{
OrganizationID: "org_123",
URL: "https://example.com/webhooks/settlekit",
EnabledEvents: []string{"payment.confirmed", "subscription.created"},
})
secret := ep.SigningSecret // returned once at creation — store it securely
c.EmitEvent(ctx, settlekit.EmitEventInput{
OrganizationID: "org_123",
Type: "payment.confirmed",
Data: map[string]any{"paymentId": "pay_123"},
})
// In your HTTP handler, verify before trusting the payload:
func handler(w http.ResponseWriter, r *http.Request) {
body, _ := io.ReadAll(r.Body)
if !settlekit.VerifySignature(secret, body, r.Header.Get(settlekit.SignatureHeader)) {
http.Error(w, "invalid signature", http.StatusUnauthorized)
return
}
var event settlekit.WebhookEvent
json.Unmarshal(body, &event)
// ... handle event.Type
}
VerifySignature compares in constant time (hmac.Equal) and returns false
for missing, malformed, or mismatched signatures. ComputeSignature produces
the same v1=<hex> value the server sends, for testing or re-signing.
Money
All monetary values use the Money type — a decimal-string Amount plus a
Currency ("USDC"). SettleKit never uses floating point for money, so amounts
are passed and returned as decimal strings such as "25.50".
License
MIT