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

# Wallet

> Core financial operations - balances, transfers, and transactions

<Info>
  The Wallet API provides core financial operations for OLIVE accounts. All monetary operations are atomic and recorded in the transaction ledger.
</Info>

## Key Features

<CardGroup cols={3}>
  <Card title="Real-Time Balance" icon="coins">
    Instant balance queries with PIN verification
  </Card>

  <Card title="P2P Transfers" icon="arrow-right-left">
    Send money to any subscriber by card
  </Card>

  <Card title="Transaction History" icon="history">
    Complete audit trail of all operations
  </Card>
</CardGroup>

***

## Endpoints

<CardGroup cols={2}>
  <Card title="Get Balance" icon="wallet" href="/api-reference/wallet/balance">
    `POST /api/v1/wallet/balance/{id}`

    Get current wallet balance (PIN required)
  </Card>

  <Card title="Transactions" icon="list" href="/api-reference/wallet/transactions">
    `POST /api/v1/wallet/transactions/{id}`

    Get transaction history
  </Card>

  <Card title="P2P Transfer" icon="arrow-right" href="/api-reference/wallet/transfer-p2p">
    `POST /api/v1/wallet/transfer-p2p`

    Send money by card serial
  </Card>

  <Card title="Internal Transfer" icon="repeat" href="/api-reference/wallet/transfer">
    `POST /api/v1/wallet/transfer`

    Transfer between accounts
  </Card>

  <Card title="Fund from VULT" icon="plus-circle" href="/api-reference/wallet/fund">
    `POST /api/v1/wallet/fund-from-vult`

    Top up from VULT wallet
  </Card>

  <Card title="Account Statement" icon="file-text" href="/api-reference/wallet/statement">
    `POST /api/v1/wallet/account-statement`

    Generate PDF/CSV statement
  </Card>
</CardGroup>

***

## Transaction Types

| Type            | Description               | Direction    |
| --------------- | ------------------------- | ------------ |
| `transfer_p2p`  | Person to person transfer | Debit/Credit |
| `agent_cashin`  | Cash deposit via agent    | Credit       |
| `agent_cashout` | Cash withdrawal via agent | Debit        |
| `pos_payment`   | POS terminal purchase     | Debit        |
| `vult_fund`     | Funding from VULT         | Credit       |
| `vult_transfer` | Transfer to VULT          | Debit        |
| `fee`           | Transaction fee           | Debit        |
| `reversal`      | Transaction reversal      | Credit/Debit |

***

## Transaction Object

```json theme={null}
{
  "id": "txn_abc123",
  "type": "transfer_p2p",
  "status": "completed",
  "amount": 5000000,
  "amount_formatted": "50,000.00 SLE",
  "fee": 75000,
  "fee_formatted": "750.00 SLE",
  "currency": "SLE",
  "direction": "debit",
  "counterparty": {
    "id": "sub_xyz789",
    "name": "Jane Smith",
    "card_serial": "OLIV0002"
  },
  "balance_after": 12500000,
  "memo": "Payment for services",
  "created_at": "2025-01-15T10:30:00Z"
}
```

***

## Transfer Flow

<Steps>
  <Step title="Initiate Transfer">
    Sender provides recipient card serial, amount, and PIN
  </Step>

  <Step title="Validation">
    * Verify sender PIN
    * Check sender balance (amount + fee)
    * Validate recipient exists and is active
    * Run compliance checks
  </Step>

  <Step title="Execute Transfer">
    Atomic operation:

    * Debit sender (amount + fee)
    * Credit recipient (amount)
    * Record fee
  </Step>

  <Step title="Notification">
    Both parties receive WhatsApp confirmation
  </Step>
</Steps>

***

## Balance Security

<Warning>
  Balance queries require PIN verification to prevent unauthorized access.
</Warning>

<CardGroup cols={2}>
  <Card title="PIN Required" icon="lock">
    All balance and history queries need 4-digit PIN
  </Card>

  <Card title="Rate Limited" icon="shield">
    Failed PIN attempts are tracked and limited
  </Card>
</CardGroup>

***

## Common Workflows

<AccordionGroup>
  <Accordion title="Send Money to Friend" icon="arrow-right">
    1. Get recipient's card serial number
    2. Call `POST /api/v1/wallet/transfer-p2p`
    3. Include sender ID, recipient card, amount, PIN
    4. Both parties receive WhatsApp notifications
  </Accordion>

  <Accordion title="Check Balance" icon="wallet">
    1. Call `POST /api/v1/wallet/balance/{subscriber_id}`
    2. Include PIN in request body
    3. Returns current balance and currency
  </Accordion>

  <Accordion title="View Transaction History" icon="history">
    1. Call `POST /api/v1/wallet/transactions/{subscriber_id}`
    2. Include PIN, limit, and offset
    3. Returns paginated transaction list
  </Accordion>

  <Accordion title="Generate Statement" icon="file-text">
    1. Call `POST /api/v1/wallet/account-statement`
    2. Specify date range and format (PDF/CSV)
    3. Returns download URL for statement file
  </Accordion>
</AccordionGroup>

***

## Fees

Transaction fees are configured per transaction type. See [Fee Settings](/api-reference/fees/overview) for configuration.

| Transaction   | Default Fee      |
| ------------- | ---------------- |
| P2P Transfer  | 1.5% (sender)    |
| Agent Cash-In | 0.5% (agent)     |
| POS Payment   | 1.0% (processor) |
| VULT Fund     | 0%               |

***

## Related

<CardGroup cols={2}>
  <Card title="Agent Cash-In" icon="plus" href="/api-reference/agents/cashin">
    Deposit cash through agent
  </Card>

  <Card title="POS Payment" icon="store" href="/api-reference/pos/payment">
    Pay at merchant terminal
  </Card>
</CardGroup>