> ## 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. # Getting Started with the Go SDK > Install the Blnk Go SDK, run your first transaction, and find the Core docs for every SDK method. The [Blnk Go SDK](https://github.com/blnkfinance/blnk-go) 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](/ledgers/introduction). *** ## 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. You need a running Blnk Core instance before using the SDK. Local install or Blnk Cloud Create a Go project and install the SDK. You need [Go 1.22 or later](https://go.dev/doc/install). ```bash bash wrap theme={"system"} go mod init blnk-quickstart go get github.com/blnkfinance/blnk-go ``` 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. ```go client.go wrap theme={"system"} baseURL, _ := url.Parse("http://localhost:5001/") apiKey := "your_api_key" client := blnkgo.NewClient( baseURL, &apiKey, blnkgo.WithTimeout(10*time.Second), blnkgo.WithRetry(2), ) ``` Create `main.go`, paste the script below, and run it: ```go main.go wrap expandable theme={"system"} 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 bash wrap theme={"system"} go run main.go ``` Your script prints the transaction ID when it succeeds. Verify the record with the CLI or in Blnk Cloud. ```bash bash wrap theme={"system"} blnk transactions list ``` *** ## Error handling Every SDK method returns three values: the result, the HTTP response, and an error. ```go wrap theme={"system"} 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](#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: 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 wrap theme={"system"} 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: 1. `WithTimeout` sets the HTTP timeout. 2. `WithRetry` sets how many times the client retries failed requests. 3. `WithLogger` attaches a custom logger. ```go wrap theme={"system"} 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](/reference/create-ledger) | | `client.Ledger.Get` | [Get ledger](/reference/get-ledger) | | `client.Ledger.List` | [Get ledger](/reference/get-ledger) | ```go Create wrap theme={"system"} ledger, resp, err := client.Ledger.Create(blnkgo.CreateLedgerRequest{ Name: "Customer accounts", }) ``` ```go Get wrap theme={"system"} ledger, resp, err := client.Ledger.Get("ldg_049495c6-356e-4ebc-a45e-60d1e1e16afb") ``` ```go List wrap theme={"system"} ledgers, resp, err := client.Ledger.List() ``` | SDK method | API Reference | | ------------------------------------- | --------------------------------------------------------------- | | `client.LedgerBalance.Create` | [Create balance](/reference/create-balance) | | `client.LedgerBalance.Get` | [Get balance](/reference/get-balance) | | `client.LedgerBalance.GetByIndicator` | [Get balance by indicator](/reference/get-balance-by-indicator) | | `client.LedgerBalance.GetHistorical` | [Historical balances](/reference/historical-balances) | ```go Create wrap theme={"system"} balance, resp, err := client.LedgerBalance.Create(blnkgo.CreateLedgerBalanceRequest{ LedgerID: "ldg_049495c6-356e-4ebc-a45e-60d1e1e16afb", Currency: "USD", }) ``` ```go Get wrap theme={"system"} balance, resp, err := client.LedgerBalance.Get("bln_5ce86029-3c2e-4e2a-aae2-7fb931ca4c4f") ``` ```go GetByIndicator wrap theme={"system"} balance, resp, err := client.LedgerBalance.GetByIndicator("@FundingPool", "USD") ``` ```go GetHistorical wrap theme={"system"} at, _ := time.Parse(time.RFC3339, "2024-04-22T15:28:03Z") balance, resp, err := client.LedgerBalance.GetHistorical( "bln_5ce86029-3c2e-4e2a-aae2-7fb931ca4c4f", at, false, ) ``` | SDK method | API Reference | | --------------------------- | --------------------------------------------------- | | `client.Transaction.Create` | [Create transaction](/reference/create-transaction) | | `client.Transaction.Get` | [Get transaction](/reference/get-transaction) | | `client.Transaction.Update` | [Update inflight](/reference/update-inflight) | | `client.Transaction.Refund` | [Refund transaction](/reference/refund-transaction) | ```go Create wrap theme={"system"} txn, resp, err := client.Transaction.Create(blnkgo.CreateTransactionRequest{ ParentTransaction: blnkgo.ParentTransaction{ Amount: 1000, Currency: "USD", Source: "@FundingPool", Destination: "@MyBalance", }, AllowOverdraft: true, }) ``` ```go Get wrap theme={"system"} txn, resp, err := client.Transaction.Get("txn_14706192-e53d-43cc-86a1-b8807a09b351") ``` ```go Update wrap theme={"system"} txn, resp, err := client.Transaction.Update("txn_14706192-e53d-43cc-86a1-b8807a09b351", blnkgo.UpdateStatus{ Status: blnkgo.InflightStatusCommit, }) ``` ```go Refund wrap theme={"system"} txn, resp, err := client.Transaction.Refund("txn_14706192-e53d-43cc-86a1-b8807a09b351") ``` | SDK method | API Reference | | ------------------------------------------ | ------------------------------------------------------- | | `client.Reconciliation.Upload` | [Upload data](/reference/upload-data) | | `client.Reconciliation.CreateMatchingRule` | [Create matching rule](/reference/create-matching-rule) | | `client.Reconciliation.Run` | [Start reconciliation](/reference/start-reconciliation) | ```go Upload wrap theme={"system"} file, _ := os.Open("statement.csv") result, resp, err := client.Reconciliation.Upload("stripe", file, file.Name()) ``` ```go CreateMatchingRule wrap theme={"system"} rule, resp, err := client.Reconciliation.CreateMatchingRule(blnkgo.Matcher{ Name: "Amount match", Description: "Match by amount", Criteria: []blnkgo.Criteria{ { Field: blnkgo.CriteriaFieldAmount, Operator: blnkgo.ReconciliationOperatorEquals, }, }, }) ``` ```go Run wrap theme={"system"} result, resp, err := client.Reconciliation.Run(blnkgo.RunReconData{ UploadID: "upl_f3a8b2c1-9d4e-4a7b-8c6e-1f2d3e4a5b6c", Strategy: blnkgo.ReconciliationStrategyOneToOne, }) ``` | SDK method | API Reference | | ------------------------ | --------------------------------------------- | | `client.Identity.Create` | [Create identity](/reference/create-identity) | | `client.Identity.Get` | [Get identity](/reference/get-identity) | | `client.Identity.List` | [Get identity](/reference/get-identity) | | `client.Identity.Update` | [Edit identity](/reference/edit-identity) | ```go Create wrap expandable theme={"system"} 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", }) ``` ```go Get wrap theme={"system"} identity, resp, err := client.Identity.Get("idt_8cc22560-5ace-4989-8953-fcbad7947d48") ``` ```go List wrap theme={"system"} identities, resp, err := client.Identity.List() ``` ```go Update wrap theme={"system"} identity, resp, err := client.Identity.Update("idt_8cc22560-5ace-4989-8953-fcbad7947d48", &blnkgo.Identity{ FirstName: "Jane", LastName: "Smith", }) ``` | SDK method | API Reference | | -------------------------------- | --------------------------------------------- | | `client.Metadata.UpdateMetadata` | [Update metadata](/reference/update-metadata) | ```go UpdateMetadata wrap theme={"system"} 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](/reference/search-db) | | `client.LedgerBalance.Filter(params)` | [Search via DB](/reference/search-db) | | `client.Transaction.Filter(params)` | [Search via DB](/reference/search-db) | ```go Ledger.Filter wrap theme={"system"} results, resp, err := client.Ledger.Filter(blnkgo.FilterParams{ Filters: []blnkgo.Filter{ {Field: "name", Operator: blnkgo.OpILike, Value: "customer"}, }, Limit: 20, }) ``` ```go LedgerBalance.Filter wrap theme={"system"} results, resp, err := client.LedgerBalance.Filter(blnkgo.FilterParams{ Filters: []blnkgo.Filter{ {Field: "currency", Operator: blnkgo.OpEqual, Value: "USD"}, }, SortBy: "created_at", SortOrder: "desc", }) ``` ```go Transaction.Filter wrap theme={"system"} results, resp, err := client.Transaction.Filter(blnkgo.FilterParams{ Filters: []blnkgo.Filter{ {Field: "status", Operator: blnkgo.OpEqual, Value: "APPLIED"}, }, Limit: 20, }) ``` Use `SearchDocument` for full-text search powered by Typesense. | SDK method | API Reference | | ------------------------------------------------ | --------------------------------------------------- | | `client.Search.SearchDocument(params, resource)` | [Search via Typesense](/reference/search-typesense) | Pass a `ResourceType` constant as the second argument to select the collection: ```go Transactions wrap theme={"system"} results, resp, err := client.Search.SearchDocument( blnkgo.SearchParams{Q: "payment", PerPage: 20}, blnkgo.Transactions, ) ``` ```go Balances wrap theme={"system"} results, resp, err := client.Search.SearchDocument( blnkgo.SearchParams{Q: "USD", PerPage: 20}, blnkgo.Balances, ) ``` ```go Ledgers wrap theme={"system"} results, resp, err := client.Search.SearchDocument( blnkgo.SearchParams{Q: "customer", PerPage: 20}, blnkgo.Ledgers, ) ``` | SDK method | API Reference | | ------------------------------ | ----------------------------------------------------------- | | `client.BalanceMonitor.Create` | [Create balance monitor](/reference/create-balance-monitor) | | `client.BalanceMonitor.Get` | [Get balance monitor](/reference/get-balance-monitor) | | `client.BalanceMonitor.List` | [Get balance monitor](/reference/get-balance-monitor) | | `client.BalanceMonitor.Update` | [Edit balance monitor](/reference/edit-balance-monitor) | ```go Create wrap theme={"system"} 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, }, }) ``` ```go Get wrap theme={"system"} monitor, resp, err := client.BalanceMonitor.Get("mon_e0e77b0c-4985-472a-9bf5-76a48b0259b0") ``` ```go List wrap theme={"system"} monitors, resp, err := client.BalanceMonitor.List() ``` ```go Update wrap theme={"system"} monitor, resp, err := client.BalanceMonitor.Update("mon_e0e77b0c-4985-472a-9bf5-76a48b0259b0", blnkgo.MonitorData{ Condition: blnkgo.MonitorCondition{ Field: "credit_balance", Operator: blnkgo.OperatorLessThan, Value: 500, }, }) ``` *** ## Where to find examples Escrow, savings, cards, and reconciliation. Step-by-step use case guides Group and organize 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](mailto:support@blnkfinance.com) or [join our Discord community](https://discord.gg/7WNv94zPpx). **Connect your ledger to Blnk Cloud** 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. *** ## Issue reporting and contributions The Go SDK is [open-source on GitHub](https://github.com/blnkfinance/blnk-go), and we welcome community issues and pull requests. If you run into problems installing or using the SDK, [report them on GitHub](https://github.com/blnkfinance/blnk-go/issues). If an endpoint is documented in the [API reference](/reference/create-ledger) but missing from the Go SDK, we encourage opening an issue or submitting a pull request to help improve SDK coverage.