Wallet Pregeneration (Beta)

Wallet Pregeneration (Beta)

#Overview

note

This feature is currently in beta. Please reach out for early access.

Magic offers Wallet Pregeneration, a feature that allows you to create non-custodial wallets programmatically without requiring end users to start or complete an authentication flow. After the wallet is generated, a user can claim their pregenerated wallet by authenticating through your application.

Neither Magic nor the developer can access the wallet's private key; it can only be accessed by the end user after claiming the wallet.

#Usage

#Create Wallet

You can make the API call below to pregenerate wallets.

  • POST Endpoint: https://api.magic.link/v1/api/wallet_pregen/create_wallets

Input Parameters

Request Headers

Request Body

  • identifiers: A list containing "identifier_payload" objects.

identifier_payload

  • identifier: A string representing the identifier (e.g., email address).
  • identifier_type: A string constant. For now, this should be set to "email_address".
Curl
01curl --request POST \
02  --url 'https://api.magic.link/v1/api/wallet_pregen/create_wallets' \
03  --header 'X-Magic-Secret-Key: <your_magic_secret_api_key>' \
04  --header 'Content-Type: application/json' \
05  --data '{
06    "identifiers": [
07      {
08⁠        "identifier": "user1@example.com",
09        "identifier_type": "email_address" 
10      },
11      {
12⁠        "identifier": "user2@example.com",
13        "identifier_type": "email_address" 
14      },
15      {
16⁠        "identifier": "user3@example.com",
17        "identifier_type": "email_address" 
18      },
19    ]
20  }'
21
22// Responds 200 OK with job_id
23{
24    "data": {
25        "job_id": "a622f0e5-2766-4e5d-bdf5-8c523ccc03a4"
26    },
27    "error_code": "",
28    "message": "",
29    "status": "ok"
30}

#Query Job Status

You can use this query to check which users have claimed their pregenerated wallet.

  • POST Endpoint: https://api.magic.link/v1/api/wallet_pregen/get_job_status

Input Parameters

Request Headers

Request Body

  • job_id: The returned UUID from create_wallets.
Curl
01curl --request POST \
02  --url 'https://api.magic.link/v1/api/wallet_pregen/get_job_status' \
03  --header 'X-Magic-Secret-Key: <your_magic_secret_api_key>' \
04  --header 'Content-Type: application/json' \
05  --data '{
06    "job_id": "91a5be54-61bf-4761-e89k-b7f35ace81d3"
07  }'
08
09// Responds 200 OK with job status object
10{
11    "data": {
12        "client_id": "A5cJpjmJk3eQq4PXC9uJuoWESlcD3_CIwZgvDVdY0wg=",
13        "created_at": 1716331284,
14        "expires_at": 1718923161,
15        "job_id": "91a5be54-61bf-4761-e89k-b7f35ace81d3",
16        "key_generation_stats": {
17            "errors": 0,
18            "processed": 1,
19            "total": 1
20        },
21        "status": "SUCCESS",
22        "updated_at": 1716331161
23    },
24    "error_code": "",
25    "message": "",
26    "status": "ok"
27}

#Query Wallet Identifiers

You can use this query to check which identifier (e.g., email address) is tied to a pregenerated wallet public address.

  • POST Endpoint: https://api.magic.link/v1/api/wallet_pregen/get_identifiers

Input Parameters

Request Headers

Request Body

  • job_id: The returned UUID from create_wallets.
  • claimed [optional]: JSON boolean, filters the result by claimed status.
  • limit [optional]: The maximum number of results to return.
Curl
01curl --request POST \
02  --url 'https://api.magic.link/v1/api/wallet_pregen/get_identifiers' \
03  --header 'X-Magic-Secret-Key: <your_magic_secret_api_key>' \
04  --header 'Content-Type: application/json' \
05  --data '{
06    "job_id": "91a5be54-61bf-4761-e89k-b7f35ace81d3",
07    "claimed": false, // optional
08    "limit": 10 // optional 
09  }'
10
11// Responds 200 OK with identifiers information
12{
13    "data": {
14        "identifiers": [
15            {
16                "claimed": false,
17                "expires_at": 1718925889,
18                "identifier": "youremail@example.com",
19                "identifier_type": "email_address",
20                "job_id": "91a5be54-61bf-4761-e89k-b7f35ace81d3",
21                "public_address": "0xBAcFD5E443eFDFECb9850a9d8a23C33701E66742",
22                "status": "success",
23                "status_detail": "Successfully generated wallet"
24            }
25        ],
26    },
27    "error_code": "",
28    "message": "",
29    "status": "ok"
30}