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:
| Check | Sandbox behavior |
|---|---|
| Transfer amount | No amount threshold: an unverified self-custody wallet belonging to the customer needs proof regardless of the transfer amount. |
| Hosted declaration | A 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
- 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. - Call Simulate funding for a transfer. To choose the sending address, send
remitter.requisites.wallet. Without it, the sandbox generates a new address. - Wait for the
v1.transfer.info_requiredevent, or call Retrieve a transfer untilstate=info_required. Therequirementslist then has an item withside=source.
For the receiving crypto wallet
- Register the customer's own crypto wallet as a first-party external account, with
selfOwned=true. Do not setwalletType=hosted. - Create a transfer that pays out to this external account. Simulate its funding.
- When
state=info_required, therequirementslist has an item withside=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.
sideis optional. Its values aresourceanddestination. 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 sendside. If you omitsidein either case, Nodu refuses the request withrule=wallet_verification_side_required. Withoutside, 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
sidebefore the requirement appears. Forsource, 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 network | Testnet coin |
|---|---|
| Ethereum | Sepolia ETH |
| Base | Base 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
requirementslist. - When no other requirement is pending, the transfer returns to
in_review. Nodu sends the eventv1.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
- Handle the
info_requiredstate: what you show the customer, and what happens when Nodu refuses the verification. - Self-custody wallets (unhosted): when Nodu asks for proof of ownership, and what Nodu remembers.
- Errors and rule codes: the rules that the simulation returns, marked "Sandbox only".