List wallets

curl --request GET \
  --url https://api.paystack.com/v1/wallets \
  --header 'Authorization: Bearer <token>'

{
  "status": true,
  "message": "Wallets fetched successfully",
  "code": "ok",
  "data": [
    {
      "id": "wal_01HXYZABC1234567890ABCDEFG",
      "customer_id": "cust_01HXYZABC1234567890ABCDEFG",
      "currency": "USDC",
      "available_balance": "1234.567890",
      "pending_balance": "0.000000",
      "total_balance": "1234.567890",
      "metadata": {},
      "provisioned": false,
      "created_at": "2026-05-20T12:00:00.000Z",
      "updated_at": "2026-05-20T12:00:00.000Z",
      "label": "USDC Operating Wallet"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 50,
    "total": 137,
    "has_more": false,
    "request_id": "req_01HXYZ4K5ABCDEFGHJKLMNPQRS",
    "timestamp": "2026-05-14T15:43:55.732Z",
    "version": "1"
  }
}

Wallets

List wallets

Returns the calling merchant’s wallets, newest first.

All filters are optional. When no filters are supplied all wallets are returned (paginated), across all customers.

Filter behavior

customer_id — restricts to a single customer’s wallets. Must be a GlobalStack cust_… id.
currency — restricts to one currency code (exact, uppercase, e.g. USDC).

Pagination

page — 1-indexed page number. Defaults to 1. Must be between 1 and 1,000,000.
per_page — page size. Defaults to 20. Must be between 1 and 50. Capped tighter than other list endpoints because each wallet is composed with a live ledger balance.

The response carries pagination metadata under meta (page, per_page, total, has_more). has_more is true when at least one more page is available.

Balances

available_balance, pending_balance, and total_balance are sourced from the ledger and formatted to the currency’s precision. Wallets that are not yet provisioned (provisioned: false) report zero balances.

Ordering

Results are sorted by created_at DESC, id DESC (newest first, deterministic on ties).

Example

GET /v1/wallets?customer_id=cust_01HXYZ…&currency=USDC&page=1&per_page=25

GET

wallets

List wallets

curl --request GET \
  --url https://api.paystack.com/v1/wallets \
  --header 'Authorization: Bearer <token>'

{
  "status": true,
  "message": "Wallets fetched successfully",
  "code": "ok",
  "data": [
    {
      "id": "wal_01HXYZABC1234567890ABCDEFG",
      "customer_id": "cust_01HXYZABC1234567890ABCDEFG",
      "currency": "USDC",
      "available_balance": "1234.567890",
      "pending_balance": "0.000000",
      "total_balance": "1234.567890",
      "metadata": {},
      "provisioned": false,
      "created_at": "2026-05-20T12:00:00.000Z",
      "updated_at": "2026-05-20T12:00:00.000Z",
      "label": "USDC Operating Wallet"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 50,
    "total": 137,
    "has_more": false,
    "request_id": "req_01HXYZ4K5ABCDEFGHJKLMNPQRS",
    "timestamp": "2026-05-14T15:43:55.732Z",
    "version": "1"
  }
}

Authorizations

Authorization

string

header

required

API key issued during merchant onboarding.

Query Parameters

customer_id

string

Restrict to one customer (cust_… id). Omit to list all wallets in the integration.

Example:

"cust_01HXYZABC1234567890ABCDEFG"

currency

string

2–8 uppercase alphanumerics. Exact match.

Example:

"USDC"

page

integer

default:1

1-indexed page number.

Required range: 1 <= x <= 1000000

Example:

1

per_page

integer

default:20

Page size (1–50). Capped tighter than other list endpoints because each wallet is composed with a live ledger balance.

Required range: 1 <= x <= 50

Example:

20

Response

Wallets fetched successfully

status

enum<boolean>

required

Available options:

true

Example:

true

message

string

required

Human-readable summary

Example:

"Wallets fetched successfully"

code

enum<string>

required

Available options:

ok

Example:

"ok"

data

object[]

required

Show child attributes