Breeze SDK

A comprehensive TypeScript SDK for interacting with the Breeze API, providing a clean interface for user yield tracking, balance management, and transaction handling.

Installation

npm install @breezebaby/breeze-sdk

Quick Start

import { BreezeSDK } from '@breezebaby/breeze-sdk';

// Initialize the SDK
const sdk = new BreezeSDK({
  baseUrl: 'https://api.breeze.baby/', // Your API base URL
  apiKey: 'your-api-key-here',
  timeout: 30000 // Optional: request timeout in milliseconds (default: 30000)
});

// Get user yield data
const userYield = await sdk.getUserYield({
  userId: '2xaSyo2LFRWoUVKifgJ36ka6Frhgc5bGfTBUf69A3Gc7'
});
console.log('Total yield earned:', userYield.total_yield_earned);

API Reference

BreezeSDK Class

The main SDK class that provides a convenient interface to all API endpoints.

Constructor

new BreezeSDK(config: BreezeSDKConfig)

BreezeSDKConfig:

apiKey: string - Your API authentication key (required)
baseUrl?: string - Base URL for the API (default: ‘https://api.breeze.baby/’)
timeout?: number - Request timeout in milliseconds (default: 30000)

Methods

User Operations

getUserYield(options) Get user yield data with pagination and fund filtering.

// Basic usage
const userYield = await sdk.getUserYield({
  userId: '2xaSyo2LFRWoUVKifgJ36ka6Frhgc5bGfTBUf69A3Gc7'
});

// With optional parameters
const userYield = await sdk.getUserYield({
  userId: '2xaSyo2LFRWoUVKifgJ36ka6Frhgc5bGfTBUf69A3Gc7',
  fundId: '8pfa41TvGWyttSViHRaNwFwbjhDEgmf3tHj81XR3CwWV', // Optional filter
  page: 1,      // Optional pagination
  limit: 10     // Optional pagination
});

// Returns:
// {
//   "yields": [
//     {
//       "fund_id": "fund_123",
//       "fund_name": "USDC Yield Fund",
//       "base_asset": "USDC",
//       "position_value": "500.00",
//       "yield_earned": "25.50",
//       "apy": "5.10",
//       "entry_date": "2024-01-15T10:30:00Z",
//       "last_updated": "2024-01-20T14:45:00Z"
//     }
//   ],
//   "pagination": {
//     "page": 1,
//     "limit": 10,
//     "total_items": 1,
//     "total_pages": 1
//   },
//   "total_yield_earned": "25.50"
// }

getUserBalances(options) Get user balance information with asset filtering and sorting.

// Basic usage
const userBalances = await sdk.getUserBalances({
  userId: '2xaSyo2LFRWoUVKifgJ36ka6Frhgc5bGfTBUf69A3Gc7'
});

// With optional parameters
const userBalances = await sdk.getUserBalances({
  userId: '2xaSyo2LFRWoUVKifgJ36ka6Frhgc5bGfTBUf69A3Gc7',
  asset: 'USDC',        // Optional filter
  sortBy: 'balance',    // Optional sorting
  sortOrder: 'desc'     // Optional sort order
});

// Returns:
// {
//   "balances": [
//     {
//       "asset": "USDC",
//       "symbol": "USDC",
//       "wallet_balance": "1000.00",
//       "fund_positions": [
//         {
//           "fund_id": "fund_123",
//           "fund_name": "USDC Yield Fund",
//           "position_value": "500.00",
//           "yield_earned": "25.50",
//           "apy": "5.10"
//         }
//       ],
//       "total_balance": "1525.50",
//       "total_yield": "25.50"
//     }
//   ],
//   "total_portfolio_value": "1525.50",
//   "total_yield_earned": "25.50"
// }

Transaction Operations

createDepositTransaction(options) Create a deposit transaction. Required parameters: fundId, amount, userKey.

const depositTx = await sdk.createDepositTransaction({
  fundId: 'DYUgGU88Fsyr2xmYAv2p8jXVPa3jrcUZmb36C8EgfpaW', // Required
  amount: 100, // Required
  userKey: '4Z9byLWE4DhH3KM84mjrkggkCxPuU8eBFgM44Enj41bh', // Required
  payerKey: '4Z9byLWE4DhH3KM84mjrkggkCxPuU8eBFgM44Enj41bh', // Optional
  all: false // Optional: whether to deposit all available funds
});
// Returns base64 encoded transaction ready for signing

createWithdrawTransaction(options) Create a withdraw transaction. Required parameters: fundId, amount, userKey.

const withdrawTx = await sdk.createWithdrawTransaction({
  fundId: '8pfa41TvGWyttSViHRaNwFwbjhDEgmf3tHj81XR3CwWV', // Required
  amount: 50, // Required
  userKey: '2xaSyo2LFRWoUVKifgJ36ka6Frhgc5bGfTBUf69A3Gc7', // Required
  payerKey: '2xaSyo2LFRWoUVKifgJ36ka6Frhgc5bGfTBUf69A3Gc7', // Optional
  all: false // Optional: whether to withdraw all amount
});
// Returns: { success: true, result: "base64-encoded-transaction" }

getDepositInstructions(options) Get Solana transaction instructions for deposits. Required parameters: fundId, amount, userKey.

const depositIx = await sdk.getDepositInstructions({
  fundId: '8pfa41TvGWyttSViHRaNwFwbjhDEgmf3tHj81XR3CwWV', // Required
  amount: 100, // Required
  userKey: '2xaSyo2LFRWoUVKifgJ36ka6Frhgc5bGfTBUf69A3Gc7', // Required
  payerKey: '2xaSyo2LFRWoUVKifgJ36ka6Frhgc5bGfTBUf69A3Gc7', // Optional
  all: false // Optional
});
// Returns: { deposit_instruction: [instruction_objects] }

getWithdrawInstruction(options) Get Solana transaction instruction for withdrawals. Required parameters: fundId, amount, userKey.

const withdrawIx = await sdk.getWithdrawInstruction({
  fundId: '8pfa41TvGWyttSViHRaNwFwbjhDEgmf3tHj81XR3CwWV', // Required
  amount: 50, // Required
  userKey: '2xaSyo2LFRWoUVKifgJ36ka6Frhgc5bGfTBUf69A3Gc7', // Required
  payerKey: '2xaSyo2LFRWoUVKifgJ36ka6Frhgc5bGfTBUf69A3Gc7', // Optional
  all: false // Optional
});
// Returns: { lut_address: "...", withdraw_instruction: instruction_object }

Utility Methods

updateApiKey(newApiKey: string) Update the API key used for authentication.

sdk.updateApiKey('new-api-key');

getApiClient() Get the underlying ApiClient instance for advanced usage.

const apiClient = sdk.getApiClient();

Complete Example

import { BreezeSDK } from '@breezebaby/breeze-sdk';

async function example() {
  const sdk = new BreezeSDK({
    baseUrl: 'https://api.breeze.baby/',
    apiKey: 'your-api-key-here'
  });

  try {
    // 1. Get user yield data
    const userYield = await sdk.getUserYield({
      userId: '2xaSyo2LFRWoUVKifgJ36ka6Frhgc5bGfTBUf69A3Gc7',
      page: 1,
      limit: 10
    });
    console.log('Total yield earned:', userYield.total_yield_earned);
    console.log('Yield records:', userYield.yields.length);

    // 2. Get user balances
    const userBalances = await sdk.getUserBalances({
      userId: '2xaSyo2LFRWoUVKifgJ36ka6Frhgc5bGfTBUf69A3Gc7',
      asset: 'USDC',
      sortBy: 'balance',
      sortOrder: 'desc'
    });
    console.log('Total portfolio value:', userBalances.total_portfolio_value);
    console.log('Balance records:', userBalances.balances.length);

    // 3. Create deposit transaction
    const deposit = await sdk.createDepositTransaction({
      fundId: '8pfa41TvGWyttSViHRaNwFwbjhDEgmf3tHj81XR3CwWV',
      amount: 100,
      userKey: '2xaSyo2LFRWoUVKifgJ36ka6Frhgc5bGfTBUf69A3Gc7'
    });
    console.log('Deposit transaction created:', deposit.success);

    // 4. Get deposit instructions (for manual transaction building)
    const instructions = await sdk.getDepositInstructions({
      fundId: '8pfa41TvGWyttSViHRaNwFwbjhDEgmf3tHj81XR3CwWV',
      amount: 100,
      userKey: '2xaSyo2LFRWoUVKifgJ36ka6Frhgc5bGfTBUf69A3Gc7'
    });
    console.log('Has instructions:', !!instructions.deposit_instruction);

  } catch (error) {
    console.error('Error:', error.message);
  }
}

Transaction Signing and Execution

For executing transactions on Solana, you’ll need to sign and send them:

import { Connection, Keypair, VersionedTransaction } from '@solana/web3.js';
import bs58 from 'bs58';

// Create connection and keypair
const connection = new Connection('https://api.mainnet-beta.solana.com');
const userKeypair = Keypair.fromSecretKey(bs58.decode('your-private-key'));

// Create transaction
const depositTx = await sdk.createDepositTransaction({
  fundId: 'DYUgGU88Fsyr2xmYAv2p8jXVPa3jrcUZmb36C8EgfpaW',
  amount: 100,
  userKey: userKeypair.publicKey.toString()
});

// Sign and send transaction
const txBuffer = Buffer.from(depositTx.result, 'base64');
const transaction = VersionedTransaction.deserialize(txBuffer);
transaction.sign([userKeypair]);

const signature = await connection.sendTransaction(transaction);
console.log('Transaction signature:', signature);

Low-Level API

For advanced use cases, you can use the individual functions and ApiClient directly:

import { 
  ApiClient, 
  getUserYield,
  getUserBalances,
  getInstructionsForDeposit,
  getTransactionForDeposit
} from '@breezebaby/breeze-sdk';

const apiClient = new ApiClient('https://api.breeze.baby/');
const userYield = await getUserYield(apiClient, 'api_key', 'user_id');
const userBalances = await getUserBalances(apiClient, 'api_key', 'user_id');

Required API Endpoint

The SDK requires access to the Breeze API at: Base URL: https://api.breeze.baby/ Make sure your API key has access to the following endpoints:

GET /user-yield/{user_id} - User yield data retrieval
GET /user-balances/{user_id} - User balance information
POST /deposit/tx - Deposit transaction creation
POST /withdraw/tx - Withdraw transaction creation
POST /deposit/ix - Deposit instruction generation
POST /withdraw/ix - Withdraw instruction generation

Error Types

BreezeApiError: Thrown for API-related errors
- message: string - Error message
- status?: number - HTTP status code
- code?: string - Error code (‘TIMEOUT’, ‘NETWORK_ERROR’, etc.)
- response?: any - Full error response from the API

TypeScript Support

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

import { 
  UserYield,
  UserBalances, 
  TransactionForDeposit,
  InstructionsForDeposit
} from '@breezebaby/breeze-sdk';

// All API responses are properly typed
const userYield: UserYield = await sdk.getUserYield({
  userId: 'user_123'
});

const userBalances: UserBalances = await sdk.getUserBalances({
  userId: 'user_123'
});

const instructions: InstructionsForDeposit = await sdk.getDepositInstructions({
  fundId: 'fund_123',
  amount: 100,
  userKey: 'user_key'
});

Testing

Integration Tests

Run integration tests against real API server:

npm run test:integration

Example Scripts

Test the SDK with example scripts: Check the examples out, in the packages/sdk/examples

API Endpoints

The SDK interacts with these API endpoints:

GET Endpoints

GET /user-yield/{user_id} - Get user yield data (supports pagination and fund filtering)
GET /user-balances/{user_id} - Get user balance information (supports asset filtering and sorting)

POST Endpoints

POST /deposit/tx - Create deposit transaction (requires fundId, amount, userKey)
POST /withdraw/tx - Create withdraw transaction (requires fundId, amount, userKey)
POST /deposit/ix - Get deposit instructions (requires fundId, amount, userKey)
POST /withdraw/ix - Get withdraw instruction (requires fundId, amount, userKey)

Development

Building

npm run build

Example Usage

The SDK includes comprehensive examples in the examples/ directory:

basic-usage.ts - Simple SDK initialization and basic method calls
integration-flow.ts - Complete transaction flow with Solana execution
integration-flow-simple.ts - API demonstration without transaction execution

Project Structure

src/
├── breeze-sdk.ts              # Main SDK class
├── builder.ts                 # ApiClient and error handling
├── index.ts                   # Main exports
├── getUserYield/              # User yield operations
├── getUserBalances/           # User balance operations
├── transactionForDeposit/     # Deposit transactions
├── transactionForWithdraw/    # Withdraw transactions
├── instructionsForDeposit/    # Deposit instructions
└── instructionsForWithdraw/   # Withdraw instructions

Introduction

Quickstart

Breeze SDK

Installation

Quick Start

API Reference

BreezeSDK Class

Constructor

Methods

User Operations

Transaction Operations

Utility Methods

Complete Example

Transaction Signing and Execution

Low-Level API

Required API Endpoint

Error Types

TypeScript Support

Testing

Integration Tests

Example Scripts

API Endpoints

GET Endpoints

POST Endpoints

Development

Building

Example Usage

Project Structure

Introduction

​Breeze SDK

​Installation

​Quick Start

​API Reference

​BreezeSDK Class

​Constructor

​Methods

User Operations

Transaction Operations

Utility Methods

​Complete Example

​Transaction Signing and Execution

​Low-Level API

​Required API Endpoint

​Error Types

​TypeScript Support

​Testing

​Integration Tests

​Example Scripts

​API Endpoints

​GET Endpoints

​POST Endpoints

​Development

​Building

​Example Usage

​Project Structure

Breeze SDK

Installation

Quick Start

API Reference

BreezeSDK Class

Constructor

Methods

Complete Example

Transaction Signing and Execution

Low-Level API

Required API Endpoint

Error Types

TypeScript Support

Testing

Integration Tests

Example Scripts

API Endpoints

GET Endpoints

POST Endpoints

Development

Building

Example Usage

Project Structure