Export Private Key

Export the private key for a specific derived address. This allows users to import addresses into external wallets like MetaMask, Trust Wallet, or Exodus.

Endpoint

POST /api/v1/wallet/customer/:customerID/export-key

Authentication

Requires API key authentication via X-API-Key header.

Path Parameters

Parameter	Type	Description
customerID	string	Customer identifier

Request Body

Field	Type	Required	Description
network	string	Yes	Blockchain network (BTC, ETH, BSC, etc.)
index	integer	No	Address derivation index (default: 0)

Example Request

JavaScript

// Export Ethereum private key
const response = await fetch(
  'https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/wallet/customer/user_12345/export-key',
  {
    method: 'POST',
    headers: {
      'X-API-Key': 'your-api-key',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      network: 'ETH',
      index: 0
    })
  }
);

const data = await response.json();
console.log('Address:', data.address);
console.log('Private Key:', data.private_key);

Python

import requests

# Export Bitcoin private key
response = requests.post(
    'https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/wallet/customer/user_12345/export-key',
    headers={
        'X-API-Key': 'your-api-key',
        'Content-Type': 'application/json'
    },
    json={
        'network': 'BTC',
        'index': 0
    }
)

data = response.json()
print(f"Address: {data['address']}")
print(f"Private Key: {data['private_key']}")

cURL

curl -X POST https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/wallet/customer/user_12345/export-key \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "network": "BSC",
    "index": 0
  }'

Response

Success Response (200 OK)

Field	Type	Description
address	string	Blockchain address
private_key	string	Private key in hexadecimal format
network	string	Blockchain network

{
  "address": "0x8B3192f2f0f0D7E4F5C3A1B9E2D7A6C5B4D3E2F1",
  "private_key": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6a7b8c9d0e1f2",
  "network": "ETH"
}

Error Responses

404 Not Found

{
  "error": "Address not found. Please derive the address first using the derive endpoint."
}

This error occurs when:

• The address hasn't been derived yet
• Wrong network or index specified
• Customer ID doesn't match

Solution: First call Derive Address before exporting

401 Unauthorized

{
  "error": "Business not found in context"
}

500 Internal Server Error

{
  "error": "failed to derive key"
}

Security Considerations

CAUTION

Critical Security Warning

Private keys provide complete control over the address and all its funds. Anyone with the private key can:

• Transfer all funds out of the address
• Sign transactions on behalf of the address
• Import the address into any wallet

Protection Recommendations:

1. Only export when necessary (wallet migration, external wallet integration)
2. Implement additional authentication (2FA, email confirmation, SMS verification)
3. Rate limit this endpoint aggressively
4. Log all export attempts with IP address and timestamp
5. Alert users via email when private key is exported
6. Never log or store exported private keys
7. Use HTTPS only - never transmit over insecure connections
8. Display warnings to users about risks

Private Key Formats

EVM Chains (ETH, BSC, POL)

• Format: 64-character hexadecimal string
• Can be imported to MetaMask, Trust Wallet, etc.

// Import to MetaMask
ethereum.request({
  method: 'wallet_importAccount',
  params: ['0xa1b2c3d4e5f6...'] // Add '0x' prefix
});

Bitcoin (BTC, BCH, LTC)

• Format: Hexadecimal or WIF (Wallet Import Format)
• Current API returns hex - may need conversion for some wallets

Solana (SOL)

• Format: Base58 or byte array
• Can be imported to Phantom, Solflare

Tron (TRX)

• Format: Hexadecimal
• Can be imported to TronLink

Use Cases

Wallet Migration

Allow users to export keys for migration to external wallets:

async function exportForMigration(customerId, network, index) {
  // Show security warning
  const confirmed = confirm(
    '⚠️ WARNING: Your private key controls all funds in this address. ' +
    'Never share it with anyone. ' +
    'Are you sure you want to export?'
  );
  
  if (!confirmed) return;
  
  // Export key
  const response = await fetch(
    `https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/wallet/customer/${customerId}/export-key`,
    {
      method: 'POST',
      headers: {
        'X-API-Key': process.env.API_KEY,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ network, index })
    }
  );
  
  const data = await response.json();
  
  // Display securely (blur-on-leave, copy protection)
  return data;
}

External Wallet Integration

Programmatically import to external wallet:

async function importToMetaMask(customerId) {
  // Export ETH private key
  const response = await fetch(
    `https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/wallet/customer/${customerId}/export-key`,
    {
      method: 'POST',
      headers: {
        'X-API-Key': process.env.API_KEY,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        network: 'ETH',
        index: 0
      })
    }
  );
  
  const data = await response.json();
  
  // Import to MetaMask
  await ethereum.request({
    method: 'wallet_importAccount',
    params: [`0x${data.private_key}`]
  });
  
  alert(`Imported ${data.address} to MetaMask`);
}

Best Practices

Private Key Management

• Derive first: Always derive address before attempting export
• Confirm export: Require explicit user confirmation with warnings
• Audit logging: Log all export operations for security
• Time limits: Consider time-limited access to exported keys
• Revocation: No way to "revoke" exported key - educate users
• Backup alternative: Recommend seed phrase backup instead

Related Endpoints

• Derive Address - Must be called before export
• Get Seed Phrase - Alternative: export master seed
• List Addresses - View all derived addresses