Skip to main content
A wallet represents an operational identity (like a technical or integrated user) that can authenticate to use the API.
Wallets belong to an App and can only be created and managed by users with the API key for that App. The App ID is automatically determined from the provided API key.

​
Endpoint

curl -X POST "https://api.g2cplatform.com/v2/wallets" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "sensor01",
    "password": "myStrongPass",
    "metadata": {
      "role": "device",
      "label": "Sensor at gate 3"
    }
  }'

​
Request

​
HTTP Method

POST

​
URL

https://api.g2cplatform.com/v2/wallets

​
Headers

X-API-Key: YOUR_API_KEY
Content-Type: application/json

​
Request Body

FieldTypeRequiredDescription
usernamestring✅Unique username for the wallet (3-50 characters)
passwordstring✅Secure password for wallet authentication (min 8 characters)
metadataobject❌Additional metadata as key-value pairs

​
Response

​
Success Response (201 Created)

{
  "id": "wal_7f8a9b2c-4d5e-6f7g-8h9i-0j1k2l3m4n5o",
  "username": "sensor01",
  "appId": "app_1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p",
  "fullUsername": "sensor01@app_1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p",
  "status": "active",
  "metadata": {
    "role": "device",
    "label": "Sensor at gate 3"
  },
  "createdAt": "2025-08-04T10:30:00Z",
  "updatedAt": "2025-08-04T10:30:00Z",
  "lastLoginAt": null
}

​
Response Headers

The response includes a Location header with the URL of the created wallet: 
Location: https://api.g2cplatform.com/v2/wallets/wal_7f8a9b2c-4d5e-6f7g-8h9i-0j1k2l3m4n5o

​
Error Responses

​
400 Bad Request

{
  "error": "Validation failed",
  "code": "VALIDATION_ERROR",
  "timestamp": "2025-08-04T10:30:00Z",
  "validationErrors": [
    {
      "field": "username",
      "message": "Username must be between 3 and 50 characters",
      "code": "LENGTH_INVALID"
    },
    {
      "field": "password",
      "message": "Password must be at least 8 characters",
      "code": "LENGTH_INVALID"
    }
  ]
}

​
401 Unauthorized

{
  "error": "Invalid or missing API key",
  "code": "UNAUTHORIZED",
  "timestamp": "2025-08-04T10:30:00Z"
}

​
409 Conflict

{
  "error": "Username already exists",
  "code": "USERNAME_EXISTS",
  "timestamp": "2025-08-04T10:30:00Z"
}

​
Implementation Examples

​
Basic Wallet Creation

async function createWallet(username, password, metadata = {}) {
  try {
    const response = await fetch(
      'https://api.g2cplatform.com/v2/wallets',
      {
        method: 'POST',
        headers: {
          'X-API-Key': process.env.G2C_API_KEY,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          username,
          password,
          metadata
        })
      }
    );

    if (response.ok) {
      const wallet = await response.json();
      console.log('✅ Wallet created successfully:', wallet.id);
      return wallet;
    } else {
      const error = await response.json();
      throw new Error(`Wallet creation failed: ${error.error}`);
    }
  } catch (error) {
    console.error('❌ Wallet creation error:', error.message);
    throw error;
  }
}

// Usage
const wallet = await createWallet(
  'sensor01',
  'myStrongPass',
  {
    role: 'device',
    label: 'Sensor at gate 3',
    location: 'Building A'
  }
);

​
Wallet with Validation

function validateWalletData(data) {
  const errors = [];

  if (!data.username || data.username.length < 3 || data.username.length > 50) {
    errors.push('Username must be between 3 and 50 characters');
  }

  if (!data.password || data.password.length < 8) {
    errors.push('Password must be at least 8 characters');
  }

  if (errors.length > 0) {
    throw new Error(`Validation failed: ${errors.join(', ')}`);
  }
}

async function createValidatedWallet(username, password, metadata = {}) {
  // Validate data before sending
  validateWalletData({ username, password });

  const response = await fetch(
    'https://api.g2cplatform.com/v2/wallets',
    {
      method: 'POST',
      headers: {
        'X-API-Key': process.env.G2C_API_KEY,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        username,
        password,
        metadata
      })
    }
  );

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`API Error: ${error.error}`);
  }

  return response.json();
}

​
Bulk Wallet Creation

async function createMultipleWallets(walletsData) {
  const results = [];

  for (const walletData of walletsData) {
    try {
      const wallet = await createWallet(
        walletData.username,
        walletData.password,
        walletData.metadata
      );
      results.push({ success: true, wallet });
    } catch (error) {
      results.push({
        success: false,
        error: error.message,
        data: walletData
      });
    }
  }

  const successful = results.filter(r => r.success);
  const failed = results.filter(r => !r.success);

  console.log(`✅ Created ${successful.length} wallets`);
  if (failed.length > 0) {
    console.log(`❌ Failed to create ${failed.length} wallets`);
  }

  return { successful, failed };
}

// Usage
const walletsData = [
  {
    username: 'sensor01',
    password: 'myStrongPass1',
    metadata: { role: 'device', location: 'Gate 1' }
  },
  {
    username: 'sensor02',
    password: 'myStrongPass2',
    metadata: { role: 'device', location: 'Gate 2' }
  }
];

const results = await createMultipleWallets(walletsData);

​
Best Practices

  • Choose meaningful, descriptive usernames
  • Use consistent naming patterns for different types of wallets
  • Consider including the device or service type in the username
  • Avoid sensitive or personally identifiable information in usernames
  • Use strong, unique passwords for each wallet
  • Consider using a password generator for maximum security
  • Store passwords securely in your application
  • Rotate passwords periodically for sensitive wallets
  • Use metadata to store relevant information about the wallet
  • Include the wallet’s role, purpose, or location
  • Add contact information for the person responsible for the wallet
  • Store configuration or feature flags in metadata
  • Always check for username conflicts before creating
  • Implement exponential backoff for retries
  • Handle network errors gracefully
  • Log wallet creation attempts for audit purposes

​
Next Steps

Wallet Login

Authenticate a wallet to get a JWT token

List Wallets

View all wallets for your App

Update Wallet

Modify wallet information and credentials

Authentication Overview

Learn about authentication methods