---
title: "Fund and pay out from a Nodu wallet"
description: "Learn how to move funds into a Nodu wallet with a transfer, how to pay out from a Nodu wallet, and what happens when its balance is too low."
url: "/guides/nodu-wallets/transfers-funded-from-a-wallet/"
index: "/llms.txt"
---

# Fund and pay out from a Nodu wallet

A Nodu wallet, which is a balance held at Nodu, can be the destination or the source of a transfer. A payout from a Nodu wallet differs from a transfer that the customer funds: Nodu takes the funds from the balance instead of waiting for the customer's payment. To create a Nodu wallet, see [Nodu wallet balances and scopes](/guides/nodu-wallets/balances-and-wallet-scopes/index.md).

## Before you start

A transfer with a Nodu wallet names a customer in `customerId`, like every transfer. [How transfers work](/guides/transfers/how-transfers-work/index.md#what-a-transfer-needs) lists what every transfer needs. This transfer also needs the following:

- **A Nodu wallet whose scope includes the customer.** A developer-scoped Nodu wallet serves any of your customers. A customer-scoped Nodu wallet serves its own customer only. For another customer, Nodu answers with the status `404`.
- **A payment channel on the rail `wallet`.** The customer's [payment channels](/guides/transfers/payment-channels/index.md) must include a channel with the rail `wallet` and the currency that you use with the Nodu wallet. When the Nodu wallet is the source, the payment channel direction is `payin`. When it is the destination, the direction is `payout`. Without this channel, Nodu answers with the status `404`.

## Move funds into a Nodu wallet

Call [Create a transfer](/api/tag/transfers/post-v1-transfers.md) with the Nodu wallet as the destination:

- `source`: the rail and the currency of the incoming payment, as in any transfer.
- `destination.walletId`: the `id` of the Nodu wallet.
- `destination.currency`: the currency to add to the Nodu wallet. It is required, because a Nodu wallet can hold several currencies.

For example, a customer sends USDC on Base, and Nodu adds it to the Nodu wallet:

```bash
curl https://api.sandbox.nodu.fi/v1/transfers \
  --header 'Authorization: Bearer <your-api-key>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <new-uuid>' \
  --data '{
    "customerId": "<customer-id>",
    "amount": "100.00",
    "source": {"paymentRail": "base", "currency": "usdc"},
    "destination": {"walletId": "<wallet-id>", "currency": "usdc"}
  }'
```

The transfer starts in `awaiting_funds`. The response includes `sourceDepositInstructions`. The customer pays as in any other transfer. When the transfer reaches `payment_processed`, the funds are in the Nodu wallet. A transfer into a Nodu wallet does not pass through `payment_submitted`.

## Pay out from a Nodu wallet

Call [Create a transfer](/api/tag/transfers/post-v1-transfers.md) with the Nodu wallet as the source:

- `source.paymentRail`: `wallet`.
- `source.walletId`: the `id` of the Nodu wallet.
- `source.currency`: the currency to take from the Nodu wallet.
- `destination.externalAccountId`: the external account that receives the payout, as in any transfer.

For example, Nodu takes EUR from the Nodu wallet and pays USDC to the customer's crypto wallet:

```bash
curl https://api.sandbox.nodu.fi/v1/transfers \
  --header 'Authorization: Bearer <your-api-key>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <new-uuid>' \
  --data '{
    "customerId": "<customer-id>",
    "amount": "100.00",
    "source": {"paymentRail": "wallet", "currency": "eur", "walletId": "<wallet-id>"},
    "destination": {"externalAccountId": "<external-account-id>"}
  }'
```

The rails and the currencies in both requests are examples. The ones that you can use depend on your integration agreement with Nodu.

To show the customer the amounts and the fees first, call [Create a quote](/api/tag/quotes/post-v1-quotes.md) with `wallet` as the `paymentRail` of the source: see [Quotes and exchange rates](/guides/transfers/quotes-and-exchange-rates/index.md).

## How a payout from a Nodu wallet differs

| What differs | A transfer that the customer funds | A transfer funded from a Nodu wallet |
|---|---|---|
| Deposit instructions | `sourceDepositInstructions` says where to pay. | None. The customer does not send a payment to fund the transfer. |
| Funding | Nodu waits for the payment to arrive. | Nodu takes `amount` from the `available` balance in the source currency. |
| Meaning of `awaiting_funds` | The payment has not arrived yet. | Nodu has not taken the funds yet. |

After Nodu takes the funds, follow the transfer's state as described in [Track and cancel a transfer](/guides/transfers/track-a-transfer/index.md). The transfer can enter `info_required`.

## When the balance is too low

Nodu does not refuse a transfer because the balance is too low. The transfer waits in `awaiting_funds` until the `available` balance in the source currency covers `amount`, or until you cancel the transfer.

- **Add funds and keep the same transfer.** Do not create a second transfer for the same payout. Creating a second transfer can result in two payouts once enough funds are available.
- **Expect waiting transfers to continue in order.** Transfers that wait on the same Nodu wallet continue oldest first. A large waiting transfer can delay later transfers.
- **Cancel a payout you no longer need.** Call [Cancel a transfer](/api/tag/transfers/delete-v1-transfers-transferid.md) and check the response: see [Track and cancel a transfer](/guides/transfers/track-a-transfer/index.md#cancel-a-transfer).

## Read the balance afterward

[Retrieve a wallet](/api/tag/wallets/get-v1-wallets-walletid.md) returns the balances of the Nodu wallet: see [Nodu wallet balances and scopes](/guides/nodu-wallets/balances-and-wallet-scopes/index.md#read-the-balances).

- While a payout is in progress, Nodu holds its amount in `reserved`.
- Use transfer events to trigger a fresh wallet retrieval and read the current balance.
- After a failed payout, read the balance before you use the funds for another payout.
- To list the transfers that use one Nodu wallet as their source or destination, call [List all transfers](/api/tag/transfers/get-v1-transfers.md) with `walletId`.

## Next steps

- [Track and cancel a transfer](/guides/transfers/track-a-transfer/index.md): follow a transfer to its outcome.
- [Relays: deposit instructions you can reuse](/guides/relays/index.md): send repeated incoming payments to a Nodu wallet.
- [Simulate funding in the sandbox](/guides/sandbox/simulate-funding/index.md): simulate the payment for a transfer into a Nodu wallet. A transfer that a Nodu wallet funds has no payment to simulate.
