Wallet Module

The wallet module provides comprehensive functionality for managing smart contract wallets, executing transactions, and managing assets.

Response shape: SDK methods return objects with a data field. Destructure const { data } = await create(...) or use extractResponseData(response) from cilantro-react. Types are exported from cilantro-sdk/wallet.

In React apps, use useWallet for the wallet list and createWallet; this module is for direct SDK usage.

Import

import {
  create,
  findOne,
  findAll,
  listSigners,
  getSignerById,
  sendSOL,
  sendSPL,
  prepareTransaction,
  submitTransaction,
} from 'cilantro-sdk/wallet';

Basic Operations

create(options)

Create a new smart contract wallet.

const { data } = await create({
  name: 'My Wallet',
  userId: 'user-id',
});
const walletId = data.id;

findAll()

Get all wallets for the authenticated user.

const wallets = await findAll();

findOne(walletId)

Get wallet by ID.

const wallet = await findOne(walletId);

update(walletId, options) / remove(walletId)

Update or delete a wallet. Check SDK exports for full signatures.

Signers

listSigners(walletId)

List all signers for a wallet.

const { data: signers } = await listSigners(walletId);

getSignerById(walletId, signerId)

Get one signer by ID.

const { data: signer } = await getSignerById(walletId, signerId);

For creating email/phone signers and storing device keys, use the helpers (createEmailSignerHelper, etc.).

Transactions

sendSOL(walletId, options)

Send SOL from wallet to recipient.

const result = await sendSOL(walletId, {
  recipientAddress: '7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU',
  amountLamports: 100000000, // 0.1 SOL
});
const { data } = result; // signature, etc.

sendSPL(walletId, options)

Send SPL tokens from wallet.

const result = await sendSPL('wallet-id', {
  recipientAddress: 'DYw8jCTfwHNRJhhmFcbXvVDTqWMEVFBX6ZKUmG5CNSKK',
  mintAddress: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
  amount: 1000000
});

sendTransaction(walletId, options)

Execute arbitrary transaction via CPI.

const result = await sendTransaction('wallet-id', {
  programId: 'program-address',
  accounts: [...],
  data: Buffer.from(...)
});

simulateTransaction(walletId, options)

Simulate a transaction without executing.

const result = await simulateTransaction('wallet-id', {
  programId: 'program-address',
  accounts: [...]
});

NFTs & Tokens

mintToken(walletId, options)

Mint fungible token (SPL or Token-2022).

await mintToken('wallet-id', {
  amount: 1000000,
  decimals: 6,
  symbol: 'USDC',
  name: 'USD Coin'
});

mintNFTSimple(walletId, options)

Mint NFT with metadata (handles all logic internally).

await mintNFTSimple('wallet-id', {
  name: 'My NFT',
  symbol: 'MNFT',
  uri: 'https://metadata-url.com',
  attributes: [{ trait_type: 'Rarity', value: 'Legendary' }]
});

mintNFT(walletId, options)

Mint NFT using Metaplex via CPI (Advanced).

await mintNFT('wallet-id', {
  // Advanced Metaplex configuration
});

Assets

getAssets(walletId, options?)

Get all assets for a wallet (cached with auto-refresh).

const assets = await getAssets('wallet-id', {
  assetType: 'SPL_TOKEN' // optional: 'NFT' | 'SPL_TOKEN' | 'SOL'
});

syncAssets(walletId)

Force sync wallet balance and assets from blockchain.

const assets = await syncAssets('wallet-id');

getTotalBalance()

Get total balance across all user wallets.

const totalBalance = await getTotalBalance();

Batch Operations

batchCreate(options)

Batch create multiple wallets.

const batchResult = await batchCreate({
  wallets: [
    { walletName: 'wallet-1' },
    { walletName: 'wallet-2' }
  ]
});
const created = extractResponseData(batchResult);

batchSendSOL(walletId, options)

Batch send SOL to multiple recipients.

await batchSendSOL('wallet-id', {
  recipients: [
    { to: 'address-1', amount: 0.5 },
    { to: 'address-2', amount: 1.0 }
  ]
});

batchSendSPL(walletId, options)

Batch send SPL tokens to multiple recipients.

await batchSendSPL('wallet-id', {
  recipients: [
    { to: 'address-1', amount: 1000, mintAddress: '...' },
    { to: 'address-2', amount: 2000, mintAddress: '...' }
  ]
});

Client-Side Transaction Signing

prepareTransaction(walletId, options)

Build an unsigned transaction that can be signed by external wallet, passkey, or email/phone signer. Returns serialized transaction for signing. This enables non-custodial wallet flows where the user controls their keys.

// Prepare SOL transfer transaction
const prepared = await prepareTransaction('wallet-id', {
  type: 'SEND_SOL',
  signerPubkey: 'base64-encoded-signer-public-key',
  sendSolParams: {
    recipientAddress: 'DYw8jCTfwHNRJhhmFcbXvVDTqWMEVFBX6ZKUmG5CNSKK',
    amountLamports: 1000000000
  }
});

// Returns: { serializedTransaction: "base64...", requiresSignature: true }

submitTransaction(walletId, options)

Submit a client-signed transaction to the Solana blockchain. Use after preparing transaction with prepareTransaction and signing it with your signer.

// After signing the transaction locally
const submitResult = await submitTransaction(walletId, {
  signedTransaction: 'base64-encoded-signed-transaction'
});
const outcome = extractResponseData(submitResult);

signMessage(walletId, options)

Sign an arbitrary message using the wallet for authentication or verification purposes. Useful for proving wallet ownership, dApp authentication, or creating verifiable signatures.

const signature = await signMessage('wallet-id', {
  message: 'Sign in to dApp',
  signerId: 'signer-id' // optional
});

console.log('Message signature:', signature.data.signature);

Non-Custodial Transactions

sendSolNonCustodial(walletId, options)

Send SOL from a non-custodial wallet using passkey signature.

const result = await sendSolNonCustodial('wallet-id', {
  recipientAddress: 'DYw8jCTfwHNRJhhmFcbXvVDTqWMEVFBX6ZKUmG5CNSKK',
  amountLamports: 1000000000,
  passkeySignature: 'passkey-signature'
});

sendSplNonCustodial(walletId, options)

Send SPL tokens from a non-custodial wallet using passkey signature.

const result = await sendSplNonCustodial('wallet-id', {
  recipientAddress: 'DYw8jCTfwHNRJhhmFcbXvVDTqWMEVFBX6ZKUmG5CNSKK',
  mintAddress: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
  amount: 1000000,
  passkeySignature: 'passkey-signature'
});

executeInstructionNonCustodial(walletId, options)

Execute an arbitrary instruction from a non-custodial wallet using passkey signature.

const result = await executeInstructionNonCustodial('wallet-id', {
  programId: 'program-id',
  accounts: [
    { pubkey: 'account1', isSigner: true, isWritable: true },
    { pubkey: 'account2', isSigner: false, isWritable: false }
  ],
  data: 'base64-encoded-data',
  passkeySignature: 'passkey-signature'
});

Wallet Management

getCustodyInfo(walletId)

Get wallet custody information and all signers.

const custodyResult = await getCustodyInfo(walletId);
const custodyInfo = extractResponseData(custodyResult);

updateAdminSigner(walletId, options)

Update the admin signer for a wallet (provider migration).

await updateAdminSigner('wallet-id', {
  newAdminSignerPubkey: 'new-admin-signer-public-key'
});