Wallet

Introduction

The wallet home sections, which provide users with an overview of their wallet functionalities and quick access to essential features.

Wallet Home Structure - Include the cardboard with the balance, and the tabs: Transactions, Send, Receive & Pay.

Wallet Balance

Endpoint: GET /v1/financial/balance

Description: Retrieves current wallet balance across different balance types including promotional, platform, and blockchain balances.

Query Parameters

Parameter	Type	Required	Description
`forced`	boolean	No	Forces balance refresh from blockchain (only used upon refresh)

Response Interface

export interface WalletBalance {
    // User's wallet balance details
    balance: Balance;
}

export interface Balance {
    // Promotional balance from marketing campaigns
    promotional?: string;
    // Main platform balance (primary currency)
    plataform: string;
    // Balance on internal blockchain network
    internalBlockchain?: string;
    // Balance on external blockchain networks
    externalBlockchain?: string;
}

Quotation

Endpoint: GET /v1/quotations

Description: Retrieves the current quotation in USD and BRL

Response Interface

export interface CoinQuotation
{
    amount: string;
    currency: string;
    rate: string;
    tax: string;

    quotations: Record<string, Quotation>;
}

export interface Quotation
{
    wibxReferenceAmount: number;
    wibxValue: number;
}

Example Response

{
    "quotations": {
        "USD": {
            "wibxReferenceAmount": 1,
            "wibxValue": 0.00214821
        },
        "BRL": {
            "wibxReferenceAmount": 1,
            "wibxValue": 0.011410002594
        }
    }
}

Wallet Transactions

Endpoint: GET /v2/finance/transactions

Description: Retrieves all the wallet transactions made by the user

Query Parameters

Parameter	Type	Required	Description
`limit`	number	No	Number of results per page
`offset`	number	No	Number of results to skip
`flow`	TransactionType	No	Filter by transaction flow type
`type`	string	No	Filter by transaction type (e.g., ‘withdraw’)
`forced`	boolean	No	Forces balance refresh from blockchain

Response Interface

export interface Transactions
{
    userEmail: string;
    userId: string;
    userName: string;
    transactionsSummary: TransactionsSummary;
    transactionsEntries: Array<TransactionsEntry>;
    globalTraceId: string;
}

export interface TransactionsSummary
{
    totalCreditsAmount: string;
    totalDebitsAmount: string;
}

export interface TransactionsEntry
{
    when: Date;
    transactionFlow: TransactionType;
    totalAmount: string;
    from: string;
    to: string;
    monetaryAmount: MonetaryAmount;
    financialTransactionId?: string;
    hasDetails?: boolean;
    details?: Details;
    simplifiedType?: SimplifiedType;
}

export enum TransactionType
{
    ALL = 'all',
    CREDIT = 'credit',
    DEBIT = 'debit',
    WITHDRAW = 'withdraw',
    TAX = 'tax',
    REVERSAL ='reversal',
    PAYMENT = 'payment',
    EARNS = 'earns'
}

export interface MonetaryAmount
{
    principalAmount: string;
    taxAmount: string;
}

export interface Details
{
    step: string;
    walletTo: string;
    walletFrom: string;
    hash: string;
}

export enum SimplifiedType
{
    TRANSFER = 'transfer',
    WITHDRAW = 'withdraw',
}

Example Response

{
    "userEmail": "test1234@wibx.io",
    "userId": "c0c288a4-77c4-41c4-b122-e101132507c4",
    "userName": "Test User",
    "transactionsSummary": {
        "totalCreditsAmount": "1234.3061",
        "totalDebitsAmount": "124.4651"
    },
    "transactionsEntries": [
        {
            "when": "2025-12-01T17:43:06.128Z",
            "transactionFlow": "credit",
            "totalAmount": "10.0000",
            "from": "Desafio Share",
            "to": "myself",
            "financialTransactionId": "019adb02-d0eb-7305-9e97-73ee9e28c2b0",
            "monetaryAmount": {
                "principalAmount": "10.0000",
                "taxAmount": "0.0000",
                "totalAmount": "10.0000"
            },
            "hasDetails": false,
            "transactionType": "earns",
            "simplifiedType": "transfer"
        }
    ],
    "globalTraceId": "370d9e1f75ae327432d9f3a3b1ee8510a"
}

Transfer

The transfer section allows users to transfer WIBX from one wallet to another. This section is divided into two endpoints:

Verify Transfer

Endpoint: POST /v1/financial/verify

Description: Verifies if the transfer is possible, checking if the user has enough balance and if the transfer is allowed. It also returns the transaction fees if applicable.

Possible errors:

400 - Bad Request - Users not allowed to transfer between whitelabels.

Request Interface

export interface VerifyTransfer
{
    walletIdTo: string;
    amount: number;
}

Example Request

{
    "walletIdTo": "0x1c81DaCE9685E2CF55a865AE1bB7606Cf9E236f6",
    "amount": 10
}

Response Interface

export interface VerifyTransferOutput
{
    tax: Array<TaxItem>;
    calculatedTax: string;
    willBeApproved: boolean;
    walletFrom: WalletFrom;
    walletTo: WalletTo;
    message: string;
    amount: number;
}

export interface TaxItem
{
    description: string;
    amount: string;
}

interface WalletFrom
{
    customerId: string;
    plataformWallet: boolean;
    protectedWallet: boolean;
    publicKey: string;
}
interface WalletTo
{
    customerId: string;
    plataformWallet: boolean;
    protectedWallet: boolean;
    publicKey: string;
}

Example Response

{
    "tax": [
      {
        "amount": "3.5",
        "description": "The Transaction tax"
      },
      {
        "amount": "0",
        "description": "The Withdraw tax"
      }
    ],
    "calculatedTax": "0.025649512179012813",
    "willBeApproved": true,
    "walletFrom": {
      "customerId": "01920b54-6365-7993-b2c9-e25c3165ec71",
      "plataformWallet": true,
      "protectedWallet": false,
      "publicKey": "0x1c81DaCE9685E2CF55a865AE1bB7606Cf9E236f6"
    },
    "walletTo": {
      "customerId": "01928cc3-7f62-7887-b752-f14a4045c3d2",
      "plataformWallet": true,
      "protectedWallet": false,
      "publicKey": "0x03554a8fbdd36A7C87ba35085a12146A28eEc4F5"
    },
    "transactionLimits": [
      null,
      null
    ],
    "globalTraceId": "79ef62e0565cae2332e92259e30f8cb1"
}

Transfer

Endpoint: POST /v1/financial/transfer

Description: Transfers WIBX from one wallet to another. The transfer is only possible if the user has enough balance and if the transfer is allowed.

Note: The transfer is only possible if the user has his MFA TOTP enabled.

Request Interface

export interface Transfer
{
    walletIdTo: string;
    secretcode: string; // TOTP code
    amount: number;
}

Example Request

{
    "walletIdTo": "0x1c81DaCE9685E2CF55a865AE1bB7606Cf9E236f6",
    "secretcode": "123456",
    "amount": 10
}

Response Interface

export interface TransferOutput
{
    walletVerificationResponse: VerifyTransferOutput;
    financialTransactionId: Array<string>;
    status: string;
}

Example Response

{
    "walletVerificationResponse": {
        "tax": [
            {
                "amount": "3.5",
                "description": "The Transaction tax"
            },
            {
                "amount": "0",
                "description": "The Withdraw tax"
            }
        ],
        "calculatedTax": "0.025649512179012813",
        "willBeApproved": true,
        "walletFrom": {
            "customerId": "01920b54-6365-7993-b2c9-e25c3165ec71",
            "plataformWallet": true,
            "protectedWallet": false,
            "publicKey": "0x1c81DaCE9685E2CF55a865AE1bB7606Cf9E236f6"
        },
        "walletTo": {
            "customerId": "01928cc3-7f62-7887-b752-f14a4045c3d2",
            "plataformWallet": true,
            "protectedWallet": false,
            "publicKey": "0x03554a8fbdd36A7C87ba35085a12146A28eEc4F5"
        },
        "transactionLimits": [
            null,
            null
        ],
        "globalTraceId": "79ef62e0565cae2332e92259e30f8cb1"
    },
    "financialTransactionId": "019adb02-d0eb-7305-9e97-73ee9e28c2b0",
    "status": "approved"
}