Wallet Balance

Overview

The Yativo Wallet Balance API provides endpoints to retrieve wallet balances across all supported currencies and get the total balance converted to USD. This feature allows users to monitor their multi-currency wallet holdings in real-time.

Base URL

https://api.yativo.com/api/v1

All API requests require a Bearer token in the Authorization header.

Get All Wallet Balances

Endpoint

GET /wallet/balance

Description

Retrieves detailed balance information for all currency wallets associated with your account, including currency metadata and formatting information.

Headers

Header

Type

Required

Description

Authorization

string

Yes

Bearer token for authentication

Example Request

curl --location 'https://api.yativo.com/api/v1/wallet/balance' \
--header 'Authorization: Bearer YOUR_TOKEN'

Success Response (200 OK)

{
    "status": "success",
    "status_code": 200,
    "message": "Request successful",
    "data": [
        {
            "name": "ARS",
            "slug": "ars",
            "description": null,
            "meta": {
                "logo": "https://cdn.yativo.com/ars.svg",
                "symbol": "$",
                "fullname": "Argentine Peso",
                "precision": "2"
            },
            "balance": "0",
            "currency": "ARS",
            "decimal_places": 2,
            "deleted_at": null
        },
        {
            "name": "USD",
            "slug": "usd",
            "description": null,
            "meta": {
                "logo": "https://catamphetamine.github.io/country-flag-icons/3x2/US.svg",
                "symbol": "$",
                "fullname": "US Dollar",
                "precision": 2
            },
            "balance": "35585",
            "currency": "USD",
            "decimal_places": 2,
            "deleted_at": null
        }
    ]
}

Response Fields Explanation

Root level

status: Status of the API call ("success" or "error")
status_code: HTTP status code
message: Human-readable message about the request
data: Array of wallet balance objects

Wallet Balance Object

Field

Type

Description

name

string

Currency code (ISO 4217)

slug

string

URL-friendly currency identifier

description

string/null

Additional description (usually null)

balance

string

Current balance as a string

currency

string

Currency code

decimal_places

integer

Number of decimal places for this currency

deleted_at

string/null

Deletion timestamp (null for active wallets)

Meta Object — Currency display and formatting information:

Field

Type

Description

logo

string

URL to currency logo/flag image

symbol

string

Currency symbol (e.g., "$", "€", "R$")

fullname

string

Full currency name

precision

string/integer

Display precision for amounts

Supported Currencies

Based on the example response, supported currencies include:

ARS - Argentine Peso ($)
BRL - Brazilian Real (R$)
CLP - Chilean Peso ($)
COP - Colombian Peso ($)
EUR - Euro (€)
MXN - Mexican Peso ($)
PEN - Peruvian Sol (S/)
USD - US Dollar ($)

Get Total Balance in USD

Endpoint

GET /wallet/balance/total

Description

Retrieves the total balance of all wallets converted to USD using current exchange rates.

Headers

Header

Type

Required

Description

Authorization

string

Yes

Bearer token for authentication

Example Request

curl --location 'https://api.yativo.com/api/v1/wallet/balance/total' \
--header 'Authorization: Bearer YOUR_TOKEN'

Success Response (200 OK)

{
    "status": "success",
    "status_code": 200,
    "message": "Request successful",
    "data": {
        "total_balance": 35629.186104
    }
}

Response Fields Explanation

Root level

status: Status of the API call ("success" or "error")
status_code: HTTP status code
message: Human-readable message about the request
data: Total balance data object

Data object

Field

Type

Description

total_balance

number

Total balance in USD with high precision

Note: The total balance includes conversions from all non-zero wallet balances using current exchange rates.

Error Handling

Both endpoints return standard HTTP status codes. Common error responses include:

401 Unauthorized

{
    "status": "error",
    "status_code": 401,
    "message": "Authentication failed"
}

403 Forbidden

{
    "status": "error",
    "status_code": 403,
    "message": "Access denied to wallet information"
}

500 Internal Server Error

{
    "status": "error",
    "status_code": 500,
    "message": "Unable to retrieve wallet balances"
}

Usage Examples

Check Individual Wallet Balances

# Get detailed balance information for all wallets
curl --location 'https://api.yativo.com/api/v1/wallet/balance' \
--header 'Authorization: Bearer YOUR_TOKEN'

Get Portfolio Overview

# Get total portfolio value in USD
curl --location 'https://api.yativo.com/api/v1/wallet/balance/total' \
--header 'Authorization: Bearer YOUR_TOKEN'

Combined Wallet Dashboard (Sequential Calls)

Get individual balances

INDIVIDUAL_BALANCES=$(curl -s --location 'https://api.yativo.com/api/v1/wallet/balance' \
--header 'Authorization: Bearer YOUR_TOKEN')

Get total USD value

TOTAL_BALANCE=$(curl -s --location 'https://api.yativo.com/api/v1/wallet/balance/total' \
--header 'Authorization: Bearer YOUR_TOKEN')

Display results

echo "Individual Balances: $INDIVIDUAL_BALANCES"
echo "Total USD Value: $TOTAL_BALANCE"

Integration Tips

Balance Formatting

Use the decimal_places and meta.precision fields to properly format balance displays:

// Example: Format balance for display
function formatBalance(walletData) {
    const balance = parseFloat(walletData.balance);
    const symbol = walletData.meta.symbol;
    const precision = walletData.decimal_places;

    return `${symbol}${balance.toFixed(precision)}`;
}

Currency Logos

The meta.logo field provides URLs for currency logos that can be used in UI components:

<!-- Example: Display currency with logo -->
<img src="https://cdn.yativo.com/usd.svg" alt="USD" width="20" height="20">
<span>$35,585.00</span>

Zero Balance Handling

Wallets with zero balances are still returned in the API response. Filter them client-side if needed:

// Filter out zero balances
const nonZeroWallets = wallets.filter(wallet => parseFloat(wallet.balance) > 0);

Rate Limits

Maximum 100 requests per minute per API key
Both endpoints count towards the same rate limit
Rate limit headers are included in all responses

Real-time Updates

Balances are updated in real-time as transactions are processed
Exchange rates for total balance calculations are updated every minute
Consider implementing polling or webhooks for live balance updates

Support

For API support and questions, contact: [email protected]

Last Updated: August 2025 API Version: v1

PreviousLists NextQuote ID API Documentation