Skip to main content

Wallets

Manage EVM wallets -- generate new ones, import existing ones, and check balances.

Generating a Wallet​

Programmatic​

const wallet = await app.onchain.wallets.create({
  name: "Treasury",
  metadata: { purpose: "payments" },
});

console.log(wallet._id);         // Internal ID
console.log(wallet.address);     // "0x1234..."
console.log(wallet.name);        // "Treasury"
// Private key is encrypted and stored in the database

REST API​

curl -X POST http://localhost:3000/onchain/wallets \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGci..." \
  -d '{"name": "Treasury"}'

Response (201):

{
  "_id": "65a1b2c3d4e5f6a7b8c9d0e1",
  "address": "0x1234567890abcdef1234567890abcdef12345678",
  "name": "Treasury",
  "createdAt": "2025-01-15T10:30:00.000Z"
}

Importing a Wallet​

const wallet = await app.onchain.wallets.import({
  privateKey: "0xabc123...",
  name: "Imported Wallet",
});
curl -X POST http://localhost:3000/onchain/wallets/import \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGci..." \
  -d '{
    "privateKey": "0xabc123...",
    "name": "Imported Wallet"
  }'

Listing Wallets​

const wallets = await app.onchain.wallets.list();
curl http://localhost:3000/onchain/wallets \
  -H "Authorization: Bearer eyJhbGci..."

Response (200):

{
  "wallets": [
    {
      "_id": "65a1b2c3d4e5f6a7b8c9d0e1",
      "address": "0x1234...5678",
      "name": "Treasury",
      "createdAt": "2025-01-15T10:30:00.000Z"
    }
  ]
}

Checking Balance​

Native Token (ETH)​

const balance = await app.onchain.getBalance("0x1234...5678", "ethereum");
console.log(balance); // "1.5" (in ETH)
curl "http://localhost:3000/onchain/balance/0x1234...5678?chain=ethereum" \
  -H "Authorization: Bearer eyJhbGci..."

Response (200):

{
  "address": "0x1234...5678",
  "balance": "1.500000000000000000",
  "symbol": "ETH",
  "chain": "ethereum"
}

ERC-20 Token Balance​

const balance = await app.onchain.getTokenBalance(
  "0x1234...5678",
  "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC
  "ethereum"
);
console.log(balance); // "1000.00"
curl "http://localhost:3000/onchain/balance/0x1234...5678?chain=ethereum&token=0xA0b8..." \
  -H "Authorization: Bearer eyJhbGci..."

Wallet Security​

  • Private keys are encrypted with AES-256-GCM before storage.
  • Encryption key is derived from the ENCRYPTION_KEY environment variable.
  • Private keys are never returned in API responses.
  • Wallet addresses are publicly accessible; private keys are not.

Wallet Data Model​

interface Wallet {
  _id: ObjectId;
  address: string;
  name?: string;
  encryptedKey: string;    // AES-256-GCM encrypted
  metadata?: Record<string, unknown>;
  createdAt: Date;
}