Fetch a wallet

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

{
  "status": true,
  "message": "Wallet 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,
    "credentials": [
      {
        "id": "wcr_01HXYZABC1234567890ABCDEFG",
        "type": "crypto",
        "currency": "USDC",
        "network": "base",
        "wallet": {
          "id": "wal_01HXYZABC1234567890ABCDEFG",
          "currency": "USDC",
          "label": "USDC Wallet"
        },
        "metadata": {
          "team": "ops"
        },
        "details": {
          "accountName": "Medard Ilunga",
          "accountNumber": "1234567890",
          "bankName": "Wema Bank",
          "bankCode": "035",
          "currency": "NGN"
        },
        "status": "pending",
        "created_at": "2026-05-20T12:00:00.000Z",
        "updated_at": "2026-05-20T12:00:00.000Z",
        "label": "Treasury deposit"
      }
    ],
    "created_at": "2026-05-20T12:00:00.000Z",
    "updated_at": "2026-05-20T12:00:00.000Z",
    "label": "USDC Operating Wallet"
  },
  "meta": {
    "request_id": "req_01HXYZ4K5ABCDEFGHJKLMNPQRS",
    "timestamp": "2026-05-14T15:43:55.732Z",
    "version": "1"
  }
}

Wallets

Fetch a wallet

Returns a single wallet, including its credentials.

The path id is the GlobalStack external identifier (wal_…) returned by POST /v1/wallets and GET /v1/wallets.

Credentials

data.credentials lists the wallet’s credentials, created via POST /v1/wallets/{id}/credentials — newest first. The array is empty when the wallet has no credentials.

Balances

available_balance, pending_balance, and total_balance start at 0.00 (formatted to the currency precision).

Errors

400 invalid_input — wallet_id does not start with wal_. This catches callers passing a non-GlobalStack id (e.g. a cust_… id).
404 not_found — returned for all lookup misses: the id does not exist.

Example

GET /v1/wallets/wal_seed_alice_usdc

GET

wallets

{walletId}

Fetch a wallet

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

{
  "status": true,
  "message": "Wallet 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,
    "credentials": [
      {
        "id": "wcr_01HXYZABC1234567890ABCDEFG",
        "type": "crypto",
        "currency": "USDC",
        "network": "base",
        "wallet": {
          "id": "wal_01HXYZABC1234567890ABCDEFG",
          "currency": "USDC",
          "label": "USDC Wallet"
        },
        "metadata": {
          "team": "ops"
        },
        "details": {
          "accountName": "Medard Ilunga",
          "accountNumber": "1234567890",
          "bankName": "Wema Bank",
          "bankCode": "035",
          "currency": "NGN"
        },
        "status": "pending",
        "created_at": "2026-05-20T12:00:00.000Z",
        "updated_at": "2026-05-20T12:00:00.000Z",
        "label": "Treasury deposit"
      }
    ],
    "created_at": "2026-05-20T12:00:00.000Z",
    "updated_at": "2026-05-20T12:00:00.000Z",
    "label": "USDC Operating Wallet"
  },
  "meta": {
    "request_id": "req_01HXYZ4K5ABCDEFGHJKLMNPQRS",
    "timestamp": "2026-05-14T15:43:55.732Z",
    "version": "1"
  }
}

Authorizations

Authorization

string

header

required

API key issued during merchant onboarding.

Path Parameters

walletId

string

required

Pattern: [^\/#\?]+?

Response

Wallet fetched successfully

status

enum<boolean>

required

Available options:

true

Example:

true

message

string

required

Human-readable summary

Example:

"Wallet fetched successfully"

code

enum<string>

required

Available options:

ok

Example:

"ok"

data

object

required

Show child attributes