Skip to main content

Simulate crypto wallet verification in the sandbox

Nodu can ask a customer to prove that they control a crypto wallet used in a transfer. The transfer then waits in the state info_required. In the sandbox, Nodu's test environment, you resolve that state with an API call, or with a real proof paid in testnet coins.

When the requirement appears​

Follow the self-custody proof conditions. Two sandbox differences make the flow testable:

CheckSandbox behavior
Transfer amountNo amount threshold: an unverified self-custody wallet belonging to the customer needs proof regardless of the transfer amount.
Hosted declarationA wallet declared with walletType=hosted is confirmed. Production checks the declaration with the exchange or custodian.

The check runs after funding. Simulate funding, then retrieve the transfer's requirements.

Produce the requirement​

For the sending crypto wallet​

  1. Create a transfer with a blockchain rail as the source. Do not send source.externalAccountId. Nodu then treats the sending crypto wallet as the customer's own.
  2. Call Simulate funding for a transfer. To choose the sending address, send remitter.requisites.wallet. Without it, the sandbox generates a new address.
  3. Wait for the v1.transfer.info_required event, or call Retrieve a transfer until state=info_required. The requirements list then has an item with side=source.

For the receiving crypto wallet​

  1. Register the customer's own crypto wallet as a first-party external account, with selfOwned=true. Do not set walletType=hosted.
  2. Create a transfer that pays out to this external account. Simulate its funding.
  3. When state=info_required, the requirements list has an item with side=destination.

If the transfer continues without a requirement, check the conditions above. For a source requirement, simulate a new transfer funded from a new sending address. For a destination requirement, register a different destination address and create a new transfer to it.

Test both sides​

Create a crypto-to-crypto transfer using a new self-custody address on each side. Simulate funding, retrieve the transfer and resolve one pending side. Retrieve it again even if the state remains info_required: the other requirement can appear without a new state event. Resolve that side and check that the transfer resumes.

Resolve the requirement​

You resolve the requirement in one of two ways: simulate the proof with an API call, or give a real proof with testnet coins.

Simulate the proof​

Read the requirement in the transfer. Call Retrieve a transfer. In the response, the requirements list says which side needs the proof. An excerpt:

{
"state": "info_required",
"requirements": [
{
"id": "0196a1f2-7c3e-7b10-9d4e-5a2b8c6f1e03",
"action": "verify_wallet_ownership",
"side": "source",
"url": "https://customer.nodu.fi/wallet-verification/019657d0-c6c4-7947-94ec-42c4164cd51e"
}
]
}

Then call Simulate a wallet verification with the id of the transfer and the side of the requirement:

curl https://api.sandbox.nodu.fi/v1/transfers/<transfer-id>/simulate-wallet-verification \
--header 'Authorization: Bearer <your-api-key>' \
--header 'Content-Type: application/json' \
--data '{"side": "source"}'

Nodu records a proof of ownership for the crypto wallet, as if the customer had given it. The response has the status 204 and no body. The operation works in the sandbox only.

  • side is optional. Its values are source and destination. Without it, Nodu uses the side that has a pending requirement. If both sides have a pending requirement, or neither side has one, you must send side. If you omit side in either case, Nodu refuses the request with rule=wallet_verification_side_required. Without side, you can also leave out the body.
  • The simulated proof is accepted. Nodu records it as a successful proof.
  • A repeated call changes nothing. A second call for the same crypto wallet also answers 204.
  • You can record a proof in advance. Send side before the requirement appears. For source, simulate the funding first: Nodu learns the sending address when the funds arrive.

Give a real proof with testnet coins​

You can also go through the flow that the customer sees in production. Open the url of the requirement and follow the page. It asks for a test transaction from the crypto wallet. In the sandbox, the test transaction can be paid in testnet coins:

Blockchain networkTestnet coin
EthereumSepolia ETH
BaseBase Sepolia ETH

You can only send a test transaction from a crypto wallet that you control. For the sending side, choose its address when you simulate the funding: send it in remitter.requisites.wallet. See Simulate funding in the sandbox.

Testnet coins work for the proof of ownership only. Coins sent to the deposit instructions of a sandbox transfer do not fund it.

What the transfer does next​

  • The item leaves the requirements list.
  • When no other requirement is pending, the transfer returns to in_review. Nodu sends the event v1.transfer.in_review. The transfer then continues without an API call from you.
  • When the other side also needs proof of ownership, the transfer stays in info_required. Resolve the second requirement in the same way.

Nodu remembers a simulated proof for the customer and the address, as it remembers a real proof. Later test transfers for this customer using the same address do not require proof of ownership again. To produce the requirement again, use another address.

Next steps​