Wallets

Your company funds every payout from a single wallet. WalletsClient covers reading the current balance and walking the transaction history.

The currency path segment does not select between multiple wallets — a company has exactly one — so the backend validates its shape and then ignores it. Pass the currency your wallet is actually denominated in anyway; a malformed value is still rejected.

Reach these methods either directly on RetornaClient or through client.wallets() — both call the same code.

getMyWallet(currency)

Reads the authenticated company's wallet: its status and current balance.

Signature

public MyWallet getMyWallet(String currency)

Parameters

Name	Type	Required	Description
currency	String	Yes	3 to 5 uppercase letters, e.g. USDR. Shape-checked client-side before the call goes out.

Returns

MyWallet:

Accessor	Type	Meaning
status()	String	Wallet status.
currency()	String	Wallet currency.
amount()	String	Current balance, decimal string — parse with BigDecimal, never double.

Example

import app.retorna.sdk.RetornaClient;
import app.retorna.sdk.RetornaClientBuilder;
import app.retorna.sdk.core.environment.RetornaEnvironment;
import app.retorna.sdk.models.wallet.MyWallet;

RetornaClient client = new RetornaClientBuilder()
        .environment(RetornaEnvironment.SANDBOX)
        .clientId(System.getenv("RETORNA_CLIENT_ID"))
        .clientSecret(System.getenv("RETORNA_CLIENT_SECRET"))
        .privateKey(System.getenv("RETORNA_PRIVATE_KEY"))
        .buildClient();

MyWallet wallet = client.getMyWallet("USDR");
System.out.printf("Balance: %s %s (status=%s)%n",
        wallet.amount(), wallet.currency(), wallet.status());

Errors

• IllegalArgumentException — currency is null or does not match 3-to-5 uppercase letters.
• RetornaB2BException with codeEnum() one of: B2B_WALLET_NOT_CONFIGURED — no wallet provisioned yet, B2B_WALLET_NOT_FOUND, B2B_UNAUTHORIZED, B2B_COMPANY_NOT_FOUND, B2B_RATE_LIMITED — retryable, B2B_UNKNOWN.
• RetornaAuthException — token exchange failure.
• RetornaSdkException — network failure or deserialization failure.

Notes

• Amounts are decimal strings, not floating point. Parse them with BigDecimal.
• Do not read anything into the specific currency you pass — the backend does not route on it.

API reference

GET /me/wallets/:currency

getMyWalletTransactions(currency, type, params)

Walks the wallet's transaction history, cursor-paginated.

Signature

public WalletTransactionsResponse getMyWalletTransactions(
    String currency,
    WalletTransactionType type,
    ListWalletTransactionsParams params
)

Parameters

Name	Type	Required	Description
currency	String	Yes	Same shape rule as getMyWallet.
type	WalletTransactionType	Yes	The listing to read. Today the SDK exposes TOP_UP (wire value "top_up"), which returns every credit to the wallet: on-chain deposits and credits booked by treasury.
params	ListWalletTransactionsParams	No (pass null or firstPage())	cursor (String, opaque, null for the first page) and limit (Integer, 1..100, backend default 10). Keep limit fixed across a walk.

Convenience factories: ListWalletTransactionsParams.firstPage() and firstPage(int limit).

Returns

WalletTransactionsResponse:

Accessor	Type	Meaning
pagination()	CursorPagination	nextCursor() (nullable when done), hasMore(), limit(), total() (nullable).
data()	List<WalletTransaction>	Transactions on this page.

Each WalletTransaction:

Accessor	Type	Meaning
id()	String	Transaction id.
externalId()	String	Client-side reference, where applicable; nullable.
type()	String	Lowercase wire form: "top_up" for an on-chain deposit, "b2b_manual_credit" for a credit booked by treasury. Kept as a string so a new type does not break deserialization; compare against WalletTransactionType.TOP_UP.wire().
amount() / currency()	String	Transaction amount (decimal string with two decimals, e.g. "20.00") and currency.
createdAt()	OffsetDateTime	Creation timestamp.
status()	String	PENDING or COMPLETED, or null when the funding provider reported nothing publishable for an on-chain top-up. A b2b_manual_credit is always COMPLETED. The listing includes top-ups that are not credited yet — check this before treating an amount as available balance.

Example

import app.retorna.sdk.RetornaClient;
import app.retorna.sdk.RetornaClientBuilder;
import app.retorna.sdk.core.environment.RetornaEnvironment;
import app.retorna.sdk.models.wallet.ListWalletTransactionsParams;
import app.retorna.sdk.models.wallet.WalletTransaction;
import app.retorna.sdk.models.wallet.WalletTransactionType;
import app.retorna.sdk.models.wallet.WalletTransactionsResponse;

RetornaClient client = new RetornaClientBuilder()
        .environment(RetornaEnvironment.SANDBOX)
        .clientId(System.getenv("RETORNA_CLIENT_ID"))
        .clientSecret(System.getenv("RETORNA_CLIENT_SECRET"))
        .privateKey(System.getenv("RETORNA_PRIVATE_KEY"))
        .buildClient();

String cursor = null;
do {
    WalletTransactionsResponse page = client.getMyWalletTransactions(
            "USDR",
            WalletTransactionType.TOP_UP,
            new ListWalletTransactionsParams(cursor, 50));

    for (WalletTransaction tx : page.data()) {
        System.out.printf("%s %s %s %s%n",
                tx.createdAt(), tx.amount(), tx.currency(), tx.status());
    }
    cursor = page.pagination().nextCursor();
} while (cursor != null);

Errors

• IllegalArgumentException — malformed currency, null type, an empty (but non-null) cursor, or a limit outside 1..100.
• RetornaB2BException with codeEnum() one of: B2B_WALLET_NOT_CONFIGURED, B2B_WALLET_NOT_FOUND, B2B_INVALID_PAGINATION_CURSOR, B2B_UNAUTHORIZED, B2B_RATE_LIMITED — retryable, B2B_UNKNOWN.
• RetornaAuthException — token exchange failure.
• RetornaSdkException — network failure or deserialization failure.

Notes

• This listing moved from offset to cursor pagination — sending an offset-style page parameter is not supported and returns 400.
• Keep limit fixed for the whole walk, same rule as listing orders.

API reference

GET /me/wallets/:currency/transactions/:type