Declare who sends incoming crypto
The originator is the person or business that sends the crypto that funds a transfer. You register the originator's crypto wallet as an external account, and you name it in the transfer: a first-party external account for the customer's own wallet at an exchange or custodian, or a third-party external account for someone else's crypto wallet. Travel Rule: what Nodu needs to know, and why explains why Nodu needs to know the originator.
Incoming bank payments need no originator declaration.
When you declare an originator
| Who sends the crypto | What you do |
|---|---|
| The customer, from a self-custody wallet (unhosted) | Register nothing, and leave source.externalAccountId out of the transfer. Nodu can ask the customer to prove that they control this crypto wallet: see Self-custody wallets (unhosted). |
| The customer, from a wallet at an exchange or custodian (hosted) | Register the crypto wallet as a first-party external account, and name it in source.externalAccountId. See The customer's own wallet at an exchange or custodian. |
| Someone else, such as a buyer who pays the customer | Register the originator's crypto wallet as a third-party external account on the originator side, whether it is hosted or self-custody. See Someone else's crypto wallet. |
The originator side is the role of an external account that sends money. External accounts and counterparties explains the two sides.
A transfer without source.externalAccountId has no declared originator. See What happens without a declaration for how Nodu checks incoming crypto in this case.
If someone other than the customer sends the crypto, declare that originator when you create the transfer. Update a transfer changes the amount and your fee only.
The customer's own wallet at an exchange or custodian
The customer is the originator, so Nodu needs no details of a counterparty. It needs to know where the crypto wallet is held: Wallets at an exchange or custodian (hosted) explains why.
- Find the exchange or custodian. See Find an exchange or custodian.
- Create the external account. Call Create an external account with
selfOwned=true, thepaymentRailand thecurrencyof the transfer's source, andaccountRequisites: the address of the crypto wallet aswallet,walletType=hosted, and thevaspIdof the exchange or custodian when you know it. - Create the transfer. Send the
idof the external account assource.externalAccountId.
curl https://api.sandbox.nodu.fi/v1/external-accounts \
--header 'Authorization: Bearer <your-api-key>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <new-uuid>' \
--data '{
"customerId": "019634b8-f479-7001-84ce-2e15ced821e2",
"selfOwned": true,
"paymentRail": "ethereum",
"currency": "usdc",
"accountRequisites": {
"wallet": "0x742d35cc6634c0532925a3b844bc9e7595f0beb1",
"walletType": "hosted",
"vaspId": "019634b8-f479-7001-84ce-2e15ced821e4"
}
}'
You can use the same external account for payouts to this crypto wallet, in destination.externalAccountId.
Someone else's crypto wallet
When someone other than the customer sends the crypto, register the originator's crypto wallet as a third-party external account on the originator side.
The originator's details
The originator is the counterparty of the external account: the person or business that owns it. The originator side needs more details about the counterparty than the beneficiary side.
The exact fields depend on the Nodu entity you integrate with. Get external account requirements returns them for your customer. The response can offer two alternative sets of identity fields with required=false. You need to supply one of the two sets. See the identity alternatives in the rail requirements guide.
- An individual. Typical details include the name, the full address and identity information, such as an identity document number or a date of birth.
- A business. Typical details include the company name, the full address and the registration number.
Steps
- Get the requirements for the originator side. Call Get external account requirements with the
customerId, thecurrencyand therailof the transfer's source, thecounterpartyTypeof the originator, andside=originator. - Collect the originator's details. See The originator's details.
- Create the external account. Call Create an external account with
selfOwned=false, thecounterparty, thepaymentRail, thecurrencyand theaccountRequisites. SendsupportedSides=["originator"]. If you will also use the external account for payouts to the originator, send bothbeneficiaryandoriginator: the beneficiary side requires the address inaccountRequisites.wallet. WithoutsupportedSides, Nodu validates the account for the beneficiary side only. - Create the transfer. Call Create a transfer with the
idof the external account insource.externalAccountId. Add a payment message indestination.message. Example requests shows steps 3 and 4. - Pass on the deposit instructions. The transfer returns the deposit address in
sourceDepositInstructions. The originator sends the crypto to that address.
For later transfers from the same crypto wallet, reuse the external account. Create a transfer lists the conditions that the external account in source.externalAccountId must meet.
Example requests
This request registers an originator who is an individual and holds the crypto wallet at an exchange. The values are examples. The counterparty fields that your customer needs come from the requirements of step 1.
curl https://api.sandbox.nodu.fi/v1/external-accounts \
--header 'Authorization: Bearer <your-api-key>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <new-uuid>' \
--data '{
"customerId": "019634b8-f479-7001-84ce-2e15ced821e2",
"selfOwned": false,
"counterparty": {
"type": "individual",
"firstName": "Alice",
"lastName": "Nowak",
"dateOfBirth": "1990-04-12",
"placeOfBirth": "Warsaw, PL",
"address": {
"country": "PL",
"addressLine1": "Ul. Marszalkowska 1",
"city": "Warsaw",
"postalCode": "00-001"
}
},
"paymentRail": "ethereum",
"currency": "usdc",
"accountRequisites": {
"wallet": "0x742d35cc6634c0532925a3b844bc9e7595f0beb1",
"walletType": "hosted",
"vaspId": "019634b8-f479-7001-84ce-2e15ced821e4"
},
"supportedSides": ["originator"]
}'
This request creates a transfer that the originator funds. The source has the rail and the currency of the originator's external account. The destination is the customer's own bank account.
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": "019634b8-f479-7001-84ce-2e15ced821e2",
"amount": "250.00",
"source": {
"paymentRail": "ethereum",
"currency": "usdc",
"externalAccountId": "019ab6d8-dd85-777f-9d40-247ba54388f5"
},
"destination": {
"externalAccountId": "019ab6e1-4c2a-7d3e-9f10-6b7c8d9e0a12",
"message": "Payment for invoice 2041"
}
}'
The originator's crypto wallet
On a third-party account's originator side, accountRequisites.wallet is optional because you may not know the sending address before the crypto arrives. If you supply a self-custody address, use the address that the originator sends from. The beneficiary side requires an address.
Describe where the crypto wallet is held using the crypto wallet custody fields.
Use a crypto wallet registered earlier
An external account that you registered earlier, for example for payouts, can lack what the originator side needs: the side itself, where the crypto wallet is held, or details of the counterparty. You do not need a new external account. Add what is missing with Update an external account:
curl --request PATCH 'https://api.sandbox.nodu.fi/v1/external-accounts/<external-account-id>' \
--header 'Authorization: Bearer <your-api-key>' \
--header 'Content-Type: application/json' \
--data '{
"accountRequisites": {"walletType": "hosted", "vaspId": "<vasp-id>"},
"counterparty": {
"dateOfBirth": "1990-04-12",
"placeOfBirth": "Warsaw, PL"
},
"supportedSides": ["beneficiary", "originator"]
}'
Each part of the request is optional. The rules:
supportedSidesreplaces the recorded sides. Send every side that the external account must keep. Nodu checks the external account against the requirements of each side. If a requirement is not met, Nodu refuses the request with a validation error that lists the missing fields.- The details in
counterpartybelong to the counterparty. Every external account of that counterparty receives them. Details that you do not send stay as they are. You cannot change the type or the names of the counterparty. - For the rules on changing custody, see Declare an existing crypto wallet.
Next steps
- Travel Rule: what Nodu needs to know, and why: what Nodu needs for each kind of crypto wallet.
- Handle the
info_requiredstate: what to do when Nodu asks for a proof. - Simulate funding in the sandbox: simulate the incoming crypto and choose the sending address.