SDKs and tools

There is no SDK you are required to use. The API is plain HTTP and JSON, and Authentication gives you a small client per language that every guide builds on. What follows is what exists if you would rather not write that yourself.

Go

go get github.com/walletd-io/walletd-go@v0.1.2

The first-party Go SDK, version v0.1.2. Its generated types describe the contract snapshot used for that release; they do not update when the service changes. These properties matter when integrating it:

• Problems decode into *walletd.Problem, and every problem matches two sentinels: its exact code and its status class. errors.Is(err, walletd.ErrInsufficientFunds) and errors.Is(err, walletd.ErrUnprocessable) both work, so a code added to the API later still matches the class you already branch on.
• Retries honour Retry-After on 429 and 503 with bounded backoff, and never retry any other 4xx. That is only safe because the idempotency key is stable across attempts.
• walletd.VerifySignature implements the webhook scheme in constant time over the raw bytes.
• Cursor pagination counts distinct cursor keys rather than rows, because the transaction listing pages by transaction while returning one row per entry. Count distinct transaction IDs when deciding whether another page may exist; a conversion can return multiple entries for one transaction. Keep page sizes in the documented range, 1–100.

Apache-2.0. It targets API 0.8.0; anything not yet wrapped is reachable over plain HTTP with the same credential. The release includes local HTTP tests; the deployment smoke suite has not yet been recorded as executed. Validate your deployment's authentication, retry and pagination flows before rollout.

Not every listing supports cursor traversal. Clients, tenant webhook events and user rewards expose a limit without a cursor; tenant webhook endpoints expose neither. Do not interpret a limited result as a complete export.

Response and webhook boundaries

Go SDK v0.1.2 retries interrupted response bodies only for GET/HEAD or keyed writes, preserving the original bytes and key. Exhausted read failures match ErrTransport; incompatible JSON is a decode error and is not retried. Redirects are refused even with a custom HTTP client; unexpected non-2xx statuses outside 4xx/5xx match ErrUnexpectedStatus. Configure the API host directly. These changes are included in v0.1.2. The release was installed in an independent module and tested against a disposable local sandbox; this does not establish production or partner-environment acceptance.

For webhooks, verify first, then use ParseEvent and the signed body’s (tenant_id, id) as the inbox identity. The HTTP event-ID header is advisory. Acknowledge after durable acceptance and commit local effects with the processed marker. See the receiver requirements.

Other languages

Generate a client from the contract rather than hand-writing one:

# Go
oapi-codegen -generate types,client -package walletd openapi.yaml > walletd.gen.go

# Python, TypeScript, PHP, Java and others
npx @openapitools/openapi-generator-cli generate -i openapi.yaml -g python -o ./walletd-python

A TypeScript SDK is planned. The guides show curl, Go, Python, PHP, JavaScript and Java for every money path in the meantime.

The OpenAPI documents

All three are OpenAPI 3.0.3. Follow each operation's security requirements: the wallet, staff-authentication and ledger-service credentials are not interchangeable, and some discovery/login routes are unauthenticated. See the API reference.

An API collection

/openapi/walletd.postman.json is a Postman v2.1 collection regenerated from the published wallet contract at developer time and committed with the site. It can lag the service until refreshed. It imports into Postman, Bruno and Insomnia. Set baseUrl and apiKey. Each keyed operation has its own idempotency_* collection variable: fill it with a saved logical-operation key before sending. Reuse that key and identical parameters when retrying; replace it only for a new operation. Postman's pre-request script skips missing or invalid keys. The collection never generates a key per send. Importers that discard Postman scripts leave the header empty: set Idempotency-Key manually using the same persistence rule. Postman's skip-request behavior is required for the automatic guard.

For coding agents

Authored English guides are published as raw markdown at the same path plus .md, indexed in /llms.txt and concatenated into /llms-full.txt. See AI and agent access for what agents most often get wrong about this API.