Cilantro Smart SDK

The Cilantro ecosystem provides two packages for building with Cilantro Smart Wallets:

• cilantro-sdk — Low-level API client for the Cilantro Smart Wallet backend. It handles auth, wallets, signers, delegated keys, message/transaction signing, address book, analytics, and more. Use it in Node/backend scripts or when you need full control and no React.
• cilantro-react — React bindings that wrap the SDK: a root CilantroProvider (auth + optional storage), hooks like useAuth and useWallet, and optional UI (e.g. SocialLoginButtons). Use it in React/Next.js apps so you don't manage JWT or SDK auth manually.

When to use which: Prefer cilantro-react in React apps (auth and wallet context are handled for you). Use cilantro-sdk directly in non-React environments (e.g. server, scripts) or when building fully custom UI and flows.

What Makes Cilantro Smart Wallets Different?

Traditional Solana wallets are simple keypairs - whoever has the private key controls the wallet. Cilantro Smart Wallets are on-chain programs that implement sophisticated access control:

Key Concepts

Smart Contract Wallet (Program-Derived Address)

A Cilantro wallet is not just a keypair - it's a Program Derived Address (PDA) controlled by an on-chain smart contract:

1. Wallet Creation: The Cilantro program generates a PDA on Solana
2. Signer Registration: Signers are registered on-chain with their public keys
3. Transaction Authorization: Transactions must be approved by registered signers
4. On-Chain Verification: The smart contract validates signatures before executing

Example Structure:

Wallet (PDA: 7xK...abc)
├── Admin Signer: email:[email protected] (Primary controller)
├── Recovery Signer: phone:+1234567890 (Backup access)
└── Delegated Signer: API key (Limited permissions)

Admin Signer - The Primary Controller

The admin signer is the first and most powerful signer added during wallet creation:

• Full Control: Can add/remove other signers
• Transaction Authority: Can authorize any transaction
• Wallet Configuration: Can update wallet settings
• Transfer Ownership: Can change admin to a different signer

Custody Models

Platform-Controlled (Custodial):

• Platform has signing keys
• Pros: Simple UX, no user key management, instant transactions
• Cons: Platform can access funds, regulatory implications
• Use case: Gaming credits, reward points, managed accounts

User-Controlled (Non-Custodial):

• User has signing keys (via device keys, passkeys, or external wallet)
• Pros: True ownership, regulatory compliance, trustless
• Cons: User responsible for key security, recovery needed if keys lost
• Use case: DeFi, personal wallets, high-value assets

Features

What You Can Build

With the Cilantro Smart SDK, you can build:

• Multi-tenant wallet platforms - Manage wallets for multiple users or organizations
• DeFi applications - Non-custodial wallets for trading, lending, and staking
• Gaming economies - In-game currency and NFT rewards with instant transactions
• Payment processing systems - Handle SOL and token transfers securely
• NFT marketplaces - Mint and manage NFTs with metadata
• Social recovery systems - Email/phone-based wallet recovery
• Subscription services - Manage plans and subscriptions for your platform

Installation

npm install cilantro-react cilantro-sdk

In browser apps, import the SDK polyfills once at the top of your entry (e.g. root layout) before any SDK usage:

import 'cilantro-sdk/polyfills';

Quick Example

React (Next.js): Wrap your app with CilantroProvider, then use useAuth and useWallet. See cilantro-react Setup for the full setup.

SDK only (Node/backend or custom UI): Configure once with configure({ apiKey }), then create wallets and call the API. Responses use a data field; destructure { data } or use extractResponseData from cilantro-react.

import { configure } from 'cilantro-sdk';
import { create, findAll } from 'cilantro-sdk/wallet';

configure({ apiKey: process.env.PLATFORM_API_KEY });

// Create a wallet — response has { data }; walletId = data.id
const { data } = await create({ name: 'Gaming Wallet', userId: 'user-id' });
const walletId = data.id;

// List wallets
const wallets = await findAll();

See Quickstart for both React and SDK-only paths.

Next Steps