Address Book Module

The address book module provides CRUD and verify for saved Solana addresses. Responses are controller-style; use extractResponseData(response) to get the payload. See Response and errors.

Import

import { 
  create,
  findAll,
  findOne,
  update,
  remove,
  verifyAddress
} from 'cilantro-sdk/address-book';
import type { CreateAddressBookDto, UpdateAddressBookDto } from 'cilantro-sdk/address-book';

Basic Operations

create(options)

Add a new address to your address book.

const createResult = await create({ address: 'So1ana...', label: 'My Contact', tags: [] });
const entry = extractResponseData(createResult);

findAll(options?)

Get all addresses in your address book with optional filtering and pagination.

const listResult = await findAll();
const entries = extractResponseData(listResult) ?? [];

findOne(id)

Get a specific address book entry by ID.

const oneResult = await findOne(entryId);
const entry = extractResponseData(oneResult);

update(id, options)

Update an address book entry (e.g. label, tags).

await update(entryId, { label: 'New Label' });

remove(id)

Delete an address from your address book.

await remove(entryId);

verifyAddress(options)

Verify that an address is a valid Solana address (e.g. on-chain check).

const validResult = await verifyAddress({ address: 'So1ana...' });
const valid = extractResponseData(validResult);

Usage Examples

Organizing Addresses with Tags

// Add addresses with different tags
await create({
  address: 'Address1...',
  label: 'Exchange Wallet',
  tags: ['exchange', 'trading']
});

await create({
  address: 'Address2...',
  label: 'DeFi Wallet',
  tags: ['defi', 'yield-farming']
});

await create({
  address: 'Address3...',
  label: 'Personal Wallet',
  tags: ['personal', 'savings']
});

// Retrieve addresses by category
const exchangeAddresses = await findAll({ tag: 'exchange' });
const defiAddresses = await findAll({ tag: 'defi' });

Quick Address Lookup

// Search for an address by name
const results = await findAll({
  search: 'exchange',
  limit: 5
});

// Use the first result for a transaction
const items = extractResponseData(results) ?? [];
if (items.length > 0) {
  const exchangeAddress = items[0];
  await sendSOL('wallet-id', {
    recipientAddress: exchangeAddress.address,
    amountLamports: 1000000000
  });
}

Bulk Address Management

// Add multiple addresses
const addresses = [
  { address: 'Addr1...', label: 'Wallet 1', tags: ['personal'] },
  { address: 'Addr2...', label: 'Wallet 2', tags: ['business'] },
  { address: 'Addr3...', label: 'Wallet 3', tags: ['personal'] }
];

for (const addr of addresses) {
  await create(addr);
}

// Get all personal wallets
const personalWallets = await findAll({ tag: 'personal' });

Best Practices