> ## Documentation Index
> Fetch the complete documentation index at: https://docs.learnway.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Blockchain Wallet & Balances

> Query on-chain smart wallet balances, link external addresses, and gasless transaction handling.

# Blockchain Wallet & Balances

Every LearnWay account is provisioned with an embedded EVM smart wallet deployed on **Lisk L2**.

***

## Get User Blockchain Balances

Retrieves on-chain XP points, Gem balances, and minted badge counts.

### Endpoint

```http theme={null}
GET /api/v2/blockchain/user/:userId/balance
```

### Headers

```http theme={null}
Authorization: Bearer <jwt_access_token>
```

### Response (200 OK)

```json theme={null}
{
  "success": true,
  "data": {
    "userId": "550e8400-e29b-41d4-a716-446655440000",
    "walletAddress": "0x71C...3921",
    "network": "Lisk L2",
    "chainId": 1135,
    "xpTokenBalance": "1450.0",
    "gemTokenBalance": "120.0",
    "nativeEthBalance": "0.005",
    "nftBadgesCount": 4
  }
}
```

***

## Link External Web3 Wallet

Links an external wallet (MetaMask, Coinbase Wallet, etc.) by submitting a cryptographic signature verifying address ownership.

### Endpoint

```http theme={null}
POST /api/v2/blockchain/link-wallet
```

### Request Body

```json theme={null}
{
  "walletAddress": "0x89205A3A3b2A69De6Dbf7f01ED13B2108B2c43e7",
  "signature": "0x304502210089...",
  "message": "Sign this message to link your wallet to LearnWay: nonce-92812"
}
```

### Response (200 OK)

```json theme={null}
{
  "success": true,
  "data": {
    "linkedAddress": "0x89205A3A3b2A69De6Dbf7f01ED13B2108B2c43e7"
  },
  "message": "External wallet linked successfully"
}
```