Skip to main content
This endpoint allows you to modify a wallet’s properties or change its status.
This endpoint can only be accessed using the API key of the App that owns the wallet. Password changes take effect immediately and will require users to login with the new credentials.

​
Endpoint

curl -X PUT "https://api.g2cplatform.com/v2/wallets/wal_7f8a9b2c-4d5e-6f7g-8h9i-0j1k2l3m4n5o" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "password": "newStrongPassword",
    "status": "active",
    "metadata": {
      "role": "device",
      "label": "Sensor at gate 5",
      "location": "Building B"
    }
  }'

​
Request

​
HTTP Method

PUT

​
URL

https://api.g2cplatform.com/v2/wallets/{walletId}

​
Path Parameters

ParameterTypeRequiredDescription
walletIdstring✅Unique identifier of the wallet to update

​
Headers

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

​
Request Body

FieldTypeRequiredDescription
passwordstring❌New password for the wallet (min 8 characters)
statusstring❌New wallet status (active, inactive, suspended)
metadataobject❌Updated metadata as key-value pairs
Only include the fields you want to update. Omitted fields will remain unchanged.

​
Response

​
Success Response (200 OK)

{
  "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 5",
    "location": "Building B"
  },
  "createdAt": "2025-08-01T10:30:00Z",
  "updatedAt": "2025-08-04T11:45:30Z",
  "lastLoginAt": "2025-08-04T09:15:30Z"
}
For security reasons, the password is never returned in the response, even when it has been updated.

​
Error Responses

​
400 Bad Request

{
  "error": "Validation failed",
  "code": "VALIDATION_ERROR",
  "timestamp": "2025-08-04T11:45:30Z",
  "validationErrors": [
    {
      "field": "password",
      "message": "Password must be at least 8 characters",
      "code": "LENGTH_INVALID"
    },
    {
      "field": "status",
      "message": "Status must be one of: active, inactive, suspended",
      "code": "ENUM_INVALID"
    }
  ]
}

​
401 Unauthorized

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

​
404 Not Found

{
  "error": "Wallet not found",
  "code": "RESOURCE_NOT_FOUND",
  "timestamp": "2025-08-04T11:45:30Z"
}

​
Implementation Examples

​
Update Wallet Password

async function updateWalletPassword(walletId, newPassword) {
  try {
    // Validate password strength
    if (newPassword.length < 8) {
      throw new Error('Password must be at least 8 characters');
    }

    if (!/[A-Z]/.test(newPassword) || !/[0-9]/.test(newPassword)) {
      throw new Error('Password must contain at least one uppercase letter and one number');
    }

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

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

    console.log('✅ Password updated successfully');
    return true;
  } catch (error) {
    console.error('❌ Password update error:', error.message);
    throw error;
  }
}

​
Change Wallet Status

async function changeWalletStatus(walletId, newStatus) {
  // Validate status
  const validStatuses = ['active', 'inactive', 'suspended'];
  if (!validStatuses.includes(newStatus)) {
    throw new Error(`Invalid status. Must be one of: ${validStatuses.join(', ')}`);
  }

  try {
    const response = await fetch(
      `https://api.g2cplatform.com/v2/wallets/${walletId}`,
      {
        method: 'PUT',
        headers: {
          'X-API-Key': process.env.G2C_API_KEY,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          status: newStatus
        })
      }
    );

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

    const wallet = await response.json();
    console.log(`✅ Wallet status changed to ${newStatus}`);
    return wallet;
  } catch (error) {
    console.error('❌ Status update error:', error.message);
    throw error;
  }
}

// Usage examples
async function suspendWallet(walletId) {
  return changeWalletStatus(walletId, 'suspended');
}

async function activateWallet(walletId) {
  return changeWalletStatus(walletId, 'active');
}

async function deactivateWallet(walletId) {
  return changeWalletStatus(walletId, 'inactive');
}

​
Update Wallet Metadata

async function updateWalletMetadata(walletId, metadataUpdates) {
  try {
    // First, get current wallet to preserve existing metadata
    const getCurrentWallet = await fetch(
      `https://api.g2cplatform.com/v2/wallets/${walletId}`,
      {
        headers: {
          'X-API-Key': process.env.G2C_API_KEY,
          'Content-Type': 'application/json'
        }
      }
    );

    if (!getCurrentWallet.ok) {
      const error = await getCurrentWallet.json();
      throw new Error(`Failed to retrieve wallet: ${error.error}`);
    }

    const currentWallet = await getCurrentWallet.json();

    // Merge existing metadata with updates
    const updatedMetadata = {
      ...currentWallet.metadata || {},
      ...metadataUpdates
    };

    // Update the wallet with merged metadata
    const updateResponse = await fetch(
      `https://api.g2cplatform.com/v2/wallets/${walletId}`,
      {
        method: 'PUT',
        headers: {
          'X-API-Key': process.env.G2C_API_KEY,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          metadata: updatedMetadata
        })
      }
    );

    if (!updateResponse.ok) {
      const error = await updateResponse.json();
      throw new Error(`Failed to update metadata: ${error.error}`);
    }

    const wallet = await updateResponse.json();
    console.log('✅ Wallet metadata updated');
    return wallet;
  } catch (error) {
    console.error('❌ Metadata update error:', error.message);
    throw error;
  }
}

// Usage
await updateWalletMetadata('wal_7f8a9b2c-4d5e-6f7g-8h9i-0j1k2l3m4n5o', {
  location: 'Building B',
  department: 'Security',
  updatedBy: 'Admin'
});

​
Usage Scenarios

​
Bulk Update Wallet Statuses

async function bulkUpdateWalletStatus(walletIds, newStatus) {
  const results = {
    successful: [],
    failed: []
  };

  for (const walletId of walletIds) {
    try {
      const updatedWallet = await changeWalletStatus(walletId, newStatus);
      results.successful.push(updatedWallet);
    } catch (error) {
      results.failed.push({
        walletId,
        error: error.message
      });
    }
  }

  console.log(`✅ Successfully updated ${results.successful.length} wallets`);
  if (results.failed.length > 0) {
    console.warn(`⚠️ Failed to update ${results.failed.length} wallets`);
  }

  return results;
}

// Example: Deactivate all unused wallets
async function deactivateUnusedWallets(daysSinceLastLogin = 90) {
  // First, list all active wallets
  const response = await fetch(
    'https://api.g2cplatform.com/v2/wallets?status=active',
    {
      headers: {
        'X-API-Key': process.env.G2C_API_KEY,
        'Content-Type': 'application/json'
      }
    }
  );

  const { data: wallets } = await response.json();

  // Calculate cutoff date
  const cutoffDate = new Date();
  cutoffDate.setDate(cutoffDate.getDate() - daysSinceLastLogin);

  // Find wallets with no recent activity
  const unusedWalletIds = wallets
    .filter(wallet => {
      // If no last login or last login before cutoff date
      if (!wallet.lastLoginAt) return true;
      return new Date(wallet.lastLoginAt) < cutoffDate;
    })
    .map(wallet => wallet.id);

  console.log(`Found ${unusedWalletIds.length} unused wallets`);

  // Deactivate the unused wallets
  if (unusedWalletIds.length > 0) {
    return bulkUpdateWalletStatus(unusedWalletIds, 'inactive');
  }

  return { successful: [], failed: [] };
}

​
Best Practices

  • Use strong password requirements (min 8 characters, mixed case, numbers)
  • Implement secure password handling - never log or expose passwords
  • Consider two-factor authentication for sensitive wallets
  • Use automatic password rotation for high-security systems
  • Use appropriate status values for different situations
  • Document status changes with metadata updates
  • Implement notification systems for status changes
  • Have a policy for handling suspended wallets
  • Keep metadata fields consistent across wallets
  • Use metadata to track ownership and responsibility
  • Include last update information in metadata
  • Validate metadata format and content
  • Log all wallet update operations for audit
  • Implement approval workflows for sensitive wallet changes
  • Verify API key permissions before updates
  • Notify wallet owners of significant changes

​
Next Steps

Get Wallet

Retrieve detailed information about a specific wallet

Delete Wallet

Remove a wallet from the system

List Wallets

View all wallets for your App

Wallet Login

Authenticate a wallet to get a JWT token