Skip to main content

How it works

You will create a temporary “escrow” wallet where funds are held securely until claimed, and embed an authenticator with access to this wallet in a URL. When the new user clicks on the claim link, they will land directly in your app and see a wallet that’s already been topped up with crypto from an existing user. You can view an example of the feature below:

Implementation guide

Step 1: Set up your application: Before you start building this feature, ensure:
  • Your organization is set up with embedded wallets in a sub-organization model: Each of your users should map to a dedicated sub-org in Turnkey.
  • Email authentication is enabled so that new users can sign up through a secure email flow.
  • Your backend can store mapping records between transactions and sub-organizations
Step 2: The Sender initiates the flow When an existing user (the “Sender”) wants to send funds to someone new, here’s what needs to happen:
1

Create a temporary sub-org

This sub-org acts as the escrow environment. It will: 
  • Contain a new “escrow” wallet 
  • Contain a root user with two authenticators: 
    • The Sender’s email or phone number, included so that they can reclaim funds later on if necessary. 
    • A programmatically generated API key (“Claim Key”). This key will later be passed to the Receiver via a claim link. 
2

Initialize transfer of funds

Initiate the transfer of funds from the Sender’s primary wallet to this new escrow wallet. 
3

Create and store Tx record

For added security, store a transaction record in your backend that maps a transaction id to this temporary sub-org id.  
You can take all of these actions via a session to ensure the user experience is as simple as setting an amount and copying a link to send.
Step 3: Generate and share the claim link
1

Create your claim link

Construct a link containing:
  • The transaction id, as a path segment or query parameter
  • The Base64-encoded private key from the Claim Key, in the URL fragment (after #), for example https://app.example.com/claim/<TX_ID>#key=<CLAIM_KEY>
Never put the Claim Key in a query parameter or path. Browsers send those to your server, so the key would end up in server, proxy, and analytics logs. The fragment stays in the browser: read it with window.location.hash, and do not send it to your backend.
You can now show the Sender a “Copy link” or “Share via…” button. Until the funds are claimed, anyone who has the link can claim them, so treat it like cash.
For larger amounts, consider requiring a passphrase as well as the link. Encrypt the Claim Key with a key derived from a passphrase (for example with PBKDF2 or Argon2, then AES-GCM), and put the ciphertext in the fragment instead of the raw key. The Sender shares the passphrase over a different channel from the link, such as the link by email and the passphrase in person or by text message, so a forwarded or leaked link is not enough to claim the funds. Use a strong passphrase, such as several random words, not a short PIN: anyone who has the link can try passphrases offline, with no limit on attempts.
Step 4: Receiver claims funds When the Receiver opens the link in your app:
1
Your app parses the transaction id and looks up the associated temporary sub-org ID
2

Reconstruct claim key

Reconstruct the Claim Key using the private key from the URL fragment and store it in local storage. Now, the Receiver has an API key in local storage that grants them the ability to send funds out of the escrow wallet. Then remove the fragment from the address bar with history.replaceState, so the key is not left visible or copied along with the URL.
3

Create permanent sub-org

Guide the Receiver through your typical signup flow to create a permanent sub-organization containing a new permanent wallet (“Receiver Wallet”) and permanent authenticators. 
4

Use claim key to authorize fund transfer

Use the Claim Key in local storage to authorize transferring the claimable funds from the escrow wallet to the Receiver Wallet. 
5

Delete temporary sub-org

After successful transfer, delete the temporary sub-org using the Claim Key, then remove the Claim Key from local storage.
The receiver now controls their own wallet under a permanent sub-org which contains the new funds. If the funds are never claimed or the Sender wishes to revoke the gift for any reason, your app can allow the sender to reclaim them by using their email or phone number to restart a new session for the escrow sub-organization.