taphubserver

taphub-sdk-go

Go SDK for the TapHub agency API with HMAC authentication. The Go counterpart of @taphubhq/sdk-server — same wire format, same error semantics, same retry behavior.

Server-only. This package signs every request with your agency secret. Never embed it in a binary distributed to untrusted hosts.

Installation

go get github.com/TaphubHQ/taphub-sdk-go@v0.5.0

Requires Go 1.22+.

Builder.GetBuilderLeaderboard requires backend support. The grid-api rank_leaderboardV2 query and the x-taphub-authorization user-forwarding header must be deployed server-side. Available from v0.5.0; see the operation below.

Auth.LoginS2S requires a multi-region backend. The mutation selects AuthResponse.homeRegion; a taphub-user-service whose schema predates multi-geo rejects the query and every login fails. See Multi-region.

v0.1.0 is retracted. The initial release shipped with a Wallet.Transfer wire body that the backend now rejects (missing tx_ref / currency, sends an obsolete direction field). Upgrade to v0.2.0+. See "Migrating from v0.1.0" below.

Configuration

All five string fields are required. The SDK does not read environment variables internally — you control how credentials are provided.

import (
    "context"
    "os"

    taphub "github.com/TaphubHQ/taphub-sdk-go"
)

client, err := taphub.New(taphub.Config{
    APIKey:       os.Getenv("TAPHUB_APIKEY"),
    AgencyID:     os.Getenv("TAPHUB_AGENCY_ID"),
    AgencySecret: os.Getenv("TAPHUB_AGENCY_SECRET"),
    BuilderCode:  os.Getenv("TAPHUB_BUILDER_CODE"),
    Endpoint:     os.Getenv("TAPHUB_ENDPOINT"), // e.g. https://api.taphub.io
})
if err != nil {
    // Missing field, or Endpoint not https:// / http://localhost.
    panic(err)
}

BuilderCode is the short identifier TapHub assigns each builder (agency). The backend resolves the canonical agency UUID from this code via the x-builder-code header. It is an identifier, not a secret, and is rendered verbatim by Config.String().

The Endpoint must use https:// (or http://localhost for local development). Plain http:// URLs are rejected.

Config.HTTPClient is optional. When nil, a default *http.Client with Timeout: 30 * time.Second is used. Pass your own to customize transport (proxies, TLS configuration, instrumentation, custom timeout).

Operations

client.User.Create

Provision a user under your agency.

raw, err := client.User.Create(ctx, taphub.UserCreateParams{
    AgencyUID: "user-123",
    Username:  "alice",
})

client.Wallet.Transfer

Transfer funds to or from a user's wallet. Ref is a mandatory idempotency key. Currency must match the agency configuration. Amount is always a positive decimal string — Direction controls the sign on the wire.

import "github.com/google/uuid" // any UUID library works

result, err := client.Wallet.Transfer(ctx, taphub.WalletTransferParams{
    Ref:       uuid.NewString(),
    AgencyUID: "user-123",
    Amount:    "10.00",
    Direction: taphub.DirectionDeposit,
    Currency:  "USDC.e",
})
// result: *taphub.WalletTransferResult{ID, WalletID, UserID, Amount, BeforeAmount, AfterAmount, Ref, Timestamp}

Direction must be DirectionDeposit or DirectionWithdraw. Amount is a string (decimal) to avoid floating-point precision loss on money values. The SDK rejects negative Amount inputs — use Direction to express withdraw instead.

client.Wallet.Reserve / Commit / Cancel — 2-phase reservation

For safe wrapping around irreversible external actions (on-chain withdraws, payment-gateway payouts, KYC holds), use the 2-phase API instead of Transfer. Reserve creates a PENDING wallet transaction and atomically moves funds from Wallet.Amount to Wallet.ReservedAmount. Follow with Commit (PENDING → FINISHED, funds finalized) on success, or Cancel (PENDING → FAILED, balance restored) on failure. The platform auto-cancels stale PENDING reservations after TTLSeconds (default 1800s, clamped server-side to [60, 86400]).

import "github.com/google/uuid"

ttl := 600 // optional; backend clamps to [60, 86400]
rsv, err := client.Wallet.Reserve(ctx, taphub.WalletReserveParams{
    Ref:        uuid.NewString(),
    AgencyUID:  "user-123",
    Amount:     "10.00",
    Direction:  taphub.DirectionWithdraw, // only Withdraw is currently accepted (see note)
    Currency:   "USDC.e",
    TTLSeconds: &ttl,
})
// rsv: *taphub.WalletReservation{ID, WalletID, UserID, Amount, BeforeAmount, AfterAmount, Ref, Status, TTLSeconds, ExpiresAt, Timestamp}

// ... perform on-chain tx, wait confirmation ...

if onChainConfirmed {
    _, err = client.Wallet.Commit(ctx, rsv.Ref)
} else {
    _, err = client.Wallet.Cancel(ctx, rsv.Ref)
}

Backend transport (since v0.4.0): GraphQL mutations agencyReserve / agencyCommit / agencyCancel on /th-user-gql. Same HMAC signing as LoginS2S. Error codes surface on *Error.Code via the GraphQL errors[].extensions.code field.

REST endpoints deprecated: the legacy REST paths POST /api/user/v1/agency/{reserve,commit,cancel} still respond but log a [deprecated] WARN per request server-side and will be removed in a future taphub-user-service release. Pin SDK ≥ v0.4.0 to ride the GraphQL path automatically.

Error code mappings (preserved on *Error.Code):

• ErrTxRefConflict — replay with mismatched body, or another agency squatted the ref
• ErrInsufficientBalance — Wallet.Amount < abs(Amount)
• ErrReservationNotFound — unknown ref, or ref belongs to another agency
• ErrReservationAlreadyCommitted — cancelling a FINISHED row
• ErrReservationAlreadyCancelled — committing a FAILED row
• ErrTransferModeNotSupported — agency is Seamless-mode

Direction restriction: the backend currently rejects deposit-direction reservations (positive amount) — see OpenSpec change user-260527-agency-wallet-reserve VULN-002. The SDK fails fast at the validation layer for DirectionDeposit. Only DirectionWithdraw is accepted until commit-of-deposit semantics are designed.

client.Auth

Server-to-server identity. Two methods:

client.Auth.LoginS2S

Exchange your agency's HMAC-signed identity for an access token keyed by a partner-supplied user ID. Use this from a builder backend.

resp, err := client.Auth.LoginS2S(ctx, taphub.LoginS2SInput{
    PartnerUserID: "user-123",
    DisplayName:   "alice",
})
// resp: *taphub.AuthResponse{AccessToken, User: AuthUser{ID, Name, Currency}, HomeRegion}

ClientMeta and Region are optional and are omitted from the request entirely when unset. If you run against more than one region, read Multi-region — there are obligations you cannot skip.

client.Auth.UserLogin

Exchange a Privy session token (issued to a builder frontend) for an access token. No HMAC — the session token is the credential.

resp, err := client.Auth.UserLogin(ctx, sessionToken)

GraphQL errors carrying extensions.code in {Unauthorized, TokenExpired, NotAuthenticated} surface as *Error{Kind: KindAuth}; all other GraphQL errors surface as *Error{Kind: KindValidation}. Backend code is preserved on *Error.Code. The three multi-region codes are classified separately — see Multi-region.

Wallet lookups

Three read-only methods. They share the HMAC transport with Transfer and return camelCase Go structs (no snake_case keys leak to callers).

client.Wallet.GetUserWallet

w, err := client.Wallet.GetUserWallet(ctx, "user-123")
// w: *taphub.Wallet{ID, Amount, Currency, IsEnabled}

client.Wallet.ListUserWallets

wallets, err := client.Wallet.ListUserWallets(ctx, "user-123")
// wallets: []taphub.Wallet

client.Wallet.GetTxByRef

Look up a wallet transaction by the same Ref passed to Transfer.

tx, err := client.Wallet.GetTxByRef(ctx, "my-ref-123")
// tx: *taphub.WalletTransaction
if errors.Is(err, taphub.ErrNotFound) {
    // Backend code preserved on the *Error, e.g. "TransactionNotFound".
}

v0.1 note: Lookup methods do not accept a currency parameter. The backend infers currency from your agency configuration.

client.Wallet.GetUserFundingSummary

Aggregated deposit/withdraw activity for one of your users, in one currency, over an optional window — for reconciling your funding ledger against TapHub's without paging the transaction list and summing it yourself.

sum, err := client.Wallet.GetUserFundingSummary(ctx, taphub.UserFundingSummaryParams{
    AgencyUID: "user-123",
    Currency:  "USDC.e",
    // From / To optional (*time.Time). Omit both for all-time.
})
// sum.DepositCount / sum.WithdrawCount        — finished transaction counts
// sum.DepositAmount / sum.WithdrawAmount      — decimal strings, both POSITIVE
// sum.PendingDepositCount, sum.PendingDepositAmount, … — same four, still in flight
// sum.From / sum.To                           — the window the server actually served

Currency is required: a user may hold several wallets, and a total summed across currencies is arithmetically valid but meaningless.

The window is half-open — From inclusive, To exclusive — so consecutive windows tile without double-counting a transaction on the boundary.

Withdrawals are returned as positive magnitudes, so DepositAmount - WithdrawAmount is the net funding flow. Amounts are decimal strings, never floats; pass them to shopspring/decimal if you need arithmetic.

Pending totals are reported separately rather than folded in, because that is where reconciliation mismatches live: a total short by 50 is a different problem depending on whether the 50 is in flight or lost.

Read this before drawing conclusions. These numbers cover only what TapHub recorded. A request that never reached TapHub — a network failure before the write — appears in none of them, so comparing balances alone cannot tell "a request was lost" apart from "the ledger is correct". Reconcile the count of requests you issued against DepositCount / WithdrawCount, not just the amounts.

Transfer-mode agencies only; seamless agencies are rejected with TransferModeNotSupported. An unknown AgencyUID returns an all-zero summary rather than an error — as does a uid belonging to another agency, deliberately, so the call cannot be used to probe another builder's user ids.

Requires a backend carrying the builderUserFundingSummary query (OpenSpec change builder-260820-funding-reconciliation); older deployments reject it as an unknown field.

client.Builder.GetBuilderLeaderboard (since v0.5.0)

Fetch the agency-scoped ("builder") leaderboard. Wraps grid-api's rank_leaderboardV2 query as an HMAC-signed server-to-server call. Period is required; all other fields are optional and fall back to server defaults (sort=pnl, sortDir=desc, limit=50, offset=0).

limit, offset := 50, 0
board, err := client.Builder.GetBuilderLeaderboard(ctx, taphub.BuilderLeaderboardInput{
    Period:  taphub.RankPeriodLast7d,        // today | yesterday | last_7d | last_30d | all_time | custom
    Sort:    taphub.RankSortPnl,             // pnl (net profit) | vol (volume); optional
    SortDir: taphub.SortDirDesc,             // asc | desc; optional
    Limit:   &limit, Offset: &offset,        // optional pagination
})
// board: *taphub.BuilderLeaderboard{ Total, Entries []RankEntry, Range, ... }
// Decimal fields (Pnl, Vol, Payout) are strings to preserve precision.
// The board is public + cacheable — it carries no per-user data. For the caller's
// own rank, use GetMyRank (below).

For RankPeriodCustom, supply an hour-aligned UTC window via Range. The bounds are time.Time values, sent to grid-api as ISO 8601 / RFC3339 (yyyy-mm-ddThh:mm:ssZ); the returned board.Range.From/To are the resolved (hour-aligned) time.Time window:

board, err := client.Builder.GetBuilderLeaderboard(ctx, taphub.BuilderLeaderboardInput{
    Period: taphub.RankPeriodCustom,
    Range: &taphub.TimeRange{
        From: time.Date(2024, 6, 1, 0, 0, 0, 0, time.UTC),
        To:   time.Date(2024, 6, 2, 0, 0, 0, 0, time.UTC),
    },
})

client.Builder.GetMyRank

Fetch a specific user's own row + rank, the per-user companion to the public board (grid-api's rank_me query). The board and GetMyRank read the same ranked window, so the returned rank agrees with the board's ordering. Pass WithUserToken(accessToken) — the access token from Auth.LoginS2S / Auth.UserLogin; the user JWT is forwarded on the x-taphub-authorization header (the agency HMAC signature keeps Authorization). Without a user token there is no identity to rank: the method returns (nil, nil).

auth, _ := client.Auth.LoginS2S(ctx, taphub.LoginS2SInput{PartnerUserID: "user-123", DisplayName: "alice"})

mine, err := client.Builder.GetMyRank(ctx, taphub.MyRankInput{
    Period: taphub.RankPeriodLast7d,        // same window selector as the board, minus pagination
}, taphub.WithUserToken(auth.AccessToken))
// mine: *taphub.MyRank{ Rank, Total, Entry *RankEntry } for user-123 — even if outside the page.
// mine == nil when the caller is anonymous (no user token). mine.Entry == nil if no activity.

MyRankInput accepts the same RankPeriodCustom + Range as the board.

Transport: both methods target grid-api at /api/grid-api/grid-gql (the gateway's grid route), not /th-user-gql. Same HMAC signing as LoginS2S.

client.Builder.GetAgencyBids

List a page of full bid rows for the authenticated builder agency, plus the total match count. Wraps grid-api's agencyBids query as an HMAC-signed server-to-server call. The agency is resolved from the request context (x-builder-code + x-api-key); callers do not pass an agency ID.

res, err := client.Builder.GetAgencyBids(ctx, taphub.AgencyBidsInput{
    GameID:    "grid-ETH-USD", // optional
    AgencyUID: "buid-123",     // optional: the builder's own user id (reverse-mapped); exclusive with UserID
    UserID:    "user-123",     // optional grid-api user ID
    Status:    "pending",      // optional: pending | won | lost | cancelled
    Demo:      &demo,          // optional *bool: nil → no filter, true → demo bids only, false → real bids only
    Range:     &taphub.TimeRange{From: from, To: to}, // optional: filter by created_at (From <= To)
    Limit:     50,             // optional; server default 50, max 200
    Offset:    0,              // optional
})
// res: taphub.AgencyBidsResult{ Items []Bid, Total, Limit, Offset int }.
// Total is the full count matching the filter (independent of Limit/Offset).
// Each Bid carries AgencyUID + UserName (the user's LIVE display name). Decimal fields are
// strings, Time1/Time2 are unix seconds, CreatedAt/UpdatedAt/CancelledAt are RFC3339 strings.

Pass the zero-value AgencyBidsInput{} to use the backend defaults and list the agency's most recent bids. Sending both AgencyUID and UserID is rejected by grid-api (InvalidParam).

client.Builder.GetRetentionKpiCard (since v0.11.0)

The agency's retention KPI pair — the cohort of distinct users active in PreviousRange and the subset of that cohort that returned in CurrentRange. Wraps grid-api's builderRetentionKpiCard query as an HMAC-signed server-to-server call (x-builder-code + x-api-key + body HMAC, same auth as every Builder call); the agency is resolved server-side from those credentials — callers do not pass an agency ID.

card, err := client.Builder.GetRetentionKpiCard(ctx, taphub.RetentionKpiCardInput{
    ProductType:   taphub.RetentionProductPredictionGrid, // only prediction_grid is served today
    Granularity:   taphub.RetentionGranularityWeek,       // day | week | month
    PreviousRange: taphub.TimeRange{From: mon, To: mon.AddDate(0, 0, 7)}, // exactly ONE calendar bucket
    CurrentRange:  taphub.TimeRange{From: mon.AddDate(0, 0, 7), To: mon.AddDate(0, 0, 14)},
})
// card.CurrentRangeUsers is an INTERSECTION with the cohort (always <= PreviousRangeUsers) —
// never an independent count of the current window. Rate = current / previous (caller-side).

Each range must be exactly one UTC-aligned calendar bucket of Granularity (week = Monday 00:00 UTC + 7 days; month = the 1st + the real month length), non-overlapping and in order — grid-api rejects anything else with Retention_InvalidRange. Other rejections: Retention_ProductUnavailable (product line has no rollup data) and Retention_RangeBeyondRetention (range starts before the 800-day rollup horizon). All surface as *taphub.Error with Kind == KindValidation and the code in Error.Code.

client.Builder.GetRetentionTrend (since v0.11.0)

The agency's cohort-retention matrix — the latest N cohorts by granularity (day 14×7, week 12×8, month 12×12; fixed server-side), each followed across subsequent periods. Wraps grid-api's builderRetentionTrend query; same auth (x-builder-code + x-api-key + body HMAC) and error codes as GetRetentionKpiCard.

trend, err := client.Builder.GetRetentionTrend(ctx, taphub.RetentionTrendInput{
    ProductType: taphub.RetentionProductPredictionGrid,
    Granularity: taphub.RetentionGranularityWeek,
    // Anchor names ONE calendar period (normally the current one); the grid is derived
    // backwards from it (newest cohort = anchor − 1 period). A future anchor is rejected.
    Anchor: taphub.TimeRange{From: mon, To: mon.AddDate(0, 0, 7)},
})
// trend.Rows is newest-cohort-first, each with exactly trend.MaxPeriod cells.
// Cell contract (load-bearing): RetainedUsers == nil means the target period has NOT started;
// a pointer to 0 means "read, nobody returned"; the in-progress current period reports a
// partial, still-rising number. Never coalesce nil to 0. Compare a cell's TargetFrom against
// trend.DataThrough to identify the partial trailing diagonal.

client.Ping

Connectivity + auth check.

raw, err := client.Ping(ctx)

Multi-region

Backend requirement: the loginS2S mutation selects homeRegion, so this SDK requires a taphub-user-service on the multi-region schema. Against an older cluster every login fails with a GraphQL validation error. Verify before upgrading.

TapHub runs one full regional stack per region. Each user is pinned to exactly one home region, write-once at their FIRST login — their user row and wallet physically live there. The pin cannot be changed until the region-migration feature ships.

The regional endpoint that receives a user's first login becomes their home region, permanently. Route it wrong and every bid that user ever places pays a cross-continent round trip.

If you deploy against more than one region, three obligations bind (full contract: docs/sdk/multi-region-integration.md):

1. Persist homeRegion per user. Every login returns it. Reading it without storing it re-pins by luck on every login.

2. Route by the stored region. A user's subsequent loginS2S — and every other S2S call for them, wallet operations included — goes to that region's endpoint. The SDK does not route for you: it is a stateless client and home region is per-user state you own. Build one client per region and pick.

3. Retry once on Auth_WrongRegion.

resp, err := clientFor(storedRegion).Auth.LoginS2S(ctx, in)
if region, ok := taphub.WrongRegionTarget(err); ok {
    resp, err = clientFor(region).Auth.LoginS2S(ctx, in) // ONCE — never a loop
    // ...then persist `region` so the next login routes straight there.
}

Pinning is write-once, so a second rejection means a bug, not a race. The SDK deliberately does not retry for you: it would fire before you could persist the correction, and it would hide a cross-continent hop inside a call that looks local.

First-join routing

For a user with no stored region, route their first login to the region nearest them. If your frontend measures which region responds fastest, forward its proposal in ClientMeta under preferredRegion — the backend validates it against its deployed regions and uses it to pin.

meta := `{"tz":"Asia/Ho_Chi_Minh","preferredRegion":"sg"}` // built by your FE, forwarded verbatim
resp, err := client.Auth.LoginS2S(ctx, taphub.LoginS2SInput{
    PartnerUserID: "user-123",
    DisplayName:   "alice",
    ClientMeta:    &meta,
})

ClientMeta is sent byte for byte — the SDK never parses or re-encodes it. Alternatively, Region names the caller's own current region as a first-join candidate; leave it empty if you geo-route instead.

HomeRegion is empty when the backend returns null: the region-directory is unconfigured (feature off), or this is a demo/refresh path.

Region error codes

Code	Constant	Kind	Retried by the SDK	Your reaction
Auth_WrongRegion	CodeAuthWrongRegion	KindAuth	no	Retry once at WrongRegionTarget(err); update the stored region
Auth_RegionUnavailable	CodeAuthRegionUnavailable	KindInternal	yes	Transient directory outage — the SDK's backoff already handles it
Auth_AgencyConfigUnavailable	CodeAuthAgencyConfigUnavailable	KindAuth	no	Usually a seeding gap on the TapHub side; contact TapHub if it persists

Auth_RegionUnavailable is the one Auth_* code deliberately not classified as KindAuth — that would suppress the retry the contract asks for and turn a momentary directory blip into a failed login.

Wallet operations land region-local

A user's wallet row lives in their home region. A wallet request for a user pinned elsewhere returns user-not-found and is quarantined on the TapHub side for manual review — it is never silently applied to a wrong-region wallet. Route wallet calls with the same stored homeRegion you use for logins.

Migrating from v0.1.0

v0.2.0 is a breaking minor bump (pre-1.0 SemVer rule). Three changes:

1. Config requires BuilderCode. The TapHub team assigns each builder a short code; you receive it alongside your APIKey / AgencyID. Without it the SDK refuses to construct and the backend returns 401 because its routing middleware reads x-builder-code.

   client, _ := taphub.New(taphub.Config{
       APIKey:       "...",
       AgencyID:     "...",
       AgencySecret: "...",
       BuilderCode:  "acme-corp", // NEW
       Endpoint:     "...",
   })
   

2. Wallet.Transfer adds required Currency and returns a typed *WalletTransferResult.

   v0.1.0:

   raw, _ := client.Wallet.Transfer(ctx, taphub.WalletTransferParams{
       Ref: "r", AgencyUID: "u", Amount: "10", Direction: taphub.DirectionDeposit,
   })
   // raw: json.RawMessage
   

   v0.2.0:

   result, _ := client.Wallet.Transfer(ctx, taphub.WalletTransferParams{
       Ref: "r", AgencyUID: "u", Amount: "10", Direction: taphub.DirectionDeposit,
       Currency: "USDC.e", // NEW required
   })
   // result: *taphub.WalletTransferResult{...}
   

   The wire body also changed: ref → tx_ref, direction removed, amount is sign-encoded for withdraw. All handled transparently by the SDK; you do not touch the wire.

3. Auth module is new. Existing callers do not have to use it, but if you previously rolled your own GraphQL client to call userLogin / loginS2S, you can replace that with client.Auth.UserLogin(ctx, token) or client.Auth.LoginS2S(ctx, input).

The compiler points at every site that needs updating: missing BuilderCode on Config, missing Currency on WalletTransferParams, and the changed Wallet.Transfer return type.

Security

Do not intercept the request body

The SDK signs the request body with HMAC-SHA256. The same bytes that are signed are sent on the wire. If your *http.Client transport, a proxy, or any middleware modifies, re-marshals, or recompresses the JSON, the signature will not match and the server will reject the request with an authentication error.

If you wrap Config.HTTPClient.Transport, do not touch req.Body.

Secret redaction

Config.AgencySecret never appears in fmt.Sprintf("%v", cfg), in json.Marshal(cfg), or in any field of the returned *Error. The transport never logs signatures.

Replay risk (v0.1)

In v0.1, each signed request is valid indefinitely if replayed. A future version will add a timestamp + nonce in the HMAC payload, coordinated with a backend change. In the meantime:

• Use Ref-based idempotency for Wallet.Transfer (the backend dedupes by Ref).
• Use distinct AgencyUID values for User.Create (the backend dedupes by agency_uid).
• Ensure your agency's IP whitelist is configured in the TapHub dashboard.

Error handling

Every operation returns either (result, nil) or (nil, *taphub.Error). The *Error value carries:

type Error struct {
    Kind       ErrorKind        // one of KindValidation, KindAuth, KindNotFound, ...
    Code       string           // backend error tag or "HTTP_<status>"
    Status     int              // HTTP status, 0 for network failures
    Message    string
    RetryAfter time.Duration    // from Retry-After header, when present
    Cause      error            // underlying transport/context error
    Details    json.RawMessage  // raw JSON error body, when present
    Meta       map[string]any   // errors[0].extensions.meta, when present
}

Meta carries the backend's structured error data. Today its only consumer is multi-region: Auth_WrongRegion puts the correct region under Meta["homeRegion"] — read it with WrongRegionTarget rather than indexing by hand.

Branch on Kind using the exported sentinels with errors.Is:

if _, err := client.Ping(ctx); err != nil {
    switch {
    case errors.Is(err, taphub.ErrAuth):
        // 401, 403 — wrong signature, blocked IP, etc.
    case errors.Is(err, taphub.ErrRateLimit):
        // 429 — back off.
    case errors.Is(err, taphub.ErrNetwork):
        // DNS / TCP / TLS / context cancellation.
    }
}

Inspect details with errors.As:

var e *taphub.Error
if errors.As(err, &e) && e.Code == "RefAlreadyUsed" {
    // Idempotent duplicate — safe to treat as already-applied.
}

Kind	HTTP status
KindValidation	400, 422
KindAuth	401, 403
KindNotFound	404
KindConflict	409
KindRateLimit	429
KindInternal	500–599, unmapped non-2xx
KindNetwork	DNS/TCP/TLS failures, context cancellation

Retry

The SDK retries transient failures with full-jitter exponential backoff.

Defaults

Field	Default	Description
MaxAttempts	3	Total attempts, including the first
BaseDelay	200ms	Base for exponential backoff
MaxDelay	5s	Upper bound per sleep

Trigger matrix

Kind	Retry?
KindNetwork	yes
KindInternal (5xx)	yes
KindRateLimit (429)	yes
KindAuth	no
KindValidation	no
KindNotFound	no
KindConflict	no

Synchronous validation errors (rejected before any HTTP request) bypass the retry loop entirely.

Backoff formula

cap   = min(MaxDelay, BaseDelay * 2^attemptIndex)
delay = rand.Float64() * cap

attemptIndex is 0-based for the first scheduled retry.

Retry-After honoring

If a failed response carries a Retry-After header (integer seconds or HTTP-date), the SDK uses that value (clamped to MaxDelay) for the next attempt. No jitter is applied to a server-supplied delay.

Disable per call

_, err := client.Wallet.Transfer(
    ctx,
    taphub.WalletTransferParams{Ref: "r-1", AgencyUID: "u-1", Amount: "1.00", Direction: taphub.DirectionDeposit},
    taphub.WithRetryDisabled(),
)

Disable for the whole client

client, _ := taphub.New(taphub.Config{
    APIKey: ..., AgencyID: ..., AgencySecret: ..., Endpoint: ...,
    Retry: &taphub.RetryConfig{Disabled: true},
})

Observability with OnRetry

client, _ := taphub.New(taphub.Config{
    APIKey: ..., AgencyID: ..., AgencySecret: ..., Endpoint: ...,
    Retry: &taphub.RetryConfig{
        OnRetry: func(info taphub.RetryInfo) {
            log.Printf("retry attempt=%d kind=%s sleep=%s",
                info.Attempt, info.Err.Kind, info.NextDelay)
        },
    },
})

A panic inside OnRetry is recovered and discarded — the retry loop never crashes the calling goroutine.

Context cancellation

If the request context.Context is cancelled or its deadline expires during a retry sleep, the loop exits immediately. The returned error has Kind == KindNetwork with Cause set to context.Canceled or context.DeadlineExceeded.

Mutation retry safety

Retry applies uniformly to mutations and reads. The backend dedupes by idempotency keys:

• Wallet.Transfer dedupes by Ref.
• User.Create dedupes by AgencyUID.

A duplicate surfaces as *Error with Kind == KindConflict (e.g. Code == "RefAlreadyUsed").

HMAC algorithm

The SDK uses HMAC-SHA256 over the raw UTF-8 bytes of the JSON request body, hex-encoded as a 64-character lowercase string. This matches the algorithm used by the backend verifier and by the TypeScript SDK (crypto.createHmac('sha256', secret).update(body).digest('hex')):

// Equivalent of the backend's hmac.GenerateHMAC and the TS createHmac call.
h := hmac.New(sha256.New, []byte(secret))
h.Write(body)
sig := hex.EncodeToString(h.Sum(nil))

A pinned (secret, body, expectedHex) fixture lives in testdata/hmac_vector.json and is verified by Test_HMAC_PinnedVector. The same fixture is reproducible by the Go reference and by the TS SDK; that is the cross-language wire-compat anchor.

Testing

Unit tests (no network):

go test ./...

Integration tests (require running dev-stack.sh and exported env vars):

export TAPHUB_APIKEY=...
export TAPHUB_AGENCY_ID=...
export TAPHUB_AGENCY_SECRET=...
export TAPHUB_ENDPOINT=https://api.taphub.io
go test -tags=integration ./...

Integration tests skip cleanly when any of those variables is unset.

License

MIT.