Cilantro Smart SDK

A TypeScript/JavaScript SDK for interacting with the Cilantro Smart API - A Solana wallet management system with comprehensive signer management, passkey support, and multi-device capabilities.

Table of Contents

• Installation
• Quick Start
• Configuration
• Complete API Reference
  • SDK Configuration
  • Platform Module
  • User Module
  • Wallet Module
  • Auth Module
  • Subscriptions Module
  • Plans Module
  • Transactions Module
  • Delegated Keys Module
  • Webhooks Module
  • Public Module
  • App Module
  • Platform Payments Module
  • Info Module
  • Address Book Module
  • Analytics Module
  • Health Module
  • Scheduled Transactions Module
  • Spending Limits Module
  • Helpers Module
  • Utils Module
• Examples & Use Cases
• Error Handling
• TypeScript Support
• Cross-Platform Support
• Best Practices
• Development & Publishing
• License

Installation

npm install cilantro-sdk

Quick Start

Option 1: Using API Key (Recommended for Server-Side)

import { configure } from 'cilantro-sdk';
import { sendSOL } from 'cilantro-sdk/wallet';

// Configure SDK with your API key
configure({ 
  apiKey: 'your-api-key-here'
});

// Make authenticated requests
const result = await sendSOL('wallet-id', {
  recipientAddress: 'DYw8jCTfwHNRJhhmFcbXvVDTqWMEVFBX6ZKUmG5CNSKK',
  amountLamports: 1000000000
});

Option 2: Using Login (For User Authentication)

import { loginAndSetAuth } from 'cilantro-sdk/auth';
import { sendSOL } from 'cilantro-sdk/wallet';

// Login and set authentication automatically
await loginAndSetAuth({
  usernameOrEmail: '[email protected]',
  password: 'SecurePass123!'
});

// Make authenticated requests
const result = await sendSOL('wallet-id', {
  recipientAddress: 'DYw8jCTfwHNRJhhmFcbXvVDTqWMEVFBX6ZKUmG5CNSKK',
  amountLamports: 1000000000
});

Option 3: Manual Authentication Control

import { setAuth } from 'cilantro-sdk';
import { login } from 'cilantro-sdk/auth';
import { sendSOL } from 'cilantro-sdk/wallet';

// Login without automatically setting auth
const authResult = await login({
  usernameOrEmail: '[email protected]',
  password: 'password123'
});

// Manually set authentication (API returns accessToken)
setAuth({ jwt: authResult.data.accessToken });

// Make authenticated requests
const result = await sendSOL('wallet-id', {
  recipientAddress: 'DYw8jCTfwHNRJhhmFcbXvVDTqWMEVFBX6ZKUmG5CNSKK',
  amountLamports: 1000000000
});

CommonJS

const { configure } = require('cilantro-sdk');
const { sendSOL } = require('cilantro-sdk/wallet');

// Configure with API key
configure({ apiKey: 'your-api-key' });

// Make authenticated requests
const result = await sendSOL('wallet-id', { ... });

Helpers Module - Device Keys & Signer Management

The SDK includes a comprehensive helpers module for device key management and signer operations. This simplifies working with email/phone signers and provides automatic device key resolution, validation, and caching.

Quick Example

import { 
  createEmailSignerHelper,
  getEmailSignerKeypair,
  createLocalStorageAdapter 
} from 'cilantro-sdk/helpers';

// Create storage for device keys
const storage = createLocalStorageAdapter();

// Create email signer (device key generated automatically)
const signer = await createEmailSignerHelper('wallet-id', {
  email: '[email protected]',
  deviceKeyManager: storage
});

// Get keypair - SDK automatically:
// 1. Fetches signer from API
// 2. Extracts devicePublicKey and deviceId
// 3. Resolves device key from storage
// 4. Validates device key matches API
const keypair = await getEmailSignerKeypair(
  'wallet-id',
  signer.signerId,
  { 
    deviceKeyManager: storage
  }
);

Key Features

• ✅ Fully Automatic Resolution - Automatically fetches signer, extracts device info, and resolves device keys
• ✅ Automatic Caching - Keypair derivation is cached to avoid redundant operations
• ✅ Device Key Validation - Prevents mismatches between storage and API
• ✅ Multi-Device Support - Handle multiple devices per signer
• ✅ Cross-Platform - Works in browser and Node.js
• ✅ Storage Adapters - localStorage, filesystem, or memory storage
• ✅ Type-Safe - Full TypeScript support
• ✅ Functional - No classes, pure functions

Available Helpers

Device Key Management:

• generateDeviceKeyPair() - Generate new device key pair
• getOrCreateDeviceKeyPair(storage, keyId?) - Get or create device key pair with caching
• getDevicePublicKey(storage, keyId) - Get device public key
• getDevicePrivateKey(storage, keyId) - Get device private key
• rotateDeviceKey(storage, keyId) - Rotate device keys
• clearDeviceKeyCache(keyId?) - Clear device key cache
• deleteDeviceKey(storage, keyId) - Delete device key
• listDeviceKeys(storage) - List all device key IDs
• findDeviceKeyByPublicKey(storage, publicKey) - Find device key by public key
• listAllDeviceKeys(storage) - List all device keys with metadata

Email Signer Helpers:

• createEmailSignerHelper(walletId, options) - Create email signer with automatic device key generation
• getEmailSignerKeypair(walletId, signerId, options) - Get keypair with automatic device key resolution
• signWithEmailSigner(walletId, signerId, message, options) - Sign messages with email signer
• clearEmailSignerCache(walletId, signerId?) - Clear email signer cache
• getEmailSignerByEmail(walletId, email) - Find email signer by email address

Phone Signer Helpers:

• createPhoneSignerHelper(walletId, options) - Create phone signer with automatic device key generation
• getPhoneSignerKeypair(walletId, signerId, options) - Get keypair with automatic device key resolution
• signWithPhoneSigner(walletId, signerId, message, options) - Sign messages with phone signer
• clearPhoneSignerCache(walletId, signerId?) - Clear phone signer cache
• getPhoneSignerByPhone(walletId, phone) - Find phone signer by phone number

Passkey (WebAuthn) Helpers:

• isWebAuthnSupported() - Check if WebAuthn is supported
• isPlatformAuthenticatorAvailable() - Check if platform authenticator is available
• registerPasskey(walletId, options?) - Register a new passkey
• authenticateWithPasskey(walletId, options?) - Authenticate with existing passkey
• formatRegistrationResponse(response) - Format passkey registration response
• formatAuthenticationResponse(response) - Format passkey authentication response
• formatAuthenticationForVerification(response) - Format authentication for verification
• findExistingPasskeySigner(walletId, credentialId?) - Find existing passkey signer
• registerPasskeyComplete(walletId, registrationData, verificationData) - Complete passkey registration
• signWithPasskeySigner(walletId, signerId, message, options) - Sign with passkey signer

Device Key Validation & Resolution:

• getSignerDeviceKeys(walletId, signerId) - Get all device keys for a signer from API
• validateDeviceKey(storage, keyId, expectedPublicKey) - Validate device key matches API
• resolveDeviceKey(storage, walletId, signerId) - Automatically find matching device key
• findAndValidateDeviceKey(storage, walletId, signerId, devicePublicKey) - Find and validate device key
• getBestDeviceIdentity(walletId, signerId) - Get most recently used device identity

Device Identity Management:

• addDeviceIdentityToSigner(walletId, signerId, options) - Add new device to existing signer
• replaceDeviceIdentity(walletId, signerId, options) - Replace existing device identity
• addNewDeviceToSigner(walletId, signerId, options) - Convenience function for adding new device
• canAddDeviceToSigner(walletId, signerId) - Check if device can be added to signer

Signer Lifecycle:

• createSigner(walletId, signerType, config) - Create a new signer
• revokeSigner(walletId, signerId) - Revoke a signer
• getSigners(walletId) - Get all signers for a wallet

Multi-Device Management:

• addDevice(walletId, signerId, devicePublicKey) - Add device to signer
• replaceDevice(walletId, signerId, oldDeviceId, newDevicePublicKey) - Replace device
• getDevices(walletId, signerId) - Get all devices for a signer
• updateDevice(walletId, signerId, deviceId, data) - Update device information

Core Signer Helpers:

• deriveSignerKeypair(walletId, signerId, options) - Derive signer keypair from encrypted secret
• signWithSigner(walletId, signerId, message, options) - Sign message with signer
• parseSignerResponse(response) - Parse signer API response to SignerInfo
• clearSignerCache(walletId?, signerId?) - Clear signer keypair cache
• getCacheStats() - Get cache statistics

Validation:

• isValidEmail(email) - Validate email format
• isValidPhone(phone) - Validate phone number format
• isBrowserCompatible() - Check if browser is compatible

External Wallet Adapter:

• detectWallets() - Detect available Solana wallets
• getWallet(name) - Get wallet by name
• connectWallet(wallet) - Connect to external wallet
• signTransaction(wallet, transaction) - Sign transaction with external wallet
• signMessage(wallet, message) - Sign message with external wallet

Wallet Transaction Helpers:

• signTransactionWithEmailSigner(walletId, signerId, unsignedTransaction, options) - Sign transaction with email signer
• signTransactionWithPhoneSigner(walletId, signerId, unsignedTransaction, options) - Sign transaction with phone signer
• signTransactionWithPasskeySigner(walletId, signerId, unsignedTransaction, options) - Sign transaction with passkey signer
• signTransactionWithExternalWallet(wallet, unsignedTransaction) - Sign transaction with external wallet
• prepareSignAndSubmitTransaction(walletId, signerId, signerType, prepareTransactionDto, options) - Prepare, sign, and submit transaction
• sendSOLWithSigner(walletId, signerId, signerType, recipientAddress, amountLamports, options) - Send SOL using signer (automatically derives signerPubkey for email/phone)
• sendSPLWithSigner(walletId, signerId, signerType, mintAddress, recipientAddress, amount, options) - Send SPL token using signer (automatically derives signerPubkey for email/phone)

Storage Adapters:

• createMemoryAdapter() - Create in-memory storage adapter (for testing)
• createLocalStorageAdapter() - Create browser localStorage adapter
• createFileSystemAdapter(basePath) - Create Node.js filesystem adapter
• getDefaultStorageAdapter() - Get platform-appropriate storage adapter

Key Format Utilities:

• normalizeSPKI(spkiKey) - Normalize SPKI key format
• base64ToPEM(base64Key, keyType) - Convert base64 to PEM format
• pemToBase64(pemKey) - Convert PEM to base64
• base64ToArrayBuffer(base64) - Convert base64 to ArrayBuffer
• arrayBufferToBase64(buffer) - Convert ArrayBuffer to base64
• importSPKIPublicKey(spkiBase64) - Import SPKI public key
• exportToSPKI(key) - Export key to SPKI format
• isValidBase64(str) - Validate base64 string

For detailed documentation on device key management, see DEVICE_KEY_MANAGEMENT.md.

Configuration

configure(config: SDKConfig): void

Initialize the SDK with configuration options. This should be called once at the start of your application.

Parameters:

• config (SDKConfig): Configuration object
  • apiKey? (string): API key for authentication (recommended for server-side)
  • jwt? (string): JWT token for authentication (obtained from login)
  • baseURL? (string): Custom API base URL (defaults to https://api.cilantro.gg)

Returns: void

Example:

import { configure } from 'cilantro-sdk';

// Configure with API key (server-side)
configure({ 
  apiKey: 'your-api-key',
  baseURL: 'https://api.cilantro.gg'
});

// Configure with JWT (after login)
configure({ 
  jwt: 'your-jwt-token'
});

// Configure with both
configure({ 
  apiKey: 'your-api-key',
  jwt: 'your-jwt-token'
});

setAuth(auth: { jwt?: string; apiKey?: string; platformApiKey?: string }): void

Update authentication credentials after initialization. Useful when credentials change (e.g., after login or token refresh). The API key is set from apiKey or platformApiKey (whichever is provided).

Parameters:

• auth (object): Authentication credentials
  • jwt? (string): JWT access token to set (from login/social/Discord)
  • apiKey? (string): API key to set
  • platformApiKey? (string): Platform API key (alternative to apiKey)

Returns: void

Example:

import { setAuth } from 'cilantro-sdk';
import { login } from 'cilantro-sdk/auth';

// Login and update auth
const result = await login({
  usernameOrEmail: '[email protected]',
  password: 'password123'
});

setAuth({ jwt: result.data.accessToken });

clearAuth(): void

Clear all authentication credentials. Useful for logout or resetting authentication state.

Parameters: None

Returns: void

Example:

import { clearAuth } from 'cilantro-sdk';

// Clear all authentication
clearAuth();

Authentication Types

The SDK supports two types of authentication:

1. API Key Authentication: For server-side applications and platform-level access

   • Use when you have a platform API key
   • Best for server-side operations
   • Set via configure({ apiKey: '...' }) or setAuth({ apiKey: '...' })

2. JWT Token Authentication: For user-specific operations after login

   • Use after user/platform login
   • Best for user-scoped operations
   • Set via configure({ jwt: '...' }) or setAuth({ jwt: '...' })

You can use either or both simultaneously. The SDK will automatically include the appropriate headers in all requests.

Documentation

Getting Started Guides

• Complete Wallet & Transaction Flow Guide - Comprehensive step-by-step guide covering:

  • Wallet creation (platform-controlled vs user-controlled)
  • Understanding and creating signers (email, phone, passkey, external, API key)
  • Device key management and ECDH encryption
  • Complete transaction flows (server-side and client-side signing)
  • Real-world examples and best practices

• Device Key Management Guide - Deep dive into device key architecture

Quick Links

• Examples - Code examples
• API Documentation - Complete API reference

Development & Publishing

If you are building or contributing to the SDK itself:

| Script | Description | |--------|-------------| | npm run fetch:spec | Download latest OpenAPI spec from the Cilantro API to openapi-spec-latest.json | | npm run generate:api | Generate API client and models from the spec (orval) | | npm run build | Fetch spec, generate API, and build dist (CJS + ESM + types) | | npm run regenerate | Alias for npm run build – sync SDK to latest docs and build |

Publishing runs prepublishOnly (full build) before npm publish. Use npm publish --otp=<code> if your npm account has 2FA enabled.

Module Structure

The SDK is organized into modules for better code organization:

• Platform (cilantro-sdk/platform) - Platform management and user operations
• User (cilantro-sdk/user) - User account operations
• Wallet (cilantro-sdk/wallet) - Wallet and blockchain operations
• Auth (cilantro-sdk/auth) - Universal authentication
• Subscriptions (cilantro-sdk/subscriptions) - Subscription management operations
• Plans (cilantro-sdk/plans) - Subscription plan management operations
• Transactions (cilantro-sdk/transactions) - Transaction history and status queries
• Delegated Keys (cilantro-sdk/delegated-keys) - Temporary key management for session-based signing
• Webhooks (cilantro-sdk/webhooks) - Webhook endpoint management for event notifications
• Platform Payments (cilantro-sdk/platform-payments) - Payment request management for platforms
• Info (cilantro-sdk/info) - API information and version details
• Utils (cilantro-sdk/utils) - Utility functions
• Helpers (cilantro-sdk/helpers) - Device key management and signer helpers

Complete API Reference

SDK Configuration (cilantro-sdk)

configure(config: SDKConfig): void

Initialize the SDK with configuration options.

Parameters:

• config (SDKConfig): Configuration object
  • apiKey? (string): API key for server-side authentication
  • jwt? (string): JWT token for user authentication
  • baseURL? (string): Custom API base URL (default: https://api.cilantro.gg)

Returns: void

Example:

import { configure } from 'cilantro-sdk';

configure({ 
  apiKey: 'your-api-key',
  baseURL: 'https://api.cilantro.gg'
});

setAuth(auth: { jwt?: string; apiKey?: string; platformApiKey?: string }): void

Update authentication credentials after initialization. API key is set from apiKey or platformApiKey.

Parameters:

• auth (object): Authentication credentials
  • jwt? (string): JWT access token
  • apiKey? (string): API key
  • platformApiKey? (string): Platform API key (alternative to apiKey)

Returns: void

Example:

import { setAuth } from 'cilantro-sdk';

setAuth({ jwt: 'your-jwt-token' });

clearAuth(): void

Clear all authentication credentials.

Parameters: None

Returns: void

Example:

import { clearAuth } from 'cilantro-sdk';

clearAuth();

generateDevicePublicKey(): Promise<string>

Generate a device public key for ECDH (P-256) encryption. Works in both browser and Node.js environments.

Parameters: None

Returns: Promise<string> - Base64-encoded P-256 ECDH public key (65 bytes, uncompressed format)

Example:

import { generateDevicePublicKey } from 'cilantro-sdk';

const devicePublicKey = await generateDevicePublicKey();
// Use with createEmailSigner or createPhoneSigner

updateDeviceIdentity(walletId: string, signerId: string, data: UpdateDeviceIdentityDto): Promise<WalletControllerUpdateDeviceIdentityResult>

Update device identity for a signer. Used to add or replace device keys associated with email/phone signers.

Parameters:

• walletId (string): Wallet ID
• signerId (string): Signer ID
• data (UpdateDeviceIdentityDto): Device identity data
  • devicePublicKey (string): Base64-encoded device public key
  • deviceId? (string): Optional device ID (for replacing existing device)
  • replace? (boolean): Whether to replace existing device

Returns: Promise<WalletControllerUpdateDeviceIdentityResult> - Updated device identity information

Example:

import { updateDeviceIdentity, generateDevicePublicKey } from 'cilantro-sdk';

const devicePublicKey = await generateDevicePublicKey();
await updateDeviceIdentity('wallet-id', 'signer-id', {
  devicePublicKey,
  replace: false
});

Platform Module (cilantro-sdk/platform)

Platform Management

create(data: CreatePlatformDto): Promise<PlatformControllerCreateResult>

Create a new platform account.

Parameters:

• data (CreatePlatformDto): Platform creation data
  • platformName (string): Platform name
  • email (string): Platform email
  • password (string): Platform password
  • billingCycle? ('monthly' | 'yearly'): Billing cycle preference

Returns: Promise<PlatformControllerCreateResult> - Created platform information

Example:

import { platform } from 'cilantro-sdk';

const newPlatform = await platform.create({
  platformName: 'My Platform',
  email: '[email protected]',
  password: 'SecurePass123!',
  billingCycle: 'monthly'
});

findAll(params?: PlatformControllerFindAllParams): Promise<PlatformControllerFindAllResult>

Get all platforms with optional filters.

Parameters:

• params? (PlatformControllerFindAllParams): Optional query parameters
  • page? (number): Page number for pagination
  • limit? (number): Items per page
  • search? (string): Search term

Returns: Promise<PlatformControllerFindAllResult> - Paginated list of platforms

Example:

const platforms = await platform.findAll({
  page: 1,
  limit: 20,
  search: 'example'
});

findOne(platformId: string): Promise<PlatformControllerFindOneResult>

Get platform by ID.

Parameters:

• platformId (string): Platform ID

Returns: Promise<PlatformControllerFindOneResult> - Platform details

Example:

const platformData = await platform.findOne('platform-id');

update(platformId: string, data: UpdatePlatformDto): Promise<PlatformControllerUpdateResult>

Update platform information.

Parameters:

• platformId (string): Platform ID
• data (UpdatePlatformDto): Update data
  • platformName? (string): New platform name
  • email? (string): New email
  • isActive? (boolean): Active status

Returns: Promise<PlatformControllerUpdateResult> - Updated platform information

Example:

await platform.update('platform-id', {
  platformName: 'Updated Name'
});

remove(platformId: string): Promise<PlatformControllerRemoveResult>

Remove (delete) a platform.

Parameters:

• platformId (string): Platform ID

Returns: Promise<PlatformControllerRemoveResult> - Removal confirmation

Example:

await platform.remove('platform-id');

getOwnProfile(): Promise<PlatformControllerGetOwnProfileResult>

Get current platform's profile (authenticated platform).

Parameters: None

Returns: Promise<PlatformControllerGetOwnProfileResult> - Current platform profile

Example:

const profile = await platform.getOwnProfile();

updateOwnProfile(data: UpdatePlatformDto): Promise<PlatformControllerUpdateOwnProfileResult>

Update current platform's profile.

Parameters:

• data (UpdatePlatformDto): Update data

Returns: Promise<PlatformControllerUpdateOwnProfileResult> - Updated profile

Example:

await platform.updateOwnProfile({
  platformName: 'New Name'
});

changePassword(data: ChangePasswordDto): Promise<PlatformControllerChangePasswordResult>

Change platform password.

Parameters:

• data (ChangePasswordDto): Password change data
  • currentPassword (string): Current password
  • newPassword (string): New password

Returns: Promise<PlatformControllerChangePasswordResult> - Password change confirmation

Example:

await platform.changePassword({
  currentPassword: 'old-password',
  newPassword: 'new-secure-password'
});

User Management

getUsers(platformId: string, params?: PlatformControllerGetUsersForPlatformParams): Promise<PlatformControllerGetUsersForPlatformResult>

Get all users for a platform.

Parameters:

• platformId (string): Platform ID
• params? (object): Optional query parameters
  • page? (number): Page number
  • limit? (number): Items per page
  • search? (string): Search term
  • isActive? (boolean): Filter by active status

Returns: Promise<PlatformControllerGetUsersForPlatformResult> - Paginated list of users

Example:

const users = await platform.getUsers('platform-id', {
  page: 1,
  limit: 20,
  isActive: true
});

createUser(platformId: string, data: CreateUserDto): Promise<PlatformControllerCreateUserForPlatformResult>

Create a new user for the platform.

Parameters:

• platformId (string): Platform ID
• data (CreateUserDto): User creation data
  • username (string): Username
  • email (string): Email address
  • password (string): Password

Returns: Promise<PlatformControllerCreateUserForPlatformResult> - Created user information

Example:

const user = await platform.createUser('platform-id', {
  username: 'johndoe',
  email: '[email protected]',
  password: 'SecurePass123!'
});

updateUser(platformId: string, userId: string, data: UpdateUserDto): Promise<PlatformControllerUpdateUserForPlatformResult>

Update user information.

Parameters:

• platformId (string): Platform ID
• userId (string): User ID
• data (UpdateUserDto): Update data
  • username? (string): New username
  • email? (string): New email
  • isActive? (boolean): Active status

Returns: Promise<PlatformControllerUpdateUserForPlatformResult> - Updated user information

Example:

await platform.updateUser('platform-id', 'user-id', {
  username: 'newusername'
});

removeUser(platformId: string, userId: string): Promise<PlatformControllerRemoveUserForPlatformResult>

Remove user from platform.

Parameters:

• platformId (string): Platform ID
• userId (string): User ID

Returns: Promise<PlatformControllerRemoveUserForPlatformResult> - Removal confirmation

Example:

await platform.removeUser('platform-id', 'user-id');

toggleUserActive(platformId: string, userId: string): Promise<PlatformControllerToggleUserActiveForPlatformResult>

Toggle user active status.

Parameters:

• platformId (string): Platform ID
• userId (string): User ID

Returns: Promise<PlatformControllerToggleUserActiveForPlatformResult> - Updated user status

Example:

await platform.toggleUserActive('platform-id', 'user-id');

Wallet Management

getWallets(platformId: string, params?: PlatformControllerGetWalletsForPlatformParams): Promise<PlatformControllerGetWalletsForPlatformResult>

Get all wallets for a platform (read-only).

Parameters:

• platformId (string): Platform ID
• params? (object): Optional query parameters
  • page? (number): Page number
  • limit? (number): Items per page

Returns: Promise<PlatformControllerGetWalletsForPlatformResult> - Paginated list of wallets

Example:

const wallets = await platform.getWallets('platform-id', {
  page: 1,
  limit: 20
});

Subscription Management

getSubscriptions(platformId: string, params?: PlatformControllerGetSubscriptionsForPlatformParams): Promise<PlatformControllerGetSubscriptionsForPlatformResult>

Get all subscriptions for a platform.

Parameters:

• platformId (string): Platform ID
• params? (object): Optional query parameters
  • status? (string): Filter by status
  • page? (number): Page number
  • limit? (number): Items per page

Returns: Promise<PlatformControllerGetSubscriptionsForPlatformResult> - Paginated list of subscriptions

Example:

const subscriptions = await platform.getSubscriptions('platform-id', {
  status: 'active'
});

getSubscriptionById(platformId: string, subscriptionId: string): Promise<PlatformControllerGetSubscriptionByIdResult>

Get subscription by ID.

Parameters:

• platformId (string): Platform ID
• subscriptionId (string): Subscription ID

Returns: Promise<PlatformControllerGetSubscriptionByIdResult> - Subscription details

Example:

const subscription = await platform.getSubscriptionById('platform-id', 'subscription-id');

renewSubscription(platformId: string, subscriptionId: string, data: RenewSubscriptionDto): Promise<PlatformControllerRenewSubscriptionResult>

Renew a subscription.

Parameters:

• platformId (string): Platform ID
• subscriptionId (string): Subscription ID
• data (RenewSubscriptionDto): Renewal data
  • extendByDays? (number): Days to extend
  • extendByMonths? (number): Months to extend

Returns: Promise<PlatformControllerRenewSubscriptionResult> - Renewed subscription

Example:

await platform.renewSubscription('platform-id', 'subscription-id', {
  extendByMonths: 1
});

upgradeSubscription(platformId: string, subscriptionId: string, data: UpgradeSubscriptionDto): Promise<PlatformControllerUpgradeSubscriptionResult>

Upgrade a subscription to a higher tier.

Parameters:

• platformId (string): Platform ID
• subscriptionId (string): Subscription ID
• data (UpgradeSubscriptionDto): Upgrade data
  • newPlanId (string): New plan ID
  • effectiveDate? (string): Effective date (ISO 8601)

Returns: Promise<PlatformControllerUpgradeSubscriptionResult> - Upgraded subscription

Example:

await platform.upgradeSubscription('platform-id', 'subscription-id', {
  newPlanId: 'premium-plan-id',
  effectiveDate: '2024-01-01T00:00:00Z'
});

downgradeSubscription(platformId: string, subscriptionId: string, data: DowngradeSubscriptionDto): Promise<PlatformControllerDowngradeSubscriptionResult>

Downgrade a subscription to a lower tier.

Parameters:

• platformId (string): Platform ID
• subscriptionId (string): Subscription ID
• data (DowngradeSubscriptionDto): Downgrade data
  • newPlanId (string): New plan ID

Returns: Promise<PlatformControllerDowngradeSubscriptionResult> - Downgraded subscription

Example:

await platform.downgradeSubscription('platform-id', 'subscription-id', {
  newPlanId: 'basic-plan-id'
});

cancelSubscription(platformId: string, subscriptionId: string, data: CancelSubscriptionDto): Promise<PlatformControllerCancelSubscriptionResult>

Cancel a subscription.

Parameters:

• platformId (string): Platform ID
• subscriptionId (string): Subscription ID
• data (CancelSubscriptionDto): Cancellation data
  • cancelAtPeriodEnd? (boolean): Cancel at period end

Returns: Promise<PlatformControllerCancelSubscriptionResult> - Cancellation confirmation

Example:

await platform.cancelSubscription('platform-id', 'subscription-id', {
  cancelAtPeriodEnd: true
});

getSubscriptionHistory(platformId: string, subscriptionId: string): Promise<PlatformControllerGetSubscriptionHistoryResult>

Get subscription history/audit trail.

Parameters:

• platformId (string): Platform ID
• subscriptionId (string): Subscription ID

Returns: Promise<PlatformControllerGetSubscriptionHistoryResult> - Subscription history

Example:

const history = await platform.getSubscriptionHistory('platform-id', 'subscription-id');

Payment Management

confirmPayment(platformId: string, data: ConfirmPaymentDto): Promise<PlatformControllerConfirmPaymentResult>

Confirm a payment transaction.

Parameters:

• platformId (string): Platform ID
• data (ConfirmPaymentDto): Payment confirmation data
  • paymentId (string): Payment ID
  • transactionId? (string): Transaction ID

Returns: Promise<PlatformControllerConfirmPaymentResult> - Payment confirmation

Example:

await platform.confirmPayment('platform-id', {
  paymentId: 'payment-id',
  transactionId: 'tx-id'
});

linkPayment(platformId: string, data: LinkPaymentDto): Promise<PlatformControllerLinkPaymentResult>

Link a payment method to the platform.

Parameters:

• platformId (string): Platform ID
• data (LinkPaymentDto): Payment method data
  • paymentMethodId (string): Payment method ID
  • isDefault? (boolean): Set as default

Returns: Promise<PlatformControllerLinkPaymentResult> - Linked payment method

Example:

await platform.linkPayment('platform-id', {
  paymentMethodId: 'pm-id',
  isDefault: true
});

getPaymentHistory(platformId: string, params?: PlatformControllerGetPaymentHistoryParams): Promise<PlatformControllerGetPaymentHistoryResult>

Get payment history for a platform.

Parameters:

• platformId (string): Platform ID
• params? (object): Optional query parameters
  • page? (number): Page number
  • limit? (number): Items per page
  • startDate? (string): Start date filter
  • endDate? (string): End date filter

Returns: Promise<PlatformControllerGetPaymentHistoryResult> - Paginated payment history

Example:

const payments = await platform.getPaymentHistory('platform-id', {
  page: 1,
  limit: 20
});

User Module (cilantro-sdk/user)

create(data: CreateUserDto): Promise<UserControllerCreateResult>

Create a new user account.

Parameters:

• data (CreateUserDto): User creation data
  • username (string): Username
  • email (string): Email address
  • password (string): Password

Returns: Promise<UserControllerCreateResult> - Created user information

Example:

import { user } from 'cilantro-sdk';

const newUser = await user.create({
  username: 'johndoe',
  email: '[email protected]',
  password: 'SecurePass123!'
});

findOne(userId: string): Promise<UserControllerFindOneResult>

Get user by ID.

Parameters:

• userId (string): User ID

Returns: Promise<UserControllerFindOneResult> - User details

Example:

const userData = await user.findOne('user-id');

update(userId: string, data: UpdateUserDto): Promise<UserControllerUpdateResult>

Update user information.

Parameters:

• userId (string): User ID
• data (UpdateUserDto): Update data
  • username? (string): New username
  • email? (string): New email
  • isActive? (boolean): Active status

Returns: Promise<UserControllerUpdateResult> - Updated user information

Example:

await user.update('user-id', {
  username: 'newusername',
  email: '[email protected]'
});

changePassword(userId: string, data: ChangePasswordDto): Promise<UserControllerChangePasswordResult>

Change user password.

Parameters:

• userId (string): User ID
• data (ChangePasswordDto): Password change data
  • currentPassword (string): Current password
  • newPassword (string): New password

Returns: Promise<UserControllerChangePasswordResult> - Password change confirmation

Example:

await user.changePassword('user-id', {
  currentPassword: 'old-password',
  newPassword: 'new-secure-password'
});

Wallet Module (cilantro-sdk/wallet)

Basic Operations

create(data: CreateWalletDto): Promise<WalletControllerCreateResult>

Create a new wallet.

Parameters:

• data (CreateWalletDto): Wallet creation data
  • name? (string): Wallet name
  • userId? (string): User ID (for user-controlled wallets)
  • walletMode? ('custodial' | 'nonCustodial'): Wallet mode
  • walletType? ('standard' | 'multisig'): Wallet type

Returns: Promise<WalletControllerCreateResult> - Created wallet information

• data.id (string): Wallet ID
• data.address (string): Solana wallet address
• data.publicKey (string): Wallet public key

Example:

import { wallet } from 'cilantro-sdk';

const newWallet = await wallet.create({
  name: 'My Wallet',
  userId: 'user-id',
  walletMode: 'nonCustodial'
});

console.log('Wallet Address:', newWallet.data.address);

findAll(params?: WalletControllerFindAllParams): Promise<WalletControllerFindAllResult>

Get all wallets with optional filters.

Parameters:

• params? (WalletControllerFindAllParams): Optional query parameters
  • page? (number): Page number
  • limit? (number): Items per page
  • userId? (string): Filter by user ID
  • walletMode? (string): Filter by wallet mode

Returns: Promise<WalletControllerFindAllResult> - Paginated list of wallets

Example:

const wallets = await wallet.findAll({
  page: 1,
  limit: 20,
  walletMode: 'nonCustodial'
});

findOne(walletId: string): Promise<WalletControllerFindOneResult>

Get wallet by ID.

Parameters:

• walletId (string): Wallet ID

Returns: Promise<WalletControllerFindOneResult> - Wallet details

Example:

const walletData = await wallet.findOne('wallet-id');

update(walletId: string, data: UpdateWalletDto): Promise<WalletControllerUpdateResult>

Update wallet information.

Parameters:

• walletId (string): Wallet ID
• data (UpdateWalletDto): Update data
  • name? (string): New wallet name
  • isActive? (boolean): Active status

Returns: Promise<WalletControllerUpdateResult> - Updated wallet information

Example:

await wallet.update('wallet-id', {
  name: 'Updated Wallet Name'
});

remove(walletId: string): Promise<WalletControllerRemoveResult>

Remove (delete) a wallet.

Parameters:

• walletId (string): Wallet ID

Returns: Promise<WalletControllerRemoveResult> - Removal confirmation

Example:

await wallet.remove('wallet-id');

findByAddress(address: string): Promise<WalletControllerFindByAddressResult>

Find wallet by Solana address.

Parameters:

• address (string): Solana wallet address

Returns: Promise<WalletControllerFindByAddressResult> - Wallet details

Example:

const walletData = await wallet.findByAddress('DYw8jCTfwHNRJhhmFcbXvVDTqWMEVFBX6ZKUmG5CNSKK');

getTotalBalance(walletId: string): Promise<WalletControllerGetTotalBalanceResult>

Get total balance across all wallets for a user.

Parameters:

• walletId (string): Wallet ID (used to identify user)

Returns: Promise<WalletControllerGetTotalBalanceResult> - Total balance information

• data.totalSOL (number): Total SOL balance in lamports
• data.totalTokens (number): Total token balance

Example:

const balance = await wallet.getTotalBalance('wallet-id');
console.log('Total SOL:', balance.data.totalSOL / 1e9); // Convert lamports to SOL

Status Management

activate(walletId: string): Promise<WalletControllerActivateWalletResult>

Activate a wallet.

Parameters:

• walletId (string): Wallet ID

Returns: Promise<WalletControllerActivateWalletResult> - Activation confirmation

Example:

await wallet.activate('wallet-id');

deactivate(walletId: string): Promise<WalletControllerDeactivateWalletResult>

Deactivate a wallet.

Parameters:

• walletId (string): Wallet ID

Returns: Promise<WalletControllerDeactivateWalletResult> - Deactivation confirmation

Example:

await wallet.deactivate('wallet-id');

Transactions

sendSOL(walletId: string, data: SendSolDto): Promise<WalletControllerSendSOLResult>

Send SOL (custodial mode - server signs the transaction).

Parameters:

• walletId (string): Wallet ID
• data (SendSolDto): Transaction data
  • recipientAddress (string): Recipient Solana address
  • amountLamports (number): Amount in lamports (1 SOL = 1,000,000,000 lamports)

Returns: Promise<WalletControllerSendSOLResult> - Transaction result

• data.signature (string): Transaction signature
• data.status (string): Transaction status

Example:

const result = await wallet.sendSOL('wallet-id', {
  recipientAddress: 'DYw8jCTfwHNRJhhmFcbXvVDTqWMEVFBX6ZKUmG5CNSKK',
  amountLamports: 1000000000 // 1 SOL
});

console.log('Transaction Signature:', result.data.signature);

sendSOLNonCustodial(walletId: string, data: SendSolNonCustodialDto): Promise<WalletControllerSendSOLNonCustodialResult>

Send SOL (non-custodial mode - requires client-side signing).

Parameters:

• walletId (string): Wallet ID
• data (SendSolNonCustodialDto): Transaction data
  • recipientAddress (string): Recipient address
  • amountLamports (number): Amount in lamports
  • signedTransaction (string): Base64-encoded signed transaction

Returns: Promise<WalletControllerSendSOLNonCustodialResult> - Transaction result

Example:

// First prepare and sign transaction client-side, then submit
const result = await wallet.sendSOLNonCustodial('wallet-id', {
  recipientAddress: 'DYw8jCTfwHNRJhhmFcbXvVDTqWMEVFBX6ZKUmG5CNSKK',
  amountLamports: 1000000000,
  signedTransaction: signedTxBase64
});

sendSPL(walletId: string, data: SendSplDto): Promise<WalletControllerSendSPLResult>

Send SPL token (custodial mode).

Parameters:

• walletId (string): Wallet ID
• data (SendSplDto): Transaction data
  • recipientAddress (string): Recipient address
  • mintAddress (string): Token mint address
  • amount (number): Token amount (in token's decimal places)

Returns: Promise<WalletControllerSendSPLResult> - Transaction result

Example:

const result = await wallet.sendSPL('wallet-id', {
  recipientAddress: 'DYw8jCTfwHNRJhhmFcbXvVDTqWMEVFBX6ZKUmG5CNSKK',
  mintAddress: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v', // USDC
  amount: 1000000 // 1 USDC (6 decimals)
});

sendSPLNonCustodial(walletId: string, data: SendSplNonCustodialDto): Promise<WalletControllerSendSPLNonCustodialResult>

Send SPL token (non-custodial mode).

Parameters:

• walletId (string): Wallet ID
• data (SendSplNonCustodialDto): Transaction data
  • recipientAddress (string): Recipient address
  • mintAddress (string): Token mint address
  • amount (number): Token amount
  • signedTransaction (string): Base64-encoded signed transaction

Returns: Promise<WalletControllerSendSPLNonCustodialResult> - Transaction result

Example:

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

executeInstructionNonCustodial(walletId: string, data: ExecuteInstructionNonCustodialDto): Promise<WalletControllerExecuteInstructionNonCustodialResult>

Execute a custom Solana instruction (non-custodial mode).

Parameters:

• walletId (string): Wallet ID
• data (ExecuteInstructionNonCustodialDto): Instruction data
  • programId (string): Program ID
  • accounts (array): Account keys
  • data (string): Instruction data
  • signedTransaction (string): Base64-encoded signed transaction

Returns: Promise<WalletControllerExecuteInstructionNonCustodialResult> - Transaction result

Example:

const result = await wallet.executeInstructionNonCustodial('wallet-id', {
  programId: 'program-id',
  accounts: [...],
  data: 'instruction-data',
  signedTransaction: signedTxBase64
});

sendTransaction(walletId: string, data: SendTransactionDto): Promise<WalletControllerSendTransactionResult>

Send a custom transaction.

Parameters:

• walletId (string): Wallet ID
• data (SendTransactionDto): Transaction data
  • transaction (string): Base64-encoded transaction
  • signers? (array): Signer public keys

Returns: Promise<WalletControllerSendTransactionResult> - Transaction result

Example:

const result = await wallet.sendTransaction('wallet-id', {
  transaction: transactionBase64
});

simulateTransaction(walletId: string, data: SimulateTransactionDto): Promise<WalletControllerSimulateTransactionResult>

Simulate a transaction without executing it.

Parameters:

• walletId (string): Wallet ID
• data (SimulateTransactionDto): Transaction data
  • transaction (string): Base64-encoded transaction

Returns: Promise<WalletControllerSimulateTransactionResult> - Simulation result

• data.logs (array): Transaction logs
• data.err (object | null): Error if simulation failed
• data.unitsConsumed (number): Compute units consumed

Example:

const simulation = await wallet.simulateTransaction('wallet-id', {
  transaction: transactionBase64
});

if (simulation.data.err) {
  console.error('Simulation failed:', simulation.data.err);
} else {
  console.log('Units consumed:', simulation.data.unitsConsumed);
}

prepareTransaction(walletId: string, data: PrepareTransactionDto): Promise<WalletControllerPrepareTransactionResult>

Prepare a transaction for signing.

Parameters:

• walletId (string): Wallet ID
• data (PrepareTransactionDto): Transaction preparation data
  • type ('transfer' | 'tokenTransfer' | 'custom'): Transaction type
  • recipientAddress? (string): Recipient address (for transfers)
  • amount? (number): Amount
  • mintAddress? (string): Token mint address (for token transfers)
  • instructions? (array): Custom instructions

Returns: Promise<WalletControllerPrepareTransactionResult> - Prepared transaction

• data.transaction (string): Base64-encoded unsigned transaction
• data.message (string): Transaction message for signing

Example:

const prepared = await wallet.prepareTransaction('wallet-id', {
  type: 'transfer',
  recipientAddress: 'DYw8jCTfwHNRJhhmFcbXvVDTqWMEVFBX6ZKUmG5CNSKK',
  amount: 1000000000
});

// Sign the transaction client-side, then submit
const signedTx = await signTransaction(prepared.data.transaction);
await wallet.submitTransaction('wallet-id', {
  signedTransaction: signedTx
});

submitTransaction(walletId: string, data: SubmitTransactionDto): Promise<WalletControllerSubmitTransactionResult>

Submit a signed transaction.

Parameters:

• walletId (string): Wallet ID
• data (SubmitTransactionDto): Transaction data
  • signedTransaction (string): Base64-encoded signed transaction

Returns: Promise<WalletControllerSubmitTransactionResult> - Transaction result

• data.signature (string): Transaction signature
• data.status (string): Transaction status

Example:

const result = await wallet.submitTransaction('wallet-id', {
  signedTransaction: signedTxBase64
});

console.log('Transaction Signature:', result.data.signature);

signMessage(walletId: string, data: SignMessageDto): Promise<WalletControllerSignMessageResult>

Sign a message with the wallet.

Parameters:

• walletId (string): Wallet ID
• data (SignMessageDto): Message data
  • message (string): Message to sign (will be base64 encoded)
  • signerId? (string): Specific signer ID to use

Returns: Promise<WalletControllerSignMessageResult> - Signature result

• data.signature (string): Message signature
• data.publicKey (string): Signer public key

Example:

const result = await wallet.signMessage('wallet-id', {
  message: 'Hello, World!',
  signerId: 'signer-id'
});

console.log('Signature:', result.data.signature);

Wallet Lifecycle Management

closeWallet(walletId: string, data: CloseWalletDto): Promise<WalletControllerCloseWalletResult>

Close a wallet only if it is completely empty (no SOL above rent-exempt threshold, no SPL tokens, and no NFTs). If the wallet contains assets, the operation will be rejected. Use emergencySend to transfer assets and close in one operation, or transfer assets individually first.

Parameters:

• walletId (string): Wallet ID
• data (CloseWalletDto): Close wallet data
  • recipientAddress (string): Recipient Solana wallet address to receive remaining lamports from the closed wallet

Returns: Promise<WalletControllerCloseWalletResult> - Wallet closure confirmation

Example:

const result = await wallet.closeWallet('wallet-id', {
  recipientAddress: 'DYw8jCTfwHNRJhhmFcbXvVDTqWMEVFBX6ZKUmG5CNSKK'
});

console.log('Wallet closed:', result.data.success);

emergencySend(walletId: string, data: EmergencySendDto): Promise<WalletControllerEmergencySendResult>

Transfer all wallet assets (SOL, SPL tokens, and NFTs) to a recipient address before closing the wallet. This is a safety mechanism to ensure no assets are lost during wallet closure. Currently only supports custodial wallets. Non-custodial wallets must transfer assets individually first.

Parameters:

• walletId (string): Wallet ID
• data (EmergencySendDto): Emergency send data
  • recipientAddress (string): Recipient Solana address to transfer all assets to

Returns: Promise<WalletControllerEmergencySendResult> - Transaction results with asset transfers

Example:

const result = await wallet.emergencySend('wallet-id', {
  recipientAddress: 'DYw8jCTfwHNRJhhmFcbXvVDTqWMEVFBX6ZKUmG5CNSKK'
});

console.log('All assets transferred and wallet closed:', result.data.success);

Batch Operations

batchCreate(data: BatchCreateWalletDto): Promise<WalletControllerBatchCreateWalletsResult>

Create multiple wallets in batch.

Parameters:

• data (BatchCreateWalletDto): Batch creation data
  • wallets (array): Array of wallet creation data
    • name? (string): Wallet name
    • userId? (string): User ID

Returns: Promise<WalletControllerBatchCreateWalletsResult> - Created wallets

Example:

const result = await wallet.batchCreate({
  wallets: [
    { name: 'Wallet 1', userId: 'user-id' },
    { name: 'Wallet 2', userId: 'user-id' }
  ]
});

batchSendSOL(walletId: string, data: BatchSendSolDto): Promise<WalletControllerBatchSendSOLResult>

Send SOL to multiple recipients in a single transaction.

Parameters:

• walletId (string): Wallet ID
• data (BatchSendSolDto): Batch send data
  • recipients (array): Array of recipients
    • address (string): Recipient address
    • amountLamports (number): Amount in lamports

Returns: Promise<WalletControllerBatchSendSOLResult> - Transaction result

Example:

const result = await wallet.batchSendSOL('wallet-id', {
  recipients: [
    { address: 'address1', amountLamports: 1000000000 },
    { address: 'address2', amountLamports: 2000000000 }
  ]
});

batchSendSPL(walletId: string, data: BatchSendSplDto): Promise<WalletControllerBatchSendSPLResult>

Send SPL tokens to multiple recipients.

Parameters:

• walletId (string): Wallet ID
• data (BatchSendSplDto): Batch send data
  • mintAddress (string): Token mint address
  • recipients (array): Array of recipients
    • address (string): Recipient address
    • amount (number): Token amount

Returns: Promise<WalletControllerBatchSendSPLResult> - Transaction result

Example:

const result = await wallet.batchSendSPL('wallet-id', {
  mintAddress: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
  recipients: [
    { address: 'address1', amount: 1000000 },
    { address: 'address2', amount: 2000000 }
  ]
});

NFTs & Tokens

mintNFT(walletId: string, data: MintNftDto): Promise<WalletControllerMintNFTResult>

Mint an NFT with full metadata.

Parameters:

• walletId (string): Wallet ID
• data (MintNftDto): NFT minting data
  • name (string): NFT name
  • symbol? (string): NFT symbol
  • uri? (string): Metadata URI
  • metadata? (object): Full metadata object
  • recipientAddress? (string): Recipient address (defaults to wallet address)

Returns: Promise<WalletControllerMintNFTResult> - Minted NFT information

• data.mintAddress (string): NFT mint address
• data.tokenAddress (string): Token account address

Example:

const result = await wallet.mintNFT('wallet-id', {
  name: 'My NFT',
  symbol: 'MNFT',
  uri: 'https://example.com/metadata.json',
  metadata: {
    description: 'My awesome NFT',
    image: 'https://example.com/image.png'
  }
});

console.log('NFT Mint Address:', result.data.mintAddress);

mintNFTSimple(walletId: string, data: MintNftSimpleDto): Promise<WalletControllerMintNFTSimpleResult>

Mint an NFT with simplified parameters.

Parameters:

• walletId (string): Wallet ID
• data (MintNftSimpleDto): Simplified NFT data
  • name (string): NFT name
  • uri? (string): Metadata URI

Returns: Promise<WalletControllerMintNFTSimpleResult> - Minted NFT information

Example:

const result = await wallet.mintNFTSimple('wallet-id', {
  name: 'Simple NFT',
  uri: 'https://example.com/metadata.json'
});

mintToken(walletId: string, data: MintTokenDto): Promise<WalletControllerMintTokenResult>

Mint an SPL token.

Parameters:

• walletId (string): Wallet ID
• data (MintTokenDto): Token minting data
  • decimals (number): Token decimals (0-9)
  • amount (number): Initial supply
  • tokenStandard? ('fungible' | 'nonFungible'): Token standard
  • name? (string): Token name
  • symbol? (string): Token symbol

Returns: Promise<WalletControllerMintTokenResult> - Minted token information

• data.mintAddress (string): Token mint address

Example:

const result = await wallet.mintToken('wallet-id', {
  decimals: 9,
  amount: 1000000000,
  name: 'My Token',
  symbol: 'MTK'
});

console.log('Token Mint Address:', result.data.mintAddress);

Assets

getAssets(walletId: string, params?: WalletControllerGetWalletAssetsParams): Promise<WalletControllerGetWalletAssetsResult>

Get wallet assets (tokens, NFTs, SOL).

Parameters:

• walletId (string): Wallet ID
• params? (WalletControllerGetWalletAssetsParams): Optional query parameters
  • assetType? ('sol' | 'token' | 'nft'): Filter by asset type
  • page? (number): Page number
  • limit? (number): Items per page

Returns: Promise<WalletControllerGetWalletAssetsResult> - Paginated list of assets

• data.assets (array): Array of asset objects
  • type (string): Asset type
  • balance (number): Asset balance
  • mintAddress? (string): Mint address (for tokens/NFTs)

Example:

const assets = await wallet.getAssets('wallet-id', {
  assetType: 'token',
  page: 1,
  limit: 20
});

console.log('Assets:', assets.data.assets);

syncAssets(walletId: string): Promise<WalletControllerSyncWalletAssetsResult>

Sync wallet assets from blockchain.

Parameters:

• walletId (string): Wallet ID

Returns: Promise<WalletControllerSyncWalletAssetsResult> - Sync result

Example:

await wallet.syncAssets('wallet-id');

Custody

getCustodyInfo(walletId: string): Promise<WalletControllerGetWalletCustodyInfoResult>

Get wallet custody information.

Parameters:

• walletId (string): Wallet ID

Returns: Promise<WalletControllerGetWalletCustodyInfoResult> - Custody information

• data.walletMode (string): Wallet mode (custodial/nonCustodial)
• data.signers (array): List of signers

Example:

const custodyInfo = await wallet.getCustodyInfo('wallet-id');
console.log('Wallet Mode:', custodyInfo.data.walletMode);

Signer Management

createEmailSigner(walletId: string, data: CreateEmailSignerDto): Promise<WalletControllerCreateEmailSignerResult>

Create an email signer for the wallet.

Parameters:

• walletId (string): Wallet ID
• data (CreateEmailSignerDto): Email signer data
  • email (string): Email address
  • devicePublicKey (string): Base64-encoded device public key (P-256 ECDH)

Returns: Promise<WalletControllerCreateEmailSignerResult> - Created signer information

• data.signerId (string): Signer ID
• data.deviceId (string): Device ID

Example:

import { generateDevicePublicKey } from 'cilantro-sdk';

const devicePublicKey = await generateDevicePublicKey();
const signer = await wallet.createEmailSigner('wallet-id', {
  email: '[email protected]',
  devicePublicKey
});

console.log('Signer ID:', signer.data.signerId);

createPhoneSigner(walletId: string, data: CreatePhoneSignerDto): Promise<WalletControllerCreatePhoneSignerResult>

Create a phone signer for the wallet.

Parameters:

• walletId (string): Wallet ID
• data (CreatePhoneSignerDto): Phone signer data
  • phone (string): Phone number (E.164 format)
  • devicePublicKey (string): Base64-encoded device public key

Returns: Promise<WalletControllerCreatePhoneSignerResult> - Created signer information

Example:

const devicePublicKey = await generateDevicePublicKey();
const signer = await wallet.createPhoneSigner('wallet-id', {
  phone: '+1234567890',
  devicePublicKey
});

startPasskeyRegistration(walletId: string, data: StartPasskeyRegistrationDto): Promise<WalletControllerStartPasskeyRegistrationResult>

Start passkey (WebAuthn) registration process.

Parameters:

• walletId (string): Wallet ID
• data (StartPasskeyRegistrationDto): Registration data
  • credentialName? (string): Name for the passkey

Returns: Promise<WalletControllerStartPasskeyRegistrationResult> - Registration options

• data.options (object): WebAuthn registration options (for browser)

Example:

const registration = await wallet.startPasskeyRegistration('wallet-id', {
  credentialName: 'My Passkey'
});

// Use registration.data.options with WebAuthn API
const credential = await navigator.credentials.create({
  publicKey: registration.data.options
});

// Then verify the registration
await wallet.verifyPasskeyRegistration('wallet-id', {
  credential: credential
});

verifyPasskeyRegistration(walletId: string, data: PasskeyRegistrationDto): Promise<WalletControllerVerifyPasskeyRegistrationResult>

Verify and complete passkey registration.

Parameters:

• walletId (string): Wallet ID
• data (PasskeyRegistrationDto): Registration verification data
  • credential (object): WebAuthn credential from browser

Returns: Promise<WalletControllerVerifyPasskeyRegistrationResult> - Verified signer information

Example:

// After creating credential with WebAuthn API
await wallet.verifyPasskeyRegistration('wallet-id', {
  credential: credentialResponse
});

startPasskeyAuthentication(walletId: string, data: StartPasskeyAuthenticationDto): Promise<WalletControllerStartPasskeyAuthenticationResult>

Start passkey authentication process.

Parameters:

• walletId (string): Wallet ID
• data (StartPasskeyAuthenticationDto): Authentication data
  • credentialId? (string): Specific credential ID to use

Returns: Promise<WalletControllerStartPasskeyAuthenticationResult> - Authentication options

Example:

const auth = await wallet.startPasskeyAuthentication('wallet-id', {});

// Use auth.data.options with WebAuthn API
const assertion = await navigator.credentials.get({
  publicKey: auth.data.options
});

// Then verify
await wallet.verifyPasskeyAuthentication('wallet-id', {
  credential: assertion
});

verifyPasskeyAuthentication(walletId: string, data: PasskeyAuthenticationDto): Promise<WalletControllerVerifyPasskeyAuthenticationResult>

Verify passkey authentication.

Parameters:

• walletId (string): Wallet ID
• data (PasskeyAuthenticationDto): Authentication verification data
  • credential (object): WebAuthn assertion from browser

Returns: Promise<WalletControllerVerifyPasskeyAuthenticationResult> - Authentication result

Example:

await wallet.verifyPasskeyAuthentication('wallet-id', {
  credential: assertionResponse
});

createExternalWalletSigner(walletId: string, data: CreateExternalWalletSignerDto): Promise<WalletControllerCreateExternalWalletSignerResult>

Create an external wallet signer (e.g., Phantom, Solflare).

Parameters:

• walletId (string): Wallet ID
• data (CreateExternalWalletSignerDto): External wallet data
  • publicKey (string): External wallet public key
  • walletName? (string): Wallet name (e.g., 'Phantom')

Returns: Promise<WalletControllerCreateExternalWalletSignerResult> - Created signer information

Example:

// After connecting to external wallet
const signer = await wallet.createExternalWalletSigner('wallet-id', {
  publicKey: externalWallet.publicKey.toString(),
  walletName: 'Phantom'
});

createApiKeySigner(walletId: string, data: CreateApiKeySignerDto): Promise<WalletControllerCreateApiKeySignerResult>

Create an API key signer for server-side operations.

Parameters:

• walletId (string): Wallet ID
• data (CreateApiKeySignerDto): API key signer data
  • name? (string): Signer name
  • permissions? (object): Signer permissions

Returns: Promise<WalletControllerCreateApiKeySignerResult> - Created signer information

Example:

const signer = await wallet.createApiKeySigner('wallet-id', {
  name: 'Server Signer',
  permissions: {
    canTransfer: true,
    maxAmount: 1000000000
  }
});

getSignerById(walletId: string, signerId: string): Promise<WalletControllerGetSignerByIdResult>

Get signer by ID.

Parameters:

• walletId (string): Wallet ID
• signerId (string): Signer ID

Returns: Promise<WalletControllerGetSignerByIdResult> - Signer details

Example:

const signer = await wallet.getSignerById('wallet-id', 'signer-id');

updateSigner(walletId: string, signerId: string, data: UpdateSignerDto): Promise<WalletControllerUpdateSignerResult>

Update signer information.

Parameters:

• walletId (string): Wallet ID
• signerId (string): Signer ID
• data (UpdateSignerDto): Update data
  • isActive? (boolean): Active status
  • name? (string): Signer name

Returns: Promise<WalletControllerUpdateSignerResult> - Updated signer information

Example:

await wallet.updateSigner('wallet-id', 'signer-id', {
  isActive: false,
  name: 'Updated Name'
});

deleteSigner(walletId: string, signerId: string): Promise<WalletControllerDeleteSignerResult>

Delete a signer.

Parameters:

• walletId (string): Wallet ID
• signerId (string): Signer ID

Returns: Promise<WalletControllerDeleteSignerResult> - Deletion confirmation

Example:

await wallet.deleteSigner('wallet-id', 'signer-id');

addSigner(walletId: string, data: AddSignerDto): Promise<WalletControllerAddSignerResult>

Add a signer to the wallet.

Parameters:

• walletId (string): Wallet ID
• data (AddSignerDto): Signer data
  • signerType ('email' | 'phone' | 'passkey' | 'external' | 'apiKey'): Signer type
  • signerConfig (object): Signer-specific configuration

Returns: Promise<WalletControllerAddSignerResult> - Added signer information

Example:

await wallet.addSigner('wallet-id', {
  signerType: 'email',
  signerConfig: {
    email: '[email protected]',
    devicePublicKey: await generateDevicePublicKey()
  }
});

listSigners(walletId: string): Promise<WalletControllerListSignersResult>

List all signers for a wallet.

Parameters:

• walletId (string): Wallet ID

Returns: Promise<WalletControllerListSignersResult> - List of signers

• data.authenticationSigners (array): Email/phone/passkey signers
• data.onChainSigners (array): External/API key signers

Example:

const signers = await wallet.listSigners('wallet-id');
console.log('Authentication Signers:', signers.data.authenticationSigners);
console.log('On-Chain Signers:', signers.data.onChainSigners);

removeSigner(walletId: string, signerId: string): Promise<WalletControllerRemoveSignerResult>

Remove a signer from the wallet.

Parameters:

• walletId (string): Wallet ID
• signerId (string): Signer ID

Returns: Promise<WalletControllerRemoveSignerResult> - Removal confirmation

Example:

await wallet.removeSigner('wallet-id', 'signer-id');

updateSignerPermissions(walletId: string, signerId: string, data: UpdateSignerPermissionsDto): Promise<WalletControllerUpdateSignerPermissionsResult>

Update signer permissions.

Parameters:

• walletId (string): Wallet ID
• signerId (string): Signer ID
• data (UpdateSignerPermissionsDto): Permission data
  • canTransfer? (boolean): Can transfer funds
  • maxAmount?