Developer Docs

Wallet Groups

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

Wallet group endpoints are currently on /v1/. They are unaffected by the v1-to-v2 migration.

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

string

Body

Optional identifier for the wallet group. Useful for organizing wallets by customer, project, or environment.

Response Fields

string

Unique identifier for the created wallet group. Use this when creating wallets.

integer

Unix timestamp (UTC) when the wallet group was created.

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

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

string

required

Body

The user’s JWT from your identity provider. The enclave binds the wallet to this identity at creation time.

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.

string

Body

UUID of the wallet group to organize this wallet under.

string

Body

Optional identifier for the wallet (e.g., user ID, customer ID).

Response Fields

string

Unique wallet identifier. Use this as wallet_id for all subsequent operations.

string

The wallet’s public address on the specified network.

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.

Server Wallets

Express API

Core API

Wallet Operations

Wallet Groups

Create Wallet Group

Request Parameters

Response Fields

List Wallet Groups

Response Fields

Wallet Management

Create Wallet

Request Parameters

Response Fields

​Wallet Groups

​Create Wallet Group

​Request Parameters

​Response Fields

​List Wallet Groups

​Response Fields

​Wallet Management

​Create Wallet

​Request Parameters

​Response Fields

Wallet Groups

Create Wallet Group

Request Parameters

Response Fields

List Wallet Groups

Response Fields

Wallet Management

Create Wallet

Request Parameters

Response Fields