Wallets

Your Wallet holds the USDR balance that funds every order you create. getMyWallet reads its current balance and getMyWalletTransactions walks its transaction history. Both are token-scoped — there is no wallet id or owner to pass, the authenticated credentials already identify your company's one wallet.

getMyWallet(currency)

Reads the authenticated company's wallet.

Signature

getMyWallet(currency?: string): Promise<MyWallet>

Parameters

Name	Type	Required	Description
currency	string	No	Defaults to "USDR". Shape-checked as 3-5 uppercase letters; not yet a selector — an organization holds exactly one wallet today, so any well-formed value returns it.

Returns

MyWallet:

Field	Type	Meaning
status	string	Wallet status.
currency	string	Wallet currency.
amount	string	Wallet balance, as a decimal string.

Example

import {
  RetornaClientBuilder,
  RetornaEnvironment,
} from "@retorna-tech/retorna-gateway-sdk";

const client = new RetornaClientBuilder()
  .environment(RetornaEnvironment.SANDBOX)
  .clientId(process.env.RETORNA_CLIENT_ID!)
  .clientSecret(process.env.RETORNA_CLIENT_SECRET!)
  .privateKey(process.env.RETORNA_PRIVATE_KEY!)
  .buildClient();

const wallet = await client.getMyWallet(); // defaults to "USDR"
console.log(wallet.amount, wallet.currency, wallet.status);

Errors

Client-side (RetornaSdkError):

• currency set but not 3-5 uppercase letters.

From the API (RetornaB2BError, see the error catalog):

• B2B_UNAUTHORIZED — credentials, token, or signature rejected.
• B2B_COMPANY_NOT_FOUND — no company is associated with the credentials used.
• B2B_WALLET_NOT_CONFIGURED — your company has no wallet provisioned yet.
• B2B_WALLET_NOT_FOUND — the configured wallet does not exist upstream.

Notes

• There is no ownerId or wallet id to pass — the token already scopes it to your company.
• currency is shape-checked, not yet meaningful as a selector; treat getMyWallet() with no arguments as the call for your balance today.

API reference

GET /me/wallets/{currency}

getMyWalletTransactions(type, params, currency)

Walks the wallet's transaction history for a given transaction type.

Signature

getMyWalletTransactions(
  type: WalletTransactionType,
  params?: ListWalletTransactionsParams,
  currency?: string
): Promise<WalletTransactionsResponse>

Parameters

Name	Type	Required	Description
type	"top_up"	Yes	The listing to read. "top_up" is the only value published today and returns every credit to the wallet: on-chain deposits and credits booked by treasury.
params.cursor	string	No	Opaque cursor from a previous page's pagination.next_cursor. Omit for the first page.
params.limit	number	No	Page size, 1-100. Fixed for the whole walk once you pass a cursor.
currency	string	No	Defaults to "USDR". Same shape-check as getMyWallet.

Returns

WalletTransactionsResponse:

Field	Type	Meaning
data[].id	string	Transaction id.
data[].external_id	string	Client-side reference for the transaction.
data[].type	string	Lowercase transaction type: "top_up" for an on-chain deposit, "b2b_manual_credit" for a credit booked by treasury.
data[].amount	string	Transaction amount, as a decimal string with two decimals (e.g. "20.00").
data[].currency	string	Transaction currency.
data[].created_at	string	ISO 8601 timestamp.
data[].status	"PENDING" | "COMPLETED" (optional)	Always "COMPLETED" on a b2b_manual_credit: treasury books it straight into the balance, there is nothing left to settle. On an on-chain top_up it is present only when a settlement status was reported upstream.
pagination.next_cursor	string | null	Opaque next-page token; null once the walk is finished.
pagination.has_more	boolean	Same end-of-list condition as a null next_cursor.
pagination.limit	number	Effective page size of the walk.
pagination.total	number | null	Total of the filtered dataset, or null when unknown.

Example

let cursor: string | undefined;

do {
  const page = await client.getMyWalletTransactions("top_up", { cursor, limit: 50 });

  for (const tx of page.data) {
    console.log(tx.id, tx.external_id, tx.amount, tx.currency, tx.status, tx.created_at);
  }

  cursor = page.pagination.next_cursor ?? undefined;
} while (cursor);

Errors

Client-side (RetornaSdkError):

• type empty, currency set but not 3-5 uppercase letters, or params.limit set but not an integer between 1 and 100.

From the API (RetornaB2BError):

• B2B_UNAUTHORIZED — credentials, token, or signature rejected.
• B2B_COMPANY_NOT_FOUND — no company is associated with the credentials used.
• B2B_WALLET_NOT_CONFIGURED / B2B_WALLET_NOT_FOUND — same as getMyWallet.
• B2B_INVALID_PAGINATION_CURSOR — the cursor could not be decoded, or was not issued by this listing.

Notes

• Same cursor rules as order listings — see pagination for the full details, including why an empty ?cursor= is invalid rather than "start over."
• status never defaults when the upstream settlement status of a top_up is unknown — absent, not guessed. A b2b_manual_credit is the one row that always carries "COMPLETED", because its type alone proves the funds are credited.

API reference

GET /me/wallets/{currency}/transactions/{type}