Get Seed Phrase

Retrieve the encrypted seed phrase (mnemonic) for a customer's wallet. This endpoint allows you to backup or re-display the mnemonic to users.

Endpoint

GET /api/v1/wallet/customer/:customerID/seed

Authentication

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

Path Parameters

Parameter	Type	Description
customerID	string	Customer identifier

Request

Example Request

JavaScript

const response = await fetch(
  'https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/wallet/customer/user_12345/seed',
  {
    headers: {
      'X-API-Key': 'your-api-key'
    }
  }
);

const data = await response.json();
console.log('Mnemonic:', data.mnemonic);

Python

import requests

response = requests.get(
    'https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/wallet/customer/user_12345/seed',
    headers={'X-API-Key': 'your-api-key'}
)

data = response.json()
print(f"Mnemonic: {data['mnemonic']}")

cURL

curl https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/wallet/customer/user_12345/seed \
  -H "X-API-Key: your-api-key"

Response

Success Response (200 OK)

Field	Type	Description
customer_id	string	Customer identifier
mnemonic	array	BIP-39 mnemonic phrase (array of words)
word_count	integer	Number of words (12 or 24)

{
  "customer_id": "user_12345",
  "mnemonic": [
    "abandon", "ability", "able", "about", "above", "absent",
    "absorb", "abstract", "absurd", "abuse", "access", "accident"
  ],
  "word_count": 12
}

Error Responses

404 Not Found

{
  "error": "wallet not found for customer user_12345"
}

401 Unauthorized

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

500 Internal Server Error

{
  "error": "failed to decrypt seed phrase"
}

Security Considerations

WARNING

Sensitive Operation: This endpoint returns the master seed phrase which can derive all addresses and control all funds. Only use this endpoint when:

• User explicitly requests seed phrase backup
• Implementing wallet recovery flow
• Migrating to external wallet software

Protection recommendations:

• Implement additional authentication (2FA, email verification)
• Rate limit this endpoint
• Log all access attempts
• Never store seed phrase in plaintext in your application

Use Cases

Wallet Backup

Allow users to backup their seed phrase:

async function showSeedPhraseBackup(customerId) {
  // Show warning dialog first
  const confirmed = confirm(
    'Your seed phrase controls all your funds. ' +
    'Never share it with anyone. Write it down and store it safely.'
  );
  
  if (!confirmed) return;
  
  const response = await fetch(
    `https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/wallet/customer/${customerId}/seed`,
    {
      headers: { 'X-API-Key': process.env.API_KEY }
    }
  );
  
  const data = await response.json();
  
  // Display mnemonic securely (blur-on-scroll, copy protection, etc.)
  displaySecureMnemonic(data.mnemonic);
}

Wallet Recovery

Verify seed phrase during recovery:

async function verifySeedPhrase(customerId, userInput) {
  const response = await fetch(
    `https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/wallet/customer/${customerId}/seed`,
    {
      headers: { 'X-API-Key': process.env.API_KEY }
    }
  );
  
  const data = await response.json();
  const storedMnemonic = data.mnemonic.join(' ');
  const inputMnemonic = userInput.trim().toLowerCase();
  
  return storedMnemonic === inputMnemonic;
}

Related Endpoints

• Create Wallet - Create new wallet (returns mnemonic once)
• Export Private Key - Export individual address keys
• Derive Address - Generate blockchain addresses