Nodu wallets: balances and wallet scopes
A Nodu wallet is a balance held at Nodu, in one or more currencies. A transfer 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.
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. Each payment channel 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
- Choose the scope. For a developer-scoped Nodu wallet, leave out
customerId. For a customer-scoped Nodu wallet, send theidof the customer incustomerId. - Choose a
nameof up to 25 characters. Optionally, include your own identifier inclientReferenceId. It must be unique among your Nodu wallets. - Call Create a wallet with these fields and an
Idempotency-Keyheader: see Idempotency. - Store the
idfrom the response. You send it aswalletIdwhen you create a transfer.
A developer-scoped Nodu wallet:
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:
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 returns the Nodu wallet with its balances. The array has one entry for each currency:
"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 returns your Nodu wallets with their balances. You can filter the list by customerId or by clientReferenceId. The list is paginated: see Pagination.
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.
Next steps
- Fund and pay out from a Nodu wallet: move funds into a Nodu wallet and pay out from it.
- Relays: deposit instructions you can reuse: send repeated incoming payments to a Nodu wallet.
- Payment channels: check a customer's channels with
paymentRail=wallet. - Simulate funding in the sandbox: add test funds to a Nodu wallet.