> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yativo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Wallets

> Manage multi-currency wallet balances and initiate payouts

Your Yativo wallet holds balances in multiple currencies. Fund payouts from your wallet, and receive deposits into it. The wallet API lets you check balances, create new currency wallets, and initiate quick payouts.

<Accordion title="Type Definitions">
  ```typescript theme={null}
  interface WalletBalance {
    name: string;           // currency code, e.g. "USD"
    slug: string;           // URL-friendly, e.g. "usd"
    balance: string;        // current balance as string
    currency: string;       // currency code
    decimal_places: number;
    meta: {
      logo: string;         // URL to currency logo/flag
      symbol: string;       // e.g. "$", "R$", "S/"
      fullname: string;     // e.g. "US Dollar"
      precision: string | number;
    };
  }

  interface TotalBalance {
    total_balance: number;  // total of all wallets converted to USD
  }
  ```
</Accordion>

***

## Get Wallet Balance

Returns detailed balance information for every currency wallet on your account.

```
GET /wallet/balance
```

<ParamField query="currency" type="string">
  Optional: filter by a specific currency code (e.g. `USD`, `BRL`). Omit to return all.
</ParamField>

<RequestExample>
  ```bash All balances theme={null}
  curl -X GET 'https://api.yativo.com/api/v1/wallet/balance' \
    -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
  ```

  ```bash Single currency theme={null}
  curl -X GET 'https://api.yativo.com/api/v1/wallet/balance?currency=USD' \
    -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
  ```
</RequestExample>

<ResponseExample>
  ```json Success theme={null}
  {
    "status": "success",
    "status_code": 200,
    "message": "Request successful",
    "data": [
      {
        "name": "USD",
        "slug": "usd",
        "balance": "35585.00",
        "currency": "USD",
        "decimal_places": 2,
        "meta": {
          "logo": "https://cdn.yativo.com/usd.svg",
          "symbol": "$",
          "fullname": "US Dollar",
          "precision": 2
        }
      },
      {
        "name": "BRL",
        "slug": "brl",
        "balance": "14200.00",
        "currency": "BRL",
        "decimal_places": 2,
        "meta": {
          "logo": "https://cdn.yativo.com/brl.svg",
          "symbol": "R$",
          "fullname": "Brazilian Real",
          "precision": "2"
        }
      }
    ]
  }
  ```
</ResponseExample>

**Supported currencies:** ARS, BRL, CLP, COP, EUR, MXN, PEN, USD

***

## Get Total Balance

Returns the sum of all wallet balances converted to USD at current exchange rates:

```
GET /wallet/balance/total
```

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET 'https://api.yativo.com/api/v1/wallet/balance/total' \
    -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
  ```
</RequestExample>

<ResponseExample>
  ```json Success theme={null}
  {
    "status": "success",
    "status_code": 200,
    "message": "Request successful",
    "data": {
      "total_balance": 37629.18
    }
  }
  ```
</ResponseExample>

***

## Create a Wallet

Create a new currency wallet for your account:

```
POST /wallet/create
```

<ParamField body="currency" type="string" required>
  The currency code for the new wallet (e.g. `COP`, `PEN`, `ARS`).
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST 'https://api.yativo.com/api/v1/wallet/create' \
    -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
    -H 'Content-Type: application/json' \
    -H 'Idempotency-Key: unique-key-here' \
    -d '{ "currency": "COP" }'
  ```
</RequestExample>

<ResponseExample>
  ```json Success theme={null}
  {
    "status": "success",
    "data": {
      "currency": "COP",
      "balance": "0.00"
    }
  }
  ```
</ResponseExample>

***

## Quick Wallet Payout

Initiate a payout directly from your wallet balance without the full send money flow:

```
POST /wallet/payout
```

<ParamField body="debit_wallet" type="string" required>
  Currency to debit from your balance (e.g. `"USD"`).
</ParamField>

<ParamField body="payment_method_id" type="number" required>
  The saved beneficiary payment method ID.
</ParamField>

<ParamField body="quote_id" type="string">
  Quote ID from `POST /sendmoney/quote` or `POST /exchange-rate`. Locks the rate for 5 minutes. Recommended — amount is taken from the quote.
</ParamField>

<ParamField body="amount" type="number">
  Amount to send. Required if `quote_id` is not provided. Uses current market rate.
</ParamField>

<RequestExample>
  ```bash With quote (recommended) theme={null}
  curl -X POST 'https://api.yativo.com/api/v1/wallet/payout' \
    -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
    -H 'Content-Type: application/json' \
    -H 'Idempotency-Key: unique-payout-key' \
    -d '{
      "debit_wallet": "USD",
      "quote_id": "4a72ecf8-6c8a-4e38-9971-8aabe9f785ed",
      "payment_method_id": 21
    }'
  ```

  ```bash Without quote (market rate) theme={null}
  curl -X POST 'https://api.yativo.com/api/v1/wallet/payout' \
    -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
    -H 'Content-Type: application/json' \
    -H 'Idempotency-Key: unique-payout-key' \
    -d '{
      "debit_wallet": "USD",
      "amount": 500,
      "payment_method_id": 21
    }'
  ```
</RequestExample>

***

## Display Tips

```javascript theme={null}
// Format a wallet balance for display
function formatBalance(wallet) {
  const balance = parseFloat(wallet.balance);
  const symbol = wallet.meta.symbol;
  const precision = wallet.decimal_places;
  return `${symbol}${balance.toFixed(precision)}`;
}

// Filter out zero balances
const activeWallets = wallets.filter(w => parseFloat(w.balance) > 0);
```

<Note>
  Wallets with zero balances are included in the response. Filter client-side if you only want non-zero holdings.
</Note>