---
title: "List wallets"
method: GET
path: "/wallets"
tags: ["Wallets"]
---

# List wallets

`GET /wallets`

List all wallets for the authenticated party, including wallet type, default flag, balance, and receiving bank name when available.

## Query parameters

- `partyId` string — Party ID for delegated wallet lookup

## Headers

- `X-Agent-ID` string, nullable
- `X-Instance-ID` string, nullable

## Response `200`

Successful Response

- object
  - `data` object[], required
    - `type` 'wallet', required — Resource type
    - `id` string, required — Resource ID
    - `attributes` object, required — Resource attributes
      - `status` 'active' | 'frozen' | 'closed', required — Wallet readiness status
      - `walletType` 'standard' | 'vault', required — Wallet kind: a spendable standard wallet or the vault
      - `isDefault` boolean, required — Whether this wallet is the party's default for unnamed operations
      - `createdAt` string, date-time, nullable, required — Wallet creation time; null when the upstream read omits it
      - `displayName` string, nullable, required — Human-readable wallet name, when set
      - `description` string, nullable, required — User-facing wallet description, when set
      - `balance` object, nullable, required — Wallet ledger balance; null when the balance read failed transiently
        - `available` integer, required — Amount currently available to spend or withdraw (cents)
        - `total` integer, required — Total wallet ledger balance (cents)
        - `currency` 'USD', required — Currency code
      - `claims` object, required — Claimable payment totals
        - `amount` integer, required — Total unclaimed product-payment amount (cents)
        - `count` integer, required — Number of unclaimed product payments
      - `depositInstructions` object, nullable, required — ACH deposit-instruction metadata for this wallet, when available
        - `bankName` string, required — Name of the receiving bank
    - `relationships` object, required — Resource relationships
      - `party` object, required — Party that owns the wallet
        - `data` object, required — Related resource identifier
          - `type` 'party', required — Resource type
          - `id` string, required
  - `meta` object, required
    - `pagination` object, required
      - `hasMore` boolean, required
      - `nextCursor` string, nullable, required

## Other responses

- `400` — Validation Error
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found — returned when the resource does not exist, or when it exists but is not accessible to your account. The two cases are intentionally indistinguishable, so that resource IDs cannot be enumerated by probing.
- `409` — Conflict
- `422` — Validation Error
- `428` — Precondition Required
- `429` — Too Many Requests
- `500` — Internal Server Error
- `501` — Not Implemented
- `502` — Bad Gateway
- `503` — Service Unavailable

---

[API](https://skmtc.dev/natural/apis/natural-api.md) · [All operations](https://skmtc.dev/natural/apis/natural-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/natural/natural-api/revisions/8cc2aed45847/schema)