# Wallets

Create and manage wallets: the user-facing containers for money, backed by liability accounts.

URL: https://docs.shiwake.app/docs/banking/wallets



A **wallet** is a user-facing money container. Under the hood, each wallet
maps 1:1 to a liability account in the core ledger. The wallet adds
higher-level concepts: an owner, a product, a tier, a status, and
human-readable metadata.

The Wallet object [#the-wallet-object]

```json
{
  "id": "wal_01HZ...",
  "productId": "wp_01HZ...",
  "productCode": "SAVINGS",
  "accountId": "acc_01HZ...",
  "accountCode": "CLIENT-user_42",
  "ownerId": "user_42",
  "ownerType": "Individual",
  "displayName": "Kwame's Savings",
  "tier": "Unverified",
  "status": "Active",
  "currency": "GHS",
  "ledgerBalance": 150000,
  "availableBalance": 125000,
  "metadata": null,
  "createdAt": "2026-04-01T10:00:00Z",
  "updatedAt": null
}
```

<TypeTable
  type="{
  id: { type: &#x22;string&#x22;, required: true, description: &#x22;Unique wallet identifier&#x22; },
  productId: { type: &#x22;string&#x22;, required: true, description: &#x22;The product this wallet was created from&#x22; },
  productCode: { type: &#x22;string&#x22;, required: true, description: &#x22;Product code for display&#x22; },
  accountId: { type: &#x22;string&#x22;, required: true, description: &#x22;Underlying ledger account id&#x22; },
  accountCode: { type: &#x22;string&#x22;, required: true, description: &#x22;Underlying ledger account code&#x22; },
  ownerId: { type: &#x22;string&#x22;, required: true, description: &#x22;Your system's user/entity id&#x22; },
  ownerType: { type: &#x22;string&#x22;, required: true, description: <><code>Individual</code> or <code>Business</code></> },
  displayName: { type: &#x22;string&#x22;, required: true, description: &#x22;Human-readable label&#x22; },
  tier: { type: &#x22;string&#x22;, required: true, description: <>KYC tier: <code>Unverified</code>, <code>Basic</code>, or <code>Full</code></> },
  status: { type: &#x22;string&#x22;, required: true, description: <><code>Active</code>, <code>Frozen</code>, <code>Closed</code></> },
  currency: { type: &#x22;string&#x22;, required: true, description: &#x22;ISO 4217 code&#x22; },
  ledgerBalance: { type: &#x22;long&#x22;, required: true, description: &#x22;Total balance from journal entries (minor units)&#x22; },
  availableBalance: { type: &#x22;long&#x22;, required: true, description: &#x22;Ledger balance minus active holds (minor units)&#x22; },
  metadata: { type: &#x22;object | null&#x22;, required: true, description: &#x22;Arbitrary JSON&#x22; },
}"
/>

<Callout type="info">
  `ledgerBalance` is the true accounting balance. `availableBalance` is
  what the user can actually spend. It excludes any amounts reserved by
  pending withdrawals.
</Callout>

One wallet per owner per product [#one-wallet-per-owner-per-product]

Each owner can have at most one wallet per product. If you need a user to
have multiple wallets, create multiple products (e.g. `SAVINGS`,
`SPENDING`, `BUSINESS`).

***

Create a wallet [#create-a-wallet]

<Endpoint method="POST" path="/api/v1/banking/wallets" />

Opens a new wallet for the given owner on the specified product. This
atomically creates the underlying ledger account and the wallet record.

Request body [#request-body]

<TypeTable
  type="{
  productCode: { type: &#x22;string&#x22;, required: true, description: &#x22;Product code or id&#x22; },
  ownerId: { type: &#x22;string&#x22;, required: true, description: &#x22;Your system's user/entity id&#x22; },
  ownerType: { type: &#x22;string&#x22;, required: true, description: <><code>Individual</code> or <code>Business</code></> },
  displayName: { type: &#x22;string&#x22;, required: true, description: &#x22;Human-readable label&#x22; },
  currency: { type: &#x22;string&#x22;, description: <>Defaults to the product's <code>defaultCurrency</code></> },
  metadata: { type: &#x22;object&#x22;, description: &#x22;Arbitrary JSON&#x22; },
}"
/>

<CodeBlockTabs defaultValue="curl">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="curl">
      curl
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="json">
      Response
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="curl">
    ```bash
    curl -X POST "https://api.shiwake.example.com/api/v1/banking/wallets" \
      -H "X-Api-Key: sk_live_..." \
      -H "Content-Type: application/json" \
      -d '{
        "productCode": "SAVINGS",
        "ownerId": "user_42",
        "ownerType": "Individual",
        "displayName": "Kwame'\''s Savings"
      }'
    ```
  </CodeBlockTab>

  <CodeBlockTab value="json">
    ```json
    {
      "code": 201,
      "message": "Created successfully",
      "data": {
        "id": "wal_01HZ...",
        "productId": "wp_01HZ...",
        "productCode": "SAVINGS",
        "accountId": "acc_01HZ...",
        "accountCode": "CLIENT-user_42",
        "ownerId": "user_42",
        "ownerType": "Individual",
        "displayName": "Kwame's Savings",
        "tier": "Unverified",
        "status": "Active",
        "currency": "GHS",
        "ledgerBalance": 0,
        "availableBalance": 0,
        "metadata": null,
        "createdAt": "2026-04-01T10:00:00Z",
        "updatedAt": null
      }
    }
    ```
  </CodeBlockTab>
</CodeBlockTabs>

Status codes [#status-codes]

| Code  | When                                                    |
| ----- | ------------------------------------------------------- |
| `201` | Wallet created                                          |
| `404` | Product not found                                       |
| `409` | Owner already has a wallet on this product              |
| `422` | Product inactive, owner type mismatch, invalid currency |

***

List wallets [#list-wallets]

<Endpoint method="GET" path="/api/v1/banking/wallets" />

<TypeTable
  type="{
  productId: { type: &#x22;string&#x22;, description: &#x22;Filter by product&#x22; },
  status: { type: &#x22;string&#x22;, description: <>Filter by <code>Active</code>, <code>Frozen</code>, <code>Closed</code></> },
}"
/>

***

Get a wallet [#get-a-wallet]

<Endpoint method="GET" path="/api/v1/banking/wallets/{id}" />

***

List by owner [#list-by-owner]

<Endpoint method="GET" path="/api/v1/banking/wallets/by-owner/{ownerId}" />

Returns all wallets for a specific owner across all products.

***

Freeze a wallet [#freeze-a-wallet]

<Endpoint method="POST" path="/api/v1/banking/wallets/{id}/freeze" />

Prevents all money movement. The wallet cannot receive deposits, process
withdrawals, or participate in transfers while frozen.

```bash
curl -X POST "https://api.shiwake.example.com/api/v1/banking/wallets/wal_01HZ.../freeze" \
  -H "X-Api-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Suspicious activity flagged by compliance" }'
```

***

Unfreeze a wallet [#unfreeze-a-wallet]

<Endpoint method="POST" path="/api/v1/banking/wallets/{id}/unfreeze" />

Restores a frozen wallet to `Active` status.

```bash
curl -X POST "https://api.shiwake.example.com/api/v1/banking/wallets/wal_01HZ.../unfreeze" \
  -H "X-Api-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Investigation cleared" }'
```

***

Close a wallet [#close-a-wallet]

<Endpoint method="POST" path="/api/v1/banking/wallets/{id}/close" />

Permanently closes a wallet. The wallet must have zero balance (both
ledger and available). Closed wallets cannot be reopened.

<Callout type="warn">
  Closing is irreversible. Ensure the wallet has been fully settled before
  closing.
</Callout>

Status codes [#status-codes-1]

| Code  | When                              |
| ----- | --------------------------------- |
| `200` | Status changed                    |
| `404` | Wallet not found                  |
| `409` | Wallet is already closed          |
| `422` | Cannot close: outstanding balance |

***

Upgrade tier [#upgrade-tier]

<Endpoint method="POST" path="/api/v1/banking/wallets/{id}/upgrade-tier" />

Changes the wallet's KYC tier. Tiers affect which
[transaction limits](/docs/banking/limits) apply. Moving a wallet to a
higher tier is what unlocks the limits you configured for that tier. The
three tiers, lowest to highest trust, are `Unverified`, `Basic`, and
`Full`.

Request body [#request-body-1]

<TypeTable
  type="{
  tier: { type: &#x22;string&#x22;, required: true, description: <><code>Unverified</code>, <code>Basic</code>, or <code>Full</code></> },
}"
/>

```bash
curl -X POST "https://api.shiwake.example.com/api/v1/banking/wallets/wal_01HZ.../upgrade-tier" \
  -H "X-Api-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "tier": "Full" }'
```

***

Get limit usage [#get-limit-usage]

<Endpoint method="GET" path="/api/v1/banking/wallets/{id}/limits/usage" />

Returns the wallet's current usage against all applicable
[transaction limits](/docs/banking/limits). How much has been used in each
period and how much remains.

```json
{
  "code": 200,
  "data": {
    "walletId": "wal_01HZ...",
    "tier": "Basic",
    "productName": "Savings Account",
    "limits": [
      {
        "transactionType": "Deposit",
        "period": "Daily",
        "maxAmount": 500000,
        "usedAmount": 150000,
        "remainingAmount": 350000,
        "currency": "GHS"
      },
      {
        "transactionType": "Withdrawal",
        "period": "Monthly",
        "maxAmount": 5000000,
        "usedAmount": 0,
        "remainingAmount": 5000000,
        "currency": "GHS"
      }
    ]
  }
}
```
