---
name: gdex-wallet-setup-ccb98ff516db
description: Generate EVM control wallets offline, create session keypairs, get wallet info — first step for users without wallets
---

# GDEX: Wallet Setup

Generate EVM control wallets for new users and session keypairs for managed-custody trading. Wallet generation is fully offline — no network or auth required.

## When to Use

- A user says they don't have a wallet
- Setting up a new user for the first time
- Generating session keypairs for managed-custody trading
- Querying wallet info on a specific chain

## Prerequisites

```bash
npm install @gemachdao/gdex-skill
```

No authentication needed for wallet generation.

## Generate an EVM Control Wallet

```typescript
import { generateEvmWallet } from '@gemachdao/gdex-skill';

const wallet = generateEvmWallet();
console.log('Address:', wallet.address);        // public — safe to display
console.log('Private Key:', wallet.privateKey);  // SECRET — store securely
console.log('Mnemonic:', wallet.mnemonic);       // SECRET — 12-word backup phrase

// wallet.type         → 'evm'
// wallet.derivationPath → "m/44'/60'/0'/0/0"
```

**Important:**
- Works fully offline — no network or API calls
- The private key and mnemonic must be stored securely
- Never log, display in UI, or transmit the private key
- The EVM control wallet is all you need — after managed-custody sign-in, the backend provisions Solana + other chain wallets automatically

## Generate a Session Keypair

Session keypairs (secp256k1) are used to sign trades after the initial control-wallet sign-in:

```typescript
import { generateGdexSessionKeyPair } from '@gemachdao/gdex-skill';

const { sessionPrivateKey, sessionKey } = generateGdexSessionKeyPair();
// sessionPrivateKey: hex string (store securely, reuse across requests)
// sessionKey: compressed public key (0x + 66 hex chars)
```

## Get Wallet Info

Managed-wallet native balance and token count on one chain. This is an
authenticated managed read (`/v1/user` + `/v1/portfolio` with `userId`, the
encrypted session `data` and `chainId`); GDEX has no address-only balance read:

```typescript
import { GdexSkill, GDEX_API_KEY_PRIMARY } from '@gemachdao/gdex-skill';

const skill = new GdexSkill();
skill.loginWithApiKey(GDEX_API_KEY_PRIMARY);

const info = await skill.getWalletInfo({
  walletAddress: '0xYourControlWallet',   // the GDEX userId
  sessionPrivateKey,                      // from sign-in (or pass `data`)
  apiKey: GDEX_API_KEY_PRIMARY,
  chain: 1,   // Ethereum
});
```

MCP: `get_wallet_info` takes `accountRef` (from `gdex_connect`) instead of the raw keys.

### Wallet Info Response

```typescript
interface WalletInfo {
  address: string;         // managed trading wallet on this chain
  userId: string;          // control wallet
  chain: number;           // normalized numeric chain id
  chainId: number;
  nativeBalance: string;   // whole units, approximate (backend float)
  nativeSymbol: string;    // 'ETH', 'SOL', 'SUI', etc.
  precision: 'approximate';
  totalValueUsd?: string;
  tokenCount: number;
}
```

## Full New User Onboarding Flow

```typescript
import {
  generateEvmWallet,
  generateGdexSessionKeyPair,
  buildGdexSignInMessage,
  buildGdexSignInComputedData,
  GdexSkill,
  GDEX_API_KEY_PRIMARY,
} from '@gemachdao/gdex-skill';

// Step 1: Generate a control wallet (offline)
const wallet = generateEvmWallet();
console.log('Your new wallet address:', wallet.address);
// ⚠️ Tell user to save privateKey and mnemonic securely!

// Step 2: Generate session keypair
const { sessionPrivateKey, sessionKey } = generateGdexSessionKeyPair();

// Step 3: Initialize SDK
const skill = new GdexSkill();
skill.loginWithApiKey(GDEX_API_KEY_PRIMARY);

// Step 4: Build sign-in message and sign with the new wallet
const userId = wallet.address;
const nonce = String(Math.floor(Date.now() / 1000) + Math.floor(Math.random() * 1000));
const message = buildGdexSignInMessage(userId, nonce, sessionKey);

// For a generated wallet, sign directly with ethers:
import { ethers } from 'ethers';
const signer = new ethers.Wallet(wallet.privateKey);
const signature = await signer.signMessage(message);

// Step 5: Sign in via managed custody
const signInPayload = buildGdexSignInComputedData({
  apiKey: GDEX_API_KEY_PRIMARY,
  userId,
  sessionKey,
  nonce,
  signature,
});
await skill.signInWithComputedData({
  computedData: signInPayload.computedData,
  chainId: 1,  // EVM
});

// ✅ User is now authenticated and can trade
// The backend has provisioned Solana + other chain wallets automatically
```

## Autonomous Agent Notes (Live-Tested)

1. **`generateEvmWallet()` works fully offline (E2E verified).** No network calls needed. Returns `{ address, privateKey, mnemonic, type, derivationPath }`.
2. **After sign-in, the backend auto-provisions managed wallets** on all chains. You only need one EVM control wallet.
3. **Store the mnemonic and private key securely.** Loss = permanent loss of access.
4. **The session keypair is separate from the wallet.** Generate it with `generateGdexSessionKeyPair()` — it's used for signing trades, not wallet derivation.
5. **Multiple sign-ins are fine.** You can generate new session keys and re-sign-in at any time.

## Related Skills

- **gdex-authentication** — Full managed-custody auth details
- **gdex-onboarding** — Platform overview for new users
- **gdex-spot-trading** — Start trading after wallet setup


---
Source attribution: GemachDAO
Original project: https://github.com/GemachDAO/gdex-skill/blob/7e51b52977be7ada679d2cbe58107d14db83cd83/skills/gdex-wallet-setup/SKILL.md
License: MIT
License information: https://opensource.org/license/mit
Original upstream instructions; downloaded from Mega AI Hub.

## Upstream license notice

MIT License

Copyright (c) 2026 GemachDAO

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.



# Mega AI Hub resource metadata

Creator / publisher: GemachDAO
Original project: https://github.com/GemachDAO/gdex-skill/blob/7e51b52977be7ada679d2cbe58107d14db83cd83/skills/gdex-wallet-setup/SKILL.md
Attribution basis: Source repository record

Fields of work: Sales
Roles: Business Development, Customer Success Manager, Sales Development Rep (SDR)
Specialties: API
Tools: @Gdexsdk/Gdex Skill
Country applicability: Country not specified
Classification basis: Source catalog labels
Instruction SHA-256: cacc3440d5c51c35ed9699625fe09c8b988c689a65c500be0c669129e99a9559