Getting Started with the Go SDK • Blnk SDK Documentation

The Blnk Go SDK is the official Go client for Blnk Core. This page gets you from install to a working transaction. For detailed documentation on each API, reference the Core documentation.

Quick start

In a few minutes, you’ll have a Go app moving money on your Blnk ledger. That’s the starting point for wallets, transfers, and the rest of your product.

Launch Blnk

You need a running Blnk Core instance before using the SDK.

Install Blnk

Local install or Blnk Cloud

Install the Blnk Go SDK

Create a Go project and install the SDK. You need Go 1.22 or later.

bash

go mod init blnk-quickstart
go get github.com/blnkfinance/blnk-go

Client initialization

Parse your Blnk base URL and create a client. Pass a pointer to your API key when your instance requires authentication. The SDK sends it as the X-Blnk-Key header.Use nil when running locally without auth.

client.go

baseURL, _ := url.Parse("http://localhost:5001/")
apiKey := "your_api_key"
client := blnkgo.NewClient(
    baseURL,
    &apiKey,
    blnkgo.WithTimeout(10*time.Second),
    blnkgo.WithRetry(2),
)

Create your first transaction

Create main.go, paste the script below, and run it:

main.go

package main

import (
	"fmt"
	"net/url"
	"time"

	blnkgo "github.com/blnkfinance/blnk-go"
)

func main() {
	baseURL, _ := url.Parse("http://localhost:5001/")
	client := blnkgo.NewClient(
		baseURL,
		nil,
		blnkgo.WithTimeout(10*time.Second),
		blnkgo.WithRetry(2),
	)

	transaction, resp, err := client.Transaction.Create(blnkgo.CreateTransactionRequest{
		ParentTransaction: blnkgo.ParentTransaction{
			Amount:      1000,
			Reference:   "first_txn_001",
			Currency:    "USD",
			Precision:   100,
			Source:      "@FundingPool",
			Destination: "@MyBalance",
			Description: "My first Blnk transaction",
		},
		AllowOverdraft: true,
	})
	if err != nil {
		fmt.Printf("Error creating transaction: %v\n", err)
		return
	}

	fmt.Printf("Transaction ID: %s\n", transaction.TransactionID)
	fmt.Printf("Status: %s\n", transaction.Status)
	fmt.Printf("HTTP status: %d\n", resp.StatusCode)
}

Run the script:

bash

go run main.go

Your script prints the transaction ID when it succeeds. Verify the record with the CLI or in Blnk Cloud.

bash

blnk transactions list

Error handling

Every SDK method returns three values: the result, the HTTP response, and an error.

import "errors"

ledger, resp, err := client.Ledger.Create(body)
if err != nil {
    var apiErr *blnkgo.ApiErrorResponse
    if errors.As(err, &apiErr) {
        fmt.Printf("API error %d: %s\n", apiErr.Status, apiErr.Body)
    }
    return err
}
fmt.Printf("HTTP status: %d\n", resp.StatusCode)

When Blnk returns a 4xx or 5xx status, the SDK wraps the response in ApiErrorResponse. Use errors.As to read the status code and response body. On success, inspect resp.StatusCode for logging or metrics.

Using the SDK

Reference the Core documentation to understand how each API works. This section shows how those APIs are organized in the Go SDK.

Client structure

NewClient returns a client with one service per resource:

client.Ledger
client.LedgerBalance
client.Transaction
client.BalanceMonitor
client.Identity
client.Search
client.Reconciliation
client.Metadata

Call methods on the service that matches the resource you need. The endpoint map lists each method and links to its API reference page.

Building transaction requests

Call client.Transaction.Create and pass a blnkgo.CreateTransactionRequest struct. It has two parts:

ParentTransaction holds the core transaction fields: amount, currency, source, destination, reference, and metadata.
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.

blnkgo.CreateTransactionRequest{
    ParentTransaction: blnkgo.ParentTransaction{
        Amount:      1000,
        Precision:   100,
        Currency:    "USD",
        Source:      "bln_28f25ef6-2e0d-4fa6-891c-37fc409d654e",
        Destination: "bln_86ba7976-499d-4282-955e-a7c2abf5db12",
        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).

Client options

Pass optional settings to NewClient as functional options:

WithTimeout sets the HTTP timeout.
WithRetry sets how many times the client retries failed requests.
WithLogger attaches a custom logger.

apiKey := os.Getenv("BLNK_API_KEY")
client := blnkgo.NewClient(
    baseURL,
    &apiKey,
    blnkgo.WithTimeout(30*time.Second),
    blnkgo.WithRetry(3),
)

Endpoint map

Each SDK method calls a Blnk Core HTTP endpoint. Use this map to find the SDK method for an operation and open its reference page.

SDK method	API Reference
`client.Ledger.Create`	Create ledger
`client.Ledger.Get`	Get ledger
`client.Ledger.List`	Get ledger

ledger, resp, err := client.Ledger.Create(blnkgo.CreateLedgerRequest{
    Name: "Customer accounts",
})

SDK method	API Reference
`client.LedgerBalance.Create`	Create balance
`client.LedgerBalance.Get`	Get balance
`client.LedgerBalance.GetByIndicator`	Get balance by indicator
`client.LedgerBalance.GetHistorical`	Historical balances

balance, resp, err := client.LedgerBalance.Create(blnkgo.CreateLedgerBalanceRequest{
    LedgerID: "ldg_049495c6-356e-4ebc-a45e-60d1e1e16afb",
    Currency: "USD",
})

SDK method	API Reference
`client.Transaction.Create`	Create transaction
`client.Transaction.Get`	Get transaction
`client.Transaction.Update`	Update inflight
`client.Transaction.Refund`	Refund transaction

txn, resp, err := client.Transaction.Create(blnkgo.CreateTransactionRequest{
    ParentTransaction: blnkgo.ParentTransaction{
        Amount:      1000,
        Currency:    "USD",
        Source:      "@FundingPool",
        Destination: "@MyBalance",
    },
    AllowOverdraft: true,
})

SDK method	API Reference
`client.Reconciliation.Upload`	Upload data
`client.Reconciliation.CreateMatchingRule`	Create matching rule
`client.Reconciliation.Run`	Start reconciliation

file, _ := os.Open("statement.csv")
result, resp, err := client.Reconciliation.Upload("stripe", file, file.Name())

SDK method	API Reference
`client.Identity.Create`	Create identity
`client.Identity.Get`	Get identity
`client.Identity.List`	Get identity
`client.Identity.Update`	Edit identity

dob, _ := time.Parse(time.RFC3339, "1990-01-15T00:00:00Z")
identity, resp, err := client.Identity.Create(blnkgo.Identity{
    IdentityType: blnkgo.Individual,
    FirstName:    "Jane",
    LastName:     "Doe",
    Gender:       "female",
    Nationality:  "US",
    DOB:          &dob,
    EmailAddress: "jane@example.com",
    PhoneNumber:  "+1234567890",
    Category:     "customer",
    Street:       "123 Main St",
    City:         "New York",
    State:        "NY",
    Country:      "USA",
    PostCode:     "10001",
})

SDK method	API Reference
`client.Metadata.UpdateMetadata`	Update metadata

meta, resp, err := client.Metadata.UpdateMetadata(
    "bln_5ce86029-3c2e-4e2a-aae2-7fb931ca4c4f",
    blnkgo.UpdateMetaDataRequest{
        MetaData: map[string]interface{}{
            "tier": "gold",
        },
    },
)

Use Filter to query ledgers, balances, and transactions. It is the recommended way to search records from the SDK.

SDK method	API Reference
`client.Ledger.Filter(params)`	Search via DB
`client.LedgerBalance.Filter(params)`	Search via DB
`client.Transaction.Filter(params)`	Search via DB

results, resp, err := client.Ledger.Filter(blnkgo.FilterParams{
    Filters: []blnkgo.Filter{
        {Field: "name", Operator: blnkgo.OpILike, Value: "customer"},
    },
    Limit: 20,
})

Use SearchDocument for full-text search powered by Typesense.

SDK method	API Reference
`client.Search.SearchDocument(params, resource)`	Search via Typesense

Pass a ResourceType constant as the second argument to select the collection:

results, resp, err := client.Search.SearchDocument(
    blnkgo.SearchParams{Q: "payment", PerPage: 20},
    blnkgo.Transactions,
)

SDK method	API Reference
`client.BalanceMonitor.Create`	Create balance monitor
`client.BalanceMonitor.Get`	Get balance monitor
`client.BalanceMonitor.List`	Get balance monitor
`client.BalanceMonitor.Update`	Edit balance monitor

monitor, resp, err := client.BalanceMonitor.Create(blnkgo.MonitorData{
    BalanceID: "bln_5ce86029-3c2e-4e2a-aae2-7fb931ca4c4f",
    Condition: blnkgo.MonitorCondition{
        Field:     "credit_balance",
        Operator:  blnkgo.OperatorGreaterThan,
        Value:     1000,
        Precision: 100,
    },
})

Where to find examples

Go SDK examples

Escrow, savings, cards, and reconciliation.

Core tutorials

Step-by-step use case guides

Ledgers

Group and organize balances

Balances

Wallets, accounts, and stores of value

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 or join our Discord community.

Issue reporting and contributions

The Go SDK is open-source on GitHub, and we welcome community issues and pull requests. If you run into problems installing or using the SDK, report them on GitHub. If an endpoint is documented in the API reference but missing from the Go SDK, we encourage opening an issue or submitting a pull request to help improve SDK coverage.

​Quick start

Install Blnk

​Error handling

​Using the SDK

​Client structure

​Building transaction requests

​JSON field names

​Date and time fields

​Client options

​Endpoint map

​Where to find examples

Go SDK examples

Core tutorials

Ledgers

Balances

​Need help?

​Issue reporting and contributions

Quick start

Error handling

Using the SDK

Client structure

Building transaction requests

JSON field names

Date and time fields

Client options

Endpoint map

Where to find examples

Need help?

Issue reporting and contributions