Skip to main content

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 cryptoWhat 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 customerRegister 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.

warning

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.

  1. Find the exchange or custodian. See Find an exchange or custodian.
  2. Create the external account. Call Create an external account with selfOwned=true, the paymentRail and the currency of the transfer's source, and accountRequisites: the address of the crypto wallet as wallet, walletType=hosted, and the vaspId of the exchange or custodian when you know it.
  3. Create the transfer. Send the id of the external account as source.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​

  1. Get the requirements for the originator side. Call Get external account requirements with the customerId, the currency and the rail of the transfer's source, the counterpartyType of the originator, and side=originator.
  2. Collect the originator's details. See The originator's details.
  3. Create the external account. Call Create an external account with selfOwned=false, the counterparty, the paymentRail, the currency and the accountRequisites. Send supportedSides=["originator"]. If you will also use the external account for payouts to the originator, send both beneficiary and originator: the beneficiary side requires the address in accountRequisites.wallet. Without supportedSides, Nodu validates the account for the beneficiary side only.
  4. Create the transfer. Call Create a transfer with the id of the external account in source.externalAccountId. Add a payment message in destination.message. Example requests shows steps 3 and 4.
  5. 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:

  • supportedSides replaces 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 counterparty belong 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​