CapSign TypeScript SDK

Official TypeScript SDK for the CapSign API - programmatic access to tokenized securities, digital equity management, and compliant investment workflows.

Installation

npm install @capsign/sdk

Quick Start

import { CapSign } from '@capsign/sdk';

const capsign = new CapSign({
  apiKey: process.env.CAPSIGN_API_KEY!,
  environment: 'sandbox', // or 'production'
});

// Create a wallet
const wallet = await capsign.wallets.create({
  ownerAddress: '0x123...',
  threshold: 1,
});

// Issue tokens
const token = await capsign.tokens.create({
  walletAddress: wallet.address,
  name: 'Example Corp Class A',
  symbol: 'EXMP-A',
  totalSupply: '1000000',
  securityType: 'COMMON_STOCK',
});

// Launch an offering
const offering = await capsign.offerings.create({
  tokenAddress: token.address,
  offeringType: 'REG_D',
  totalAmount: '5000000',
  pricePerToken: '10',
});

console.log(`Offering created: ${offering.id}`);

Features

• ✅ Type-Safe - Full TypeScript types for all API operations
• ✅ Auto-Pagination - Automatic handling of paginated responses
• ✅ Retry Logic - Built-in exponential backoff for failed requests
• ✅ Webhooks - Helper methods for webhook signature verification
• ✅ Error Handling - Structured error types for better debugging
• ✅ Modern Fetch - Uses native fetch API (Node.js 18+ / browser)

Authentication

Get your API key from the CapSign Dashboard.

const capsign = new CapSign({
  apiKey: 'csk_test_...',  // Sandbox key
  // or
  apiKey: 'csk_live_...',  // Production key
});

Environments

Environment	Base URL	Network
Sandbox	https://demo.capsign.com/api/v1	Base Sepolia (testnet)
Production	https://capsign.com/api/v1	Base Mainnet

Resources

Wallets

// Create wallet
const wallet = await capsign.wallets.create({
  ownerAddress: '0x123...',
  threshold: 1,
});

// Get wallet
const wallet = await capsign.wallets.get('0xabc...');

// List wallets with auto-pagination
for await (const wallet of capsign.wallets.list()) {
  console.log(wallet.address);
}

Tokens

// Create token
const token = await capsign.tokens.create({
  walletAddress: '0xabc...',
  name: 'Example Corp',
  symbol: 'EXMP',
  totalSupply: '1000000',
  securityType: 'COMMON_STOCK',
});

// List tokens
const tokens = await capsign.tokens.list({ limit: 50 });

// Get token details
const token = await capsign.tokens.get('0xdef...');

Offerings

// Create offering
const offering = await capsign.offerings.create({
  tokenAddress: '0xdef...',
  offeringType: 'REG_D',
  totalAmount: '5000000',
  pricePerToken: '10',
  minimumInvestment: '1000',
});

// List offerings
for await (const offering of capsign.offerings.list()) {
  console.log(`${offering.token.symbol}: $${offering.totalRaised}`);
}

Documents

// Create document
const document = await capsign.documents.create({
  walletAddress: '0xabc...',
  title: 'Investment Agreement',
  content: 'Document content...',
  signers: [
    { email: 'investor@example.com', role: 'INVESTOR' },
    { email: 'founder@example.com', role: 'ISSUER' },
  ],
});

// Get document
const document = await capsign.documents.get(document.id);

Webhooks

// List webhooks
const webhooks = await capsign.webhooks.list();

// Create webhook
const webhook = await capsign.webhooks.create({
  url: 'https://your-app.com/webhooks/capsign',
  events: ['wallet.created', 'token.created', 'offering.investment'],
});

// Verify webhook signature (Express example)
app.post('/webhooks/capsign', (req, res) => {
  const signature = req.headers['x-capsign-signature'] as string;
  const payload = JSON.stringify(req.body);
  
  if (!capsign.webhooks.verifySignature(payload, signature, webhookSecret)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }
  
  // Process webhook
  const event = req.body;
  console.log(`Received: ${event.type}`);
  
  res.json({ received: true });
});

Error Handling

import { CapSignError } from '@capsign/sdk';

try {
  const wallet = await capsign.wallets.create({
    ownerAddress: '0x123...',
    threshold: 1,
  });
} catch (error) {
  if (error instanceof CapSignError) {
    console.error('API Error:', {
      message: error.message,
      code: error.code,
      status: error.status,
      details: error.details,
    });
  } else {
    console.error('Unexpected error:', error);
  }
}

Advanced Usage

Custom Configuration

const capsign = new CapSign({
  apiKey: process.env.CAPSIGN_API_KEY!,
  environment: 'production',
  
  // Custom base URL
  baseUrl: 'https://custom.capsign.com/api/v1',
  
  // Retry configuration
  maxRetries: 3,
  retryDelay: 1000,
  
  // Timeout (ms)
  timeout: 30000,
  
  // Custom headers
  headers: {
    'X-Custom-Header': 'value',
  },
});

Pagination Helpers

// Auto-pagination with async iterator
for await (const token of capsign.tokens.list()) {
  console.log(token.symbol);
}

// Manual pagination
let cursor: string | undefined;
do {
  const response = await capsign.tokens.list({ cursor, limit: 100 });
  
  for (const token of response.tokens) {
    console.log(token.symbol);
  }
  
  cursor = response.pagination.nextCursor;
} while (cursor);

// Collect all pages into array (use with caution)
const allTokens = await capsign.tokens.listAll();

TypeScript Support

The SDK is written in TypeScript and provides full type safety:

import type { 
  Wallet, 
  Token, 
  Offering, 
  Document 
} from '@capsign/sdk';

// All responses are fully typed
const wallet: Wallet = await capsign.wallets.create({...});
const token: Token = await capsign.tokens.get('0x...');

Documentation

• API Reference
• Guides & Tutorials
• OpenAPI Spec

Support

• Email: support@capsign.com
• Discord: discord.gg/capsign
• GitHub Issues: github.com/capsign/sdk-typescript

License

MIT © CapSign Inc.