​
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. Returns the recovery_key, access_key, and wallet uuid for future operations.
cURL
curl -X POST 'https://tee.magiclabs.com/v1/api/wallet' \
  -H 'Content-Type: application/json' \
  -H 'x-magic-secret-key: sk_live_XXXXXXXX' \
  -d '{
    "encryption_context": "hashed_passcode",
    "network": "mainnet",
    "wallet_group_id": "58a08494-3c83-439a-8a07-551f2022c3fc",
    "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-551f2022c3fc",
    "metadata": {
      "resource_id": "customer-resource-id"
    },
    "key_type": "CORE",
    "public_address": "0x797063FB2e3C31a8b9a10D7EDF6dE612d6aE7Fde",
    "recovery_key": "3130cc5b8fb4c5a835067f8c1aba3872",
    "access_key": "ebf0e16c5c22cd734083c803562b5dc0"
  }
}

​
Request Parameters

​
encryption_context
string
required
Body
The context used to encrypt key shards. Should be derived from user input (e.g., hashed passphrase).
​
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 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 for all subsequent operations.
​
data.public_address
string
The wallet’s public address on the specified network.
​
data.recovery_key
string
Key shard for wallet recovery. Store securely in your database.
​
data.access_key
string
Key shard for non-recovery operations. Store securely in your database.
Store both recovery_key and access_key securely in your database. These are required for wallet operations and recovery.