> ## Documentation Index > Fetch the complete documentation index at: https://docs.sakawave.com/llms.txt > Use this file to discover all available pages before exploring further. # List accounts > Returns your accounts and your customers’ wallet accounts, newest first. Internal platform balances, such as card settlement accounts, are never included. Closed accounts are. ## Filtering Filters are written as `field=value`, or `field:operator=value`. `balance` is compared in **minor units**, which is how it is stored — filtering NGN by naira is wrong by a factor of a hundred. ```http GET /v1/accounts?status=active¤cy:in=NGN,USDC&balance:gt=0&sort=-balance ``` To separate your own money from your customers’, filter on ownership rather than inferring it: ```http GET /v1/accounts?customerId:isnull=true # your business accounts GET /v1/accounts?isWalletAccount=true # your customers’ wallets ``` There is no filter on the payment provider behind an account, and there will not be: naming the integration that holds a balance is not something a filter should disclose either. ## Error codes | Status | `code` | Cause | | - | - | - | | `400` | `validation_failed` | An unknown filter or sort key, an unsupported operator, or a page size above 100. | | `401` | `INVALID_API_KEY` | The key is missing, invalid, inactive, expired, from the other environment, or blocked by its IP allowlist. | | `429` | `api_key_rate_limit_exceeded` | The per-minute limit for this key was exceeded. | ## OpenAPI ````yaml /openapi.json get /v1/accounts openapi: 3.1.0 info: title: Sakawave Business API version: 1.0.0-draft summary: >- Accounts, transfers, FX quotes, and transaction reconciliation for Sakawave businesses. description: >- Generated from the public NestJS controllers and their Zod request schemas. Public URLs and policy statements remain draft until the Phase 1 contract checklist is approved. contact: name: Sakawave API Support email: api-support@sakawave.example servers: - url: https://sandbox-api.sakawave.example description: Sandbox (default) - url: https://api.sakawave.example description: Live security: - bearerAuth: [] tags: - name: Bill payments description: Browse the biller catalog, validate a customer, and pay a bill. - name: Cards description: Issue, fund, and control USD virtual and disposable cards. - name: eSIM description: >- Sell mobile data abroad: browse the catalog, buy an eSIM, and manage it once installed. - name: Currencies and countries description: >- Reference data: what may be held, what may be sent where, and which jurisdictions are served. - name: Customers description: Create and manage customers of your business. - name: Accounts description: >- Open business and customer accounts, and issue the destinations that fund them. - name: Transfer destinations description: Resolve temporary destinations and saved recipients. - name: FX quotes description: Create and retrieve time-limited cross-currency quotes. - name: Transfers description: Preview, create, and monitor transfers. - name: Transactions description: Read ledger entries for reconciliation. paths: /v1/accounts: get: tags: - Accounts summary: List accounts description: >- Returns your accounts and your customers’ wallet accounts, newest first. Internal platform balances, such as card settlement accounts, are never included. Closed accounts are. operationId: listAccounts parameters: - name: page in: query required: false description: One-based page number. schema: type: integer minimum: 1 default: 1 - name: pageSize in: query required: false description: Records per page. A larger value is rejected rather than capped. schema: type: integer minimum: 1 maximum: 100 default: 25 - name: search in: query required: false description: >- Case-insensitive term matched against name and tag. Maximum 100 characters. schema: type: string maxLength: 100 - name: sort in: query required: false description: >- Up to three comma-separated keys from name, balance, currency, status, and createdAt. Prefix a key with - for descending order. schema: type: string example: '-createdAt' - name: name in: query required: false description: Exact match on your label. schema: type: string - name: name:contains in: query required: false description: Substring of your label. schema: type: string example: wallet - name: tag in: query required: false description: Exact match on the public transfer handle. schema: type: string pattern: ^[A-Z]{2}\d{10}$ example: AA0271849366 - name: tag:contains in: query required: false description: Substring of the transfer handle. schema: type: string - name: type in: query required: false description: Filter by account type. schema: type: string enum: - operational - savings - settlement - collection - fee - revenue - suspense - name: type:ne in: query required: false description: Everything except this type. schema: type: string - name: type:in in: query required: false description: Comma-separated account types. schema: type: string example: operational,savings - name: category in: query required: false description: Filter by asset category. schema: type: string enum: - fiat - crypto - name: category:in in: query required: false description: Comma-separated categories. schema: type: string - name: status in: query required: false description: Filter by status. schema: type: string enum: - active - inactive - frozen - closed - name: status:ne in: query required: false description: Everything except this status. schema: type: string example: closed - name: status:in in: query required: false description: Comma-separated statuses. schema: type: string example: active,frozen - name: currency in: query required: false description: Filter by asset code. schema: $ref: '#/components/schemas/AssetCode' - name: currency:in in: query required: false description: Comma-separated asset codes. schema: type: string example: NGN,USDC - name: balance in: query required: false description: Exact balance, in minor units. schema: $ref: '#/components/schemas/MinorUnits' - name: balance:gt in: query required: false description: Balance above this value, in minor units. schema: $ref: '#/components/schemas/MinorUnits' example: '0' - name: balance:gte in: query required: false description: Balance at or above this value, in minor units. schema: $ref: '#/components/schemas/MinorUnits' - name: balance:lt in: query required: false description: Balance below this value, in minor units. schema: $ref: '#/components/schemas/MinorUnits' - name: balance:lte in: query required: false description: Balance at or below this value, in minor units. schema: $ref: '#/components/schemas/MinorUnits' - name: isWalletAccount in: query required: false description: True for customer wallets, false for your own accounts. schema: type: boolean - name: customerId in: query required: false description: Wallets belonging to one customer. schema: $ref: '#/components/schemas/Ulid' - name: customerId:in in: query required: false description: Comma-separated customer identifiers. At most 50. schema: type: string - name: customerId:isnull in: query required: false description: >- true returns only your own accounts; false returns only customer wallets. schema: type: boolean - name: createdAt:gt in: query required: false description: Opened after this ISO 8601 timestamp. schema: type: string format: date-time - name: createdAt:gte in: query required: false description: Opened at or after this ISO 8601 timestamp. schema: type: string format: date-time - name: createdAt:lt in: query required: false description: Opened before this ISO 8601 timestamp. schema: type: string format: date-time - name: createdAt:lte in: query required: false description: Opened at or before this ISO 8601 timestamp. schema: type: string format: date-time responses: '200': description: Successful response. headers: X-Request-ID: description: >- The request identifier assigned by Sakawave. Include it in support requests. schema: type: string content: application/json: schema: $ref: '#/components/schemas/AccountPage' example: items: - id: 01K2Z3AB4D5E6F7G8H9JKMNPQR name: Ada NGN wallet type: operational category: fiat status: active currency: NGN balance: '2500000' balanceFormatted: '25000.00' tag: AA0271849366 canDebit: true canCredit: true isWalletAccount: true transferReady: true customerId: 01K2Z3AB4C5D6E7F8G9HJKMNPQ metadata: cohort: sandbox-tutorial closedAt: null closureReason: null createdAt: '2026-08-14T09:02:00.000Z' updatedAt: '2026-08-14T09:02:00.000Z' pagination: page: 1 pageSize: 25 total: 1 pageCount: 1 hasNext: false hasPrevious: false '400': $ref: '#/components/responses/ValidationError' '401': $ref: '#/components/responses/AuthenticationError' '429': $ref: '#/components/responses/RateLimitError' '500': $ref: '#/components/responses/ServerError' security: - bearerAuth: [] components: schemas: AssetCode: type: string enum: - NGN - USD - GBP - EUR - GHS - ZAR - UGX - CAD - MXN - AED - BTC - ETH - USDT - USDC MinorUnits: type: string pattern: ^-?\d+$ example: '2500000' description: >- An integer number of the asset’s smallest unit. Use this value for arithmetic. Ulid: type: string minLength: 26 maxLength: 26 pattern: ^[0-7][0-9A-HJKMNP-TV-Z]{25}$ example: 01K2Z3AB4C5D6E7F8G9HJKMNPQ description: A 26-character ULID. AccountPage: type: object additionalProperties: false properties: items: type: array items: $ref: '#/components/schemas/AccountResponse' pagination: $ref: '#/components/schemas/Pagination' required: - items - pagination AccountResponse: type: object additionalProperties: false properties: id: $ref: '#/components/schemas/Ulid' name: type: string description: Your own label for the account. Not shown to anyone paying into it. type: type: string enum: - operational - savings - settlement - collection - fee - revenue - suspense description: >- What the account is for. `operational` and `savings` behave identically; the rest are platform-managed. category: type: string enum: - fiat - crypto description: Follows from the currency; it is never chosen. status: type: string enum: - active - inactive - frozen - closed description: >- Only `active` can move money. `frozen` is a compliance or provider hold. `closed` is terminal. currency: $ref: '#/components/schemas/AssetCode' balance: $ref: '#/components/schemas/MinorUnits' balanceFormatted: type: string description: The same figure rendered for display. Never use it in a calculation. tag: type: string pattern: ^[A-Z]{2}\d{10}$ description: >- The account’s public transfer handle: two letters and ten digits, the last a check digit. Platform-minted and unique across Sakawave, so another business can pay this account by tag. canDebit: type: boolean description: >- Whether money may leave. Held separately from status: an account can be stopped in one direction only. canCredit: type: boolean description: Whether money may arrive. isWalletAccount: type: boolean description: >- True when the account belongs to one of your customers rather than to your business. transferReady: type: boolean description: >- True once the account is bound to a payment provider. A freshly opened account is false until its first detail is issued, and cannot yet send or receive externally. customerId: anyOf: - $ref: '#/components/schemas/Ulid' description: The owning customer, when this is a wallet account. - type: 'null' metadata: anyOf: - type: object additionalProperties: true description: >- Whatever you stored at creation, returned unchanged. Sakawave never reads it. - type: 'null' closedAt: anyOf: - $ref: '#/components/schemas/IsoTimestamp' - type: 'null' closureReason: anyOf: - type: string enum: - client_request - no_longer_needed - duplicate - compliance - type: 'null' createdAt: $ref: '#/components/schemas/IsoTimestamp' updatedAt: $ref: '#/components/schemas/IsoTimestamp' required: - id - name - type - category - status - currency - balance - balanceFormatted - tag - canDebit - canCredit - isWalletAccount - transferReady - customerId - metadata - closedAt - closureReason - createdAt - updatedAt Pagination: type: object additionalProperties: false properties: page: type: integer minimum: 1 pageSize: type: integer minimum: 1 maximum: 100 total: type: integer minimum: 0 pageCount: type: integer minimum: 0 hasNext: type: boolean hasPrevious: type: boolean required: - page - pageSize - total - pageCount - hasNext - hasPrevious RequestError: anyOf: - $ref: '#/components/schemas/ValidationError' - $ref: '#/components/schemas/Error' description: >- Either a field-level validation failure carrying an errors array, or a rule the request broke, identified by code. Error: type: object additionalProperties: true properties: statusCode: type: integer message: type: string description: >- A sentence suitable for a log or a support conversation, not for a user interface. code: type: string description: >- The stable machine-readable reason. Branch on this, never on the message. required: - message - code description: >- An error body. Individual errors may add context fields alongside these three. RateLimitError: type: object additionalProperties: false properties: statusCode: const: 429 message: type: string code: const: api_key_rate_limit_exceeded retryAfterSeconds: type: integer minimum: 1 required: - statusCode - message - code - retryAfterSeconds IsoTimestamp: type: string format: date-time example: '2026-08-14T09:00:00.000Z' ValidationError: type: object additionalProperties: false properties: statusCode: const: 400 message: type: string description: The single failure, or a count when more than one field failed. code: const: validation_failed errors: type: array items: $ref: '#/components/schemas/ValidationFailure' required: - statusCode - message - code - errors ValidationFailure: type: object additionalProperties: false properties: message: type: string field: type: string code: type: string path: type: array items: anyOf: - type: string - type: integer required: - message - field - code - path responses: ValidationError: description: >- The request was rejected before it was acted on. Field failures list every failing field. headers: X-Request-ID: description: >- The request identifier assigned by Sakawave. Include it in support requests. schema: type: string content: application/json: schema: $ref: '#/components/schemas/RequestError' example: statusCode: 400 message: Must be a valid identifier. code: validation_failed errors: - message: Must be a valid identifier. field: accountId code: custom path: - accountId AuthenticationError: description: >- The API key is missing, invalid, inactive, expired, for another environment, or blocked by its IP allowlist. headers: X-Request-ID: description: >- The request identifier assigned by Sakawave. Include it in support requests. schema: type: string content: application/json: schema: $ref: '#/components/schemas/Error' example: statusCode: 401 code: INVALID_API_KEY message: Invalid or inactive API credentials. RateLimitError: description: The API key rate limit was exceeded. headers: X-Request-ID: description: >- The request identifier assigned by Sakawave. Include it in support requests. schema: type: string content: application/json: schema: $ref: '#/components/schemas/RateLimitError' example: statusCode: 429 message: Too many API requests. Try again later. code: api_key_rate_limit_exceeded retryAfterSeconds: 17 ServerError: description: An unexpected server error occurred. headers: X-Request-ID: description: >- The request identifier assigned by Sakawave. Include it in support requests. schema: type: string content: application/json: schema: $ref: '#/components/schemas/Error' example: statusCode: 500 code: internal_server_error message: An unexpected error occurred. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: Sakawave API key description: >- A secret API key, sent as `Authorization: Bearer sk_test_…` in sandbox or `Bearer sk_live_…` in live. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.