Wallets

Tu Wallet guarda el balance en USDR que financia cada orden que creas. getMyWallet lee su balance actual y getMyWalletTransactions recorre su historial de transacciones. Ambos son de alcance por token — no hay un id de wallet ni un owner que pasar, las credenciales autenticadas ya identifican la única wallet de tu compañía.

getMyWallet(currency)

Lee la wallet de la compañía autenticada.

Firma

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

Parámetros

Nombre	Tipo	Obligatorio	Descripción
currency	string	No	Default "USDR". Se valida su forma como 3-5 letras mayúsculas; todavía no es un selector — hoy una organización tiene exactamente una wallet, así que cualquier valor bien formado la devuelve.

Retorno

MyWallet:

Campo	Tipo	Significado
status	string	Estado de la wallet.
currency	string	Moneda de la wallet.
amount	string	Balance de la wallet, como string decimal.

Ejemplo

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);

Errores

Del lado del cliente (RetornaSdkError):

• currency definido pero no son 3-5 letras mayúsculas.

Desde la API (RetornaB2BError, consulta el catálogo de errores):

• B2B_UNAUTHORIZED — credenciales, token o firma rechazados.
• B2B_COMPANY_NOT_FOUND — no hay ninguna compañía asociada a las credenciales usadas.
• B2B_WALLET_NOT_CONFIGURED — tu compañía todavía no tiene una wallet provisionada.
• B2B_WALLET_NOT_FOUND — la wallet configurada no existe del lado del proveedor.

Notas

• No hay ownerId ni id de wallet que pasar — el token ya lo limita a tu compañía.
• currency se valida en su forma, pero todavía no es significativo como selector; trata getMyWallet() sin argumentos como la llamada para tu balance hoy.

Referencia de API

GET /me/wallets/{currency}

getMyWalletTransactions(type, params, currency)

Recorre el historial de transacciones de la wallet para un tipo de transacción dado.

Firma

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

Parámetros

Nombre	Tipo	Obligatorio	Descripción
type	"top_up"	Sí	El listado a leer. "top_up" es el único valor publicado hoy y devuelve todo lo que acredita la wallet: depósitos on-chain y créditos registrados por tesorería.
params.cursor	string	No	Cursor opaco del pagination.next_cursor de una página anterior. Omítelo para la primera página.
params.limit	number	No	Tamaño de página, 1-100. Queda fijo durante todo el recorrido una vez que pasas un cursor.
currency	string	No	Default "USDR". Misma validación de forma que getMyWallet.

Retorno

WalletTransactionsResponse:

Campo	Tipo	Significado
data[].id	string	Id de la transacción.
data[].external_id	string	Referencia del lado del cliente para la transacción.
data[].type	string	Tipo de transacción en minúsculas: "top_up" para un depósito on-chain, "b2b_manual_credit" para un crédito registrado por tesorería.
data[].amount	string	Monto de la transacción, como string decimal con dos decimales (ej. "20.00").
data[].currency	string	Moneda de la transacción.
data[].created_at	string	Timestamp ISO 8601.
data[].status	"PENDING" | "COMPLETED" (opcional)	Siempre "COMPLETED" en un b2b_manual_credit: tesorería lo asienta directamente en el balance, no queda nada por liquidar. En un top_up on-chain solo está presente cuando se informó un estado de liquidación.
pagination.next_cursor	string | null	Token opaco de la próxima página; null cuando termina el recorrido.
pagination.has_more	boolean	Misma condición de fin de lista que un next_cursor nulo.
pagination.limit	number	Tamaño de página efectivo del recorrido.
pagination.total	number | null	Total del dataset filtrado, o null cuando no se conoce.

Ejemplo

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);

Errores

Del lado del cliente (RetornaSdkError):

• type vacío, currency definido pero no son 3-5 letras mayúsculas, o params.limit definido pero no es un entero entre 1 y 100.

Desde la API (RetornaB2BError):

• B2B_UNAUTHORIZED — credenciales, token o firma rechazados.
• B2B_COMPANY_NOT_FOUND — no hay ninguna compañía asociada a las credenciales usadas.
• B2B_WALLET_NOT_CONFIGURED / B2B_WALLET_NOT_FOUND — igual que en getMyWallet.
• B2B_INVALID_PAGINATION_CURSOR — el cursor no se pudo decodificar, o no lo emitió este listado.

Notas

• Mismas reglas de cursor que el listado de órdenes — consulta paginación para el detalle completo, incluyendo por qué un ?cursor= vacío es inválido y no "empezar de nuevo".
• status nunca toma un valor por default cuando el estado de liquidación upstream de un top_up es desconocido — se omite, no se adivina. Un b2b_manual_credit es la única fila que siempre trae "COMPLETED", porque su tipo por sí solo prueba que los fondos están acreditados.

Referencia de API

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