Skip to main content

​
Wallet Groups

Wallet groups allow you to logically organize wallets for better management and organization.

​
Create Wallet Group

Creates a new wallet group for organizing wallets.
cURL
curl -X POST 'https://tee.magiclabs.com/v1/api/wallet_group' \
  -H 'Content-Type: application/json' \
  -H 'x-magic-secret-key: sk_live_XXXXXXXX' \
  -d '{
    "metadata": {
      "resource_id": "customer-resource-id"
    }
  }'
Response: 
{
  "data": {
    "uuid": "7313a996-eb9c-4568-acef-f622a6b151fd",
    "time_created": 1709931542,
    "time_updated": 1709931542,
    "metadata": {
      "resource_id": "customer-resource-id"
    }
  }
}

​
Request Parameters

​
metadata.resource_id
string
Body
Optional identifier for the wallet group. Useful for organizing wallets by customer, project, or environment.

​
Response Fields

​
data.uuid
string
Unique identifier for the created wallet group. Use this when creating wallets.
​
data.time_created
integer
Unix timestamp (UTC) when the wallet group was created.
​
data.time_updated
integer
Unix timestamp (UTC) when the wallet group was last updated.

​
List Wallet Groups

Retrieve all wallet groups for your application.
cURL
curl -X GET 'https://tee.magiclabs.com/v1/api/wallet_groups' \
  -H 'x-magic-secret-key: sk_live_XXXXXXXX'
Response: 
{
  "data": [
    {
      "uuid": "7313a996-eb9c-4568-acef-f622a6b151fd",
      "time_created": 1709931542,
      "time_updated": 1718035165,
      "metadata": {
        "resource_id": "customer-resource-id"
      }
    }
  ]
}

​
Response Fields

​
data
array
Array of wallet group objects, each containing the same fields as the create response.

​
Wallet Management

​
Create Wallet

Create a new wallet for a user. In v2, the wallet is cryptographically bound to the user’s identity via auth_jwt. Returns an access_key that you must store securely for all subsequent operations.
cURL
curl -X POST 'https://tee.magiclabs.com/v2/api/wallet' \
  -H 'Content-Type: application/json' \
  -H 'x-magic-secret-key: sk_live_XXXXXXXX' \
  -d '{
    "auth_jwt": "eyJhbGciOiJSUzI1NiIsImtpZCI6ImFiYzEyMyIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2F1dGgueW91cmFwcC5jb20iLCJzdWIiOiJ1c2VyXzEyMzQ1NiIsImF1ZCI6Imh0dHBzOi8vdGVlLm1hZ2ljbGFicy5jb20iLCJpYXQiOjE3NTE2NzIwMDAsImV4cCI6MTc1MTY3MjMwMH0.SIGNATURE",
    "network": "mainnet",
    "wallet_group_id": "58a08494-3c83-439a-8a07-551f20xxxxxx",
    "metadata": {
      "resource_id": "customer-resource-id"
    }
  }'
Response: 
{
  "data": {
    "uuid": "e982b4a3-14d3-4d66-a3ac-fadfc3ae1875",
    "time_created": 1709931542,
    "time_updated": null,
    "network": "mainnet",
    "wallet_group_id": "58a08494-3c83-439a-8a07-551f20xxxxxx",
    "metadata": {
      "resource_id": "customer-resource-id"
    },
    "key_type": "CORE",
    "public_address": "0x797063FB2e3C31a8b9a10D7EDF6dE612d6aE7Fde",
    "access_key": "ebf0e16c5c22cd734083c803562b5dc0"
  },
  "wallet_id": "e982b4a3-14d3-4d66-a3ac-fadfc3ae1875",
  "wallet_address": "0x797063FB2e3C31a8b9a10D7EDF6dE612d6aE7Fde"
}

​
Request Parameters

​
auth_jwt
string
required
Body
The user’s JWT from your identity provider. The enclave binds the wallet to this identity at creation time.
​
network
string
required
Body
Target blockchain network. Values: BTC_MAINNET, BTC_TESTNET, BTC_REGTEST for Bitcoin; SOL_MAINNET, SOL_TESTNET for Solana; all other values create an EVM wallet.
​
wallet_group_id
string
Body
UUID of the wallet group to organize this wallet under.
​
metadata.resource_id
string
Body
Optional identifier for the wallet (e.g., user ID, customer ID).

​
Response Fields

​
data.uuid
string
Unique wallet identifier. Use this as wallet_id for all subsequent operations.
​
data.public_address
string
The wallet’s public address on the specified network.
​
data.access_key
string
Key shard required for all signing and key-reveal operations. Store securely in your database.
Store access_key securely in your database. Unlike v1, v2 wallets do not have a recovery_key — recovery is handled via your identity provider’s JWT.