Go client

go get sotirea.com/sdk/go

The package is sotirea. It needs Go 1.22 or later and nothing beyond the standard library. Its types and methods are generated from the same Go types as the API itself, so they always match what the API serves. The source is on GitHub under the MIT licence.

A client

import sotirea "sotirea.com/sdk/go"

client := sotirea.New(os.Getenv("SOTIREA_API"), os.Getenv("SOTIREA_API_KEY"))

A Client is safe to share between goroutines: make one and reuse it. Each request waits at most 30 seconds; pass your own http.Client for other timeouts, a proxy or tracing:

client := sotirea.New(api, key,
  sotirea.WithHTTPClient(&http.Client{Timeout: 10 * time.Second}),
  sotirea.WithUserAgent("payouts-service/2.4"),
)

Keep the key on your server. See authentication.

Calling the API

There is one method per operation, named for what it does, and every one takes a Context first:

Operation	Method
Who this key is	GetMe(ctx)
Open a vault	CreateVault(ctx, VaultRequest{...})
Balances	ListBalances(ctx, ListBalancesParams{...})
Quote a payment	QuotePayment(ctx, PaymentRequest{...})
Pay out	SendPayment(ctx, idempotencyKey, PaymentRequest{...})
One payment	GetPayment(ctx, id)

and so on for every operation in the API reference. A single answer comes with a Meta whose RequestID is the one to quote when asking about the request:

payment, meta, err := client.SendPayment(ctx, "payout-42", pay)

A list answers a Page[T], with Items, Page, PageSize, Total, TotalPages, HasNext and its own RequestID. Ask for the next with the list’s params, such as ListDepositsParams{Vault: 7, Page: 2}. A zero field in params is not sent.

Amounts are strings of the asset’s smallest unit, never floats: see deposits and finality.

Refusals

A refusal is an *sotirea.Error with Status, Code, Message, Rule() and RequestID. The codes are constants, sotirea.CodeConflict and so on, and sotirea.IsCode(err, code) tests for one:

var refusal *sotirea.Error
if errors.As(err, &refusal) && refusal.Rule() == "new_destination" {
  // approve the address first
}

Handle refusals has a fuller example, and errors and refusals lists every rule.

Webhooks

sotirea.VerifyWebhook(secret, r.Header, body) checks a delivery and answers its Event, whose Payment(), Deposit() and GasPool() read its data by type. Event names are constants such as sotirea.EventDepositReceived. See verify webhooks.

Versions

The client follows the API’s version 1: a new minor version adds fields, operations and values, and never removes or changes one. See the changelog.