---
title: "Nodu wallets: balances and wallet scopes"
description: "Learn what a Nodu wallet is, how to create one, what its scope allows, and how to read its balances."
url: "/guides/nodu-wallets/balances-and-wallet-scopes/"
index: "/llms.txt"
---

# Nodu wallets: balances and wallet scopes

A Nodu wallet is a balance held at Nodu, in one or more currencies. A [transfer](/guides/transfers/how-transfers-work/index.md) can add funds to it or draw from it. When you create the wallet, its scope decides which customers' transfers it can serve. You read its balances through the API.

The availability of Nodu wallets depends on your integration agreement with Nodu.

## What a Nodu wallet holds

A Nodu wallet is a balance, not a crypto wallet or a bank account. Funds enter and leave it through transfers: see [Fund and pay out from a Nodu wallet](/guides/nodu-wallets/transfers-funded-from-a-wallet/index.md).

One Nodu wallet can hold several currencies at the same time: for example, `eur` and `usdc`. The currencies that you can use depend on your integration agreement with Nodu. To find them for a customer, call [List payment channels](/api/tag/customers/get-v1-customers-customerid-payment-channels.md). Each [payment channel](/guides/transfers/payment-channels/index.md) with `paymentRail=wallet` names one currency. The `status` of these payment channels is `active`. You do not need to activate them.

## Scopes of a Nodu wallet

The scope says whose transfers a Nodu wallet can fund. The API reference names two scopes:

- **Developer-scoped.** The Nodu wallet is attached to your company. It can fund transfers for any of your customers.
- **Customer-scoped.** The Nodu wallet is attached to one customer. It can fund transfers for that customer only.

You set the scope when you create the Nodu wallet. You cannot change it afterward. The availability of each scope depends on your integration agreement with Nodu.

## Create a Nodu wallet

1. Choose the scope. For a developer-scoped Nodu wallet, leave out `customerId`. For a customer-scoped Nodu wallet, send the `id` of the customer in `customerId`.
2. Choose a `name` of up to 25 characters. Optionally, include your own identifier in `clientReferenceId`. It must be unique among your Nodu wallets.
3. Call [Create a wallet](/api/tag/wallets/post-v1-wallets.md) with these fields and an `Idempotency-Key` header: see [Idempotency](/guides/api-basics/idempotency/index.md).
4. Store the `id` from the response. You send it as `walletId` when you create a transfer.

A developer-scoped Nodu wallet:

```bash
curl https://api.sandbox.nodu.fi/v1/wallets \
  --header 'Authorization: Bearer <your-api-key>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <new-uuid>' \
  --data '{
    "name": "Treasury wallet",
    "clientReferenceId": "client_wallet_id_123"
  }'
```

A customer-scoped Nodu wallet:

```bash
curl https://api.sandbox.nodu.fi/v1/wallets \
  --header 'Authorization: Bearer <your-api-key>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <new-uuid>' \
  --data '{
    "name": "Alice Smith wallet",
    "customerId": "<customer-id>"
  }'
```

A new Nodu wallet has `status=active` and an empty `balances` array.

If your integration agreement with Nodu does not include Nodu wallets of this scope, Nodu answers with the status `403` and the code `feature_not_enabled`.

## Read the balances

[Retrieve a wallet](/api/tag/wallets/get-v1-wallets-walletid.md) returns the Nodu wallet with its `balances`. The array has one entry for each currency:

```json
"balances": [
  {"currency": "eur", "current": "1000.00", "reserved": "50.00", "available": "950.00"},
  {"currency": "usdc", "current": "500.00", "reserved": "0.00", "available": "500.00"}
]
```

| Field | Meaning |
|---|---|
| `currency` | The currency code in lower case, such as `eur`. |
| `current` | The balance, including the reserved amount. |
| `reserved` | The part of the balance that Nodu holds for transfers in progress. |
| `available` | `current` minus `reserved`. A new transfer can use this amount. |

- The amounts are decimal strings.
- A currency that the Nodu wallet has not held yet can be absent from `balances`. Treat it as a balance of zero.
- A response shows the balances at the time of the request. Transfers in progress can change them afterward.
- To follow a balance, follow the transfers that use the Nodu wallet. Then retrieve it again.

[List all wallets](/api/tag/wallets/get-v1-wallets.md) returns your Nodu wallets with their balances. You can filter the list by `customerId` or by `clientReferenceId`. The list is paginated: see [Pagination](/guides/api-basics/pagination/index.md).

## Statuses of a Nodu wallet


| `status` | Meaning | What you do |
|---|---|---|
| `active` | You can use the Nodu wallet for transfers. | Nothing. |
| `suspended` | The Nodu wallet is temporarily suspended. | Do not create new transfers with this Nodu wallet. Wait for the event `v1.wallet.activated`. |
| `closed` | The Nodu wallet is closed. You can no longer use it. | Use another Nodu wallet. |

Nodu sends an event when a Nodu wallet is created and when its status changes: `v1.wallet.created`, `v1.wallet.activated`, `v1.wallet.suspended` and `v1.wallet.closed`. Each event carries the `wallet` without its `balances`. An event is a notification, not the current state: see [Receive and verify webhooks](/guides/api-basics/webhooks/index.md#event-types).

## Next steps

- [Fund and pay out from a Nodu wallet](/guides/nodu-wallets/transfers-funded-from-a-wallet/index.md): move funds into a Nodu wallet and pay out from it.
- [Relays: deposit instructions you can reuse](/guides/relays/index.md): send repeated incoming payments to a Nodu wallet.
- [Payment channels](/guides/transfers/payment-channels/index.md): check a customer's channels with `paymentRail=wallet`.
- [Simulate funding in the sandbox](/guides/sandbox/simulate-funding/index.md): add test funds to a Nodu wallet.
