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
  • 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
• 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
setAuth({ jwt: authResult.data.jwt });

// 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 }): void

Update authentication credentials after initialization. Useful when credentials change (e.g., after login or token refresh).

Parameters:

• auth (object): Authentication credentials
  • jwt? (string): JWT token to set
  • apiKey? (string): API key to set

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.jwt });

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

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
• 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 }): void

Update authentication credentials after initialization.

Parameters:

• auth (object): Authentication credentials
  • jwt? (string): JWT token
  • apiKey? (string): API key

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);

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? (number): Maximum transfer amount
  • allowedPrograms? (array): Allowed program IDs

Returns: Promise<WalletControllerUpdateSignerPermissionsResult> - Updated permissions

Example:

await wallet.updateSignerPermissions('wallet-id', 'signer-id', {
  canTransfer: true,
  maxAmount: 1000000000,
  allowedPrograms: ['program-id-1']
});

getDeviceEncryptedSecret(walletId: string, signerId: string, params: WalletControllerGetDeviceEncryptedSecretParams): Promise<WalletControllerGetDeviceEncryptedSecretResult>

Get device encrypted secret for deriving signer keypair.

Parameters:

• walletId (string): Wallet ID
• signerId (string): Signer ID
• params (WalletControllerGetDeviceEncryptedSecretParams): Query parameters
  • devicePublicKey (string): Device public key
  • deviceId? (string): Device ID

Returns: Promise<WalletControllerGetDeviceEncryptedSecretResult> - Encrypted secret

• data.encryptedSecret (string): Encrypted secret (base64)
• data.deviceId (string): Device ID

Example:

const secret = await wallet.getDeviceEncryptedSecret('wallet-id', 'signer-id', {
  devicePublicKey: devicePublicKey
});

// Use with helpers.deriveSignerKeypair() to get keypair

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

Update device identity for a signer.

Parameters:

• walletId (string): Wallet ID
• signerId (string): Signer ID
• data (UpdateDeviceIdentityDto): Device identity data
  • devicePublicKey (string): New device public key
  • deviceId? (string): Device ID (for replacing)
  • replace? (boolean): Replace existing device

Returns: Promise<WalletControllerUpdateDeviceIdentityResult> - Updated device identity

Example:

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

Auth Module (cilantro-sdk/auth)

login(credentials: CommonLoginDto, options?: AuthRequestOptions): Promise<AuthControllerLoginResult>

Authenticate as platform or user. Returns user type and appropriate JWT token.

Parameters:

• credentials (CommonLoginDto): Login credentials
  • usernameOrEmail (string): Username or email address
  • password (string): Password
• options? (AuthRequestOptions): Optional request options (axios config)

Returns: Promise<AuthControllerLoginResult> - Login response with JWT token and user information

• data.jwt (string): JWT token for authentication
• data.userType (string): User type (platform or user)
• data.user (object): User information

Example:

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

const result = await login({
  usernameOrEmail: '[email protected]',
  password: 'SecurePass123!'
});

console.log('JWT Token:', result.data.jwt);
console.log('User Type:', result.data.userType);

loginAndSetAuth(credentials: CommonLoginDto, options?: AuthRequestOptions): Promise<AuthControllerLoginResult>

Login and automatically set authentication credentials. This is a convenience function that calls `