Client SDK

The client SDK lets your own program work with a Bitween's exchanges, as the Exchanges and Scheduled retries pages do: search them, read their files, follow their retry chains, retry one or many, and export their files. It comes for .NET (SimplyWorks.Bitween.Client on NuGet) and for JavaScript and TypeScript (@simplyworks/bitween-client on npm), with the same calls in each.

It calls the same API the admin UI calls, and answers with the same rows. Each release of Bitween from releases/r10.0 publishes both packages at Bitween's version; use the version of the Bitween you call, or an earlier one.

A service account#

The SDK signs in as a service account (Team > Service accounts in Bitween). Create one, give it a role, and issue it a token. The token, starting bwt_, is shown once.

The SDK trades the token for a session on its first call, and again whenever the session runs out or is refused, so the token is all you hand it.

Keep the token on your server. A browser app calls your own back end, and your back end calls Bitween: a token in browser code can be read by anyone using the page, and does all its role allows.

.NET#

dotnet add package SimplyWorks.Bitween.Client

It needs .NET 10.

using SW.Bitween.Client;

using var bitween = new BitweenClient("https://bitween.example.com", token);

var failed = await bitween.Exchanges.SearchAsync(new ExchangeQuery
{
    Status = ExchangeStatus.Failed,
    From = DateTimeOffset.UtcNow.AddDays(-1),
    PartnerIds = [7],
});

foreach (var exchange in failed.Result)
    Console.WriteLine($"{exchange.Id} {exchange.DocumentName}: {exchange.Exception}");

var first = failed.Result.FirstOrDefault();
if (first != null)
{
    var input = await bitween.Exchanges.ReadFileAsync(first.InputKey);
    var retryId = await bitween.Exchanges.RetryAsync(first.Id);
}

Keep one BitweenClient for the life of the program, as a singleton in dependency injection: it can be used from many threads at once, and they share one session. To send through an HttpClient of your own, pass it with the Bitween's address as its BaseAddress: new BitweenClient(httpClient, token).

The rows and plans are the API's own types, from SimplyWorks.Bitween.Sdk, in SW.Bitween.Model: XchangeRow, XchangeRetryTree, XchangeBulkRetryPlan, XchangeFilesExportCheck and DelayedRetryRow.

JavaScript and TypeScript#

npm install @simplyworks/bitween-client

It needs Node 22 or later, and has no dependencies.

const { BitweenClient } = require("@simplyworks/bitween-client");

const bitween = new BitweenClient({ url: "https://bitween.example.com", token: process.env.BITWEEN_TOKEN });

const failed = await bitween.exchanges.search({ status: "failed", from: new Date(Date.now() - 86400e3), partnerIds: [7] });
const [first] = failed.result;
if (first) {
  const input = await bitween.exchanges.readFile(first.inputKey);
  const retryId = await bitween.exchanges.retry(first.id);
}

Types come with it. Rows have the API's camelCase names, and times are ISO strings.

What it does#

Queries#

A query filters the way the Exchanges page does. What is left unset matches any; everything set has to hold.

A scheduled retry query takes SubscriptionId, InformationTypeId, ErrorContains, and From and To for when it is due.

Selections#

Bulk retry and export take a selection: exchanges by id, or every exchange a query matches, however many pages that is, with some left out. A query with an empty list of ids, partners, subscriptions or information types is refused: an empty list adds no filter, so it would widen the selection rather than narrow it.

ExchangeSelection.Of(["a1b2...", "c3d4..."])
ExchangeSelection.Matching(new ExchangeQuery { Status = ExchangeStatus.Failed, PartnerIds = [7] }, except: ["a1b2..."])

{ ids: ["a1b2...", "c3d4..."] }
{ matching: { status: "failed", partnerIds: [7] }, except: ["a1b2..."] }

A bulk retry retries each chain once, from its newest attempt, and skips what succeeded or has an automatic retry booked, saying why. It carries out at most 500 at a time: past that the plan comes back with overLimit set and nothing done. To retry more, take targets from the preview, which plans up to 500,000, and retry them by id, 500 at a time. An export takes at most 500 exchanges.

Errors#

A refusal throws BitweenClientException in .NET and BitweenClientError in JavaScript. Both carry the HTTP status, Bitween's reasons by code, and the first code alone.