> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blnkfinance.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Using the SDK
> Configure authentication, timeouts, retries, logging, and request shapes for the Go SDK.
export const CtaCallout = props => {
const {title, buttonLabel, href, trackingEvent, buttonTarget, rel = "noopener noreferrer", children} = props;
const handleCtaClick = () => {
if (typeof window === "undefined" || !trackingEvent) {
return;
}
try {
window.dispatchEvent(new CustomEvent("blnk:docs-cta", {
detail: {
name: trackingEvent,
href
}
}));
} catch {}
try {
window.posthog?.capture?.(trackingEvent, {
href
});
} catch {}
const gaPayload = {
cta_href: href
};
try {
window.gtag?.("event", trackingEvent, gaPayload);
} catch {}
try {
window.dataLayer = window.dataLayer || [];
window.dataLayer.push({
event: trackingEvent,
...gaPayload
});
} catch {}
};
const isExternal = typeof href === "string" && (/^https?:\/\//i).test(href);
const target = buttonTarget ?? (isExternal ? "_blank" : undefined);
const linkRel = isExternal ? rel : undefined;
return ;
};
Configurable client options ship in v1.2.0. See the [Changelog](/changelog/blnk-go) before upgrading.
## Initialize the client
Your Blnk client is the single entry point to everything: ledgers, balances, transactions, reconciliation, and more. Configure it once when your app starts, then use it everywhere.
```go client.go theme={"system"}
package blnk
import (
"net/url"
"os"
"time"
blnkgo "github.com/blnkfinance/blnk-go"
)
func NewBlnkClient() *blnkgo.Client {
baseURL, _ := url.Parse(os.Getenv("BLNK_BASE_URL"))
if baseURL == nil || baseURL.String() == "" {
baseURL, _ = url.Parse("http://localhost:5001/")
}
apiKey := os.Getenv("BLNK_API_KEY")
return blnkgo.NewClient(
baseURL,
&apiKey,
blnkgo.WithTimeout(10*time.Second),
blnkgo.WithRetry(2),
)
}
```
That's it. One import, one call, one client. From here you can create ledgers, move money, reconcile transactions, and manage your entire financial infrastructure.
```go create-ledger.go theme={"system"}
client := NewBlnkClient()
ledger, resp, err := client.Ledger.Create(blnkgo.CreateLedgerRequest{
Name: "Customer Savings Account",
MetaData: map[string]interface{}{
"project_owner": "YOUR_APP_NAME",
},
})
if err != nil {
return err
}
fmt.Printf("Ledger created (HTTP %d): %s\n", resp.StatusCode, ledger.LedgerID)
```
Per-method SDK pages in the sidebar list each call on `client.Ledger`, `client.LedgerBalance`, and other services.
***
## Authentication
`NewClient` takes a base URL and an optional API key pointer. The SDK sends the key on every request in the `X-Blnk-Key` header when you pass a non-nil pointer.
How you set the API key depends on whether Core runs in secure mode:
When `server.secure` is enabled, pass a pointer to your API key as the second argument.
```go theme={"system"}
apiKey := os.Getenv("BLNK_API_KEY")
client := blnkgo.NewClient(baseURL, &apiKey)
```
When secure mode is off, pass `nil` as the API key.
```go theme={"system"}
client := blnkgo.NewClient(baseURL, nil)
```
Secure mode, master key, and server hardening.
Owner-scoped keys and permission limits.
***
## Timeouts and retries
When connections fail, Core restarts, or requests hang, the SDK handles it without blocking your app. Pass functional options to `NewClient` to tune behavior:
```go theme={"system"}
client := blnkgo.NewClient(
baseURL,
&apiKey,
blnkgo.WithTimeout(30*time.Second),
blnkgo.WithRetry(3),
blnkgo.WithRetryDelay(2*time.Second),
)
```
| Option | Type | Default | What it does for you |
| :--------------- | :-------------- | :------ | :------------------------------------------------------------------------------------------------------- |
| `WithTimeout` | `time.Duration` | `10s` | How long to wait before giving up on a request. Bump this for slow operations like bulk reconciliations. |
| `WithRetry` | `int` | `1` | Total attempts including the first try. `1` means no retries. `3` means up to three attempts. |
| `WithRetryDelay` | `time.Duration` | `2s` | Base delay between retries. Uses linear backoff. |
When to tune these:
* Keep defaults if you're making fast, local calls and want to fail fast.
* Increase `WithTimeout` if you're running large batch requests that may take a while to complete synchronously.
* Increase `WithRetry` if you're reading data across an unreliable network.
Retries apply to idempotent `GET` requests and retryable network failures. `POST`, `PUT`, and `DELETE` are not retried on HTTP errors.
***
## Custom logger
By default, the SDK logs retry and transport events through a built-in logger that writes to stdout with `INFO:` and `ERROR:` prefixes.
Pass a type that implements `blnkgo.Logger` to route these messages to your own logging system instead of stdout.
```go theme={"system"}
type appLogger struct{}
func (l appLogger) Info(msg string) { log.Println("info:", msg) }
func (l appLogger) Error(msg string) { log.Println("error:", msg) }
client := blnkgo.NewClient(
baseURL,
&apiKey,
blnkgo.WithLogger(appLogger{}),
)
```
| Level | When the SDK calls it |
| :------ | :------------------------------------------------------------------------------------ |
| `Info` | Before a retry, or when a retryable network failure will be retried |
| `Error` | When a request returns a retryable HTTP status on a `GET`, or exhausts retry attempts |
***
## Building transaction requests
Call `client.Transaction.Create` and pass a `blnkgo.CreateTransactionRequest` struct. It has two parts:
1. **`ParentTransaction`** holds the core transaction fields: amount, currency, source, destination, reference, and metadata.
2. **Top-level fields** control how the request is processed, such as `AllowOverdraft`, `Inflight`, and `ScheduledFor`.
`ParentTransaction` is an embedded struct in the Go SDK, not a field in the API request body. The API expects flat JSON with fields like `amount` and `source` at the root.
Do not confuse this struct with the API response field `parent_transaction`, which is a transaction ID linking related records such as inflight commits or split distributions.
```go theme={"system"}
blnkgo.CreateTransactionRequest{
ParentTransaction: blnkgo.ParentTransaction{
PreciseAmount: 100000,
Precision: 100,
Currency: "USD",
Source: "bln_28f25ef6-2e0d-4fa6",
Destination: "bln_86ba7976-499d-4282",
Reference: "payment_001",
},
AllowOverdraft: true,
}
```
Transactions are the exception. Every other resource uses a single request struct with no nesting. Pass `CreateLedgerRequest` to `client.Ledger.Create`, `CreateLedgerBalanceRequest` to `client.LedgerBalance.Create`, and so on.
***
## JSON field names
Go struct fields use PascalCase, like `MetaData` and `LedgerID`. These map to the API's snake\_case JSON fields (`meta_data`, `ledger_id`).
You should always use the Go field names in your code.
***
## Date and time fields
Fields such as `DOB`, `EffectiveDate`, `ScheduledFor`, `InflightCommitDate`, and historical balance timestamps use `time.Time` (or `*time.Time`). Parse ISO 8601 strings with `time.Parse(time.RFC3339, "...")`, for example `"2024-04-22T15:28:03Z"` or `"2024-12-21T01:36:46+01:00"`, then pass the resulting value. Use a pointer when the field is optional so zero values omit from JSON.
***
## Related docs
Install the SDK and create your first transaction.
Three-value returns and Core error bodies.
Go SDK releases and version history.
Escrow, savings, cards, and reconciliation.
***
## Need help?
We are very happy to help you make the most of Blnk, regardless of whether it is your first time or you are switching from another tool.
To ask questions or discuss issues, please [contact us](mailto:support@blnkfinance.com) or [join our Discord community](https://discord.gg/7WNv94zPpx).
Sign up and manage your ledger with our back-office dashboard. You can invite teammates to collaborate and manage your ledger operations directly from the dashboard.