Breeze

Quickstart

Start with Breeze SDK within minutes

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 @solana/breeze-sdk

@solana/breeze-sdk is the maintained, Solana Foundation-scoped package. See the migration section in the package README when upgrading from @breezebaby/breeze-sdk v2.

Quick Start

import { BreezeSDK } from "@solana/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: "7EcSQsLNbkorQr3igFzfEwFJoPEUgB3NfmDTAigEcoSY",
});
for (const entry of userYield.data) {
  console.log(`${entry.fund_name}: earned ${entry.yield_earned} (APY ${entry.apy})`);
}

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.

// Basic usage
const userYield = await sdk.getUserYield({
  userId: "7EcSQsLNbkorQr3igFzfEwFJoPEUgB3NfmDTAigEcoSY",
});

// With optional parameters
const userYield = await sdk.getUserYield({
  userId: "7EcSQsLNbkorQr3igFzfEwFJoPEUgB3NfmDTAigEcoSY",
  page: 1, // Optional pagination
  limit: 10, // Optional pagination
});

// Returns:
// {
// 	"data": [
// 		{
// 			"fund_id": "8pfa41TvGWyttSViHRaNwFwbjhDEgmf3tHj81XR3Cysk",
// 			"fund_name": "Fund 8pfa41TvGWyttSViHRaNwFwbjhDEgmf3tHj81XR3Cysk",
// 			"base_asset": "USDC",
// 			"position_value": 1000005,
// 			"yield_earned": 5,
// 			"apy": 6.614188643106429,
// 			"entry_date": "2025-08-05T13:28:21+00:00",
// 			"last_updated": "2025-08-05T13:28:21+00:00"
// 		}
// 	],
// 	"meta": {
// 		"page": 1,
// 		"per_page": 10,
// 		"total": 1,
// 		"total_pages": 1,
// 		"has_more": false
// 	}
// }

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

// Basic usage
const userBalances = await sdk.getUserBalances({
  userId: "7EcSQsLNbkorQr3igFzfEwFJoPEUgB3NfmDTAigEcoSY",
});

// With optional parameters
const userBalances = await sdk.getUserBalances({
  userId: "7EcSQsLNbkorQr3igFzfEwFJoPEUgB3NfmDTAigEcoSY",
  asset: "USDC", // Optional filter
  sortBy: "balance", // Optional sorting
  sortOrder: "desc", // Optional sort order
  page: 1, // Optional pagination
  limit: 10, // Optional pagination
});

// Returns:
// {
// 	"data": [
// 		{
// 			"token_address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
// 			"token_symbol": "USDC",
// 			"token_name": "USD Coin",
// 			"decimals": 6,
// 			"total_balance": 10470880,
// 			"yield_balance": {
// 				"fund_id": "8pfa41TvGWyttSViHRaNwFwbjhDEgmf3tHj81XR3CwWV",
// 				"funds": "1000000",
// 				"amount_of_yield": "5",
// 				"fund_apy": 4.999999993617795
// 			}
// 		},
// 		{
// 			"token_address": "So11111111111111111111111111111111111111112",
// 			"token_symbol": "SOL",
// 			"token_name": "Wrapped SOL",
// 			"decimals": 9,
// 			"total_balance": 97959415,
// 			"yield_balance": null
// 		},
// 		{
// 			"token_address": "11111111111111111111111111111112",
// 			"token_symbol": "SOL",
// 			"token_name": "Solana",
// 			"decimals": 9,
// 			"total_balance": 3207138599,
// 			"yield_balance": null
// 		}
// 	],
// 	"meta": {
// 		"page": 1,
// 		"per_page": 10,
// 		"total": 3,
// 		"total_pages": 1,
// 		"has_more": false
// 	}
// }

getBreezeBalances(options) Get breeze-specific balance information with strategy details, including position values, yields, and APY data.

// Basic usage - strategyId is required
const breezeBalances = await sdk.getBreezeBalances({
  userId: "your-user-id",
  strategyId: "your-strategy-id",
});

// With optional parameters
const breezeBalances = await sdk.getBreezeBalances({
  userId: "your-user-id",
  strategyId: "your-strategy-id", // Required
  asset: "USDC", // Optional filter by asset symbol or mint address
  sortBy: "balance", // Optional sorting field
  sortOrder: "desc", // Optional sort order (asc/desc)
  page: 1, // Optional pagination
  limit: 10, // Optional pagination
});

// Returns:
// {
//   "data": [
//     {
//       "strategy_name": "try-breeze-all-assets",
//       "strategy_id": "your-strategy-id",
//       "fund_id": "6ZBKy52sqCN8UuCFkCbqTRUtYgMTvrqds1MqTXdrYRxt",
//       "token_address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
//       "token_symbol": "USDC",
//       "token_name": "USD Coin",
//       "decimals": 6,
//       "total_position_value": 2003215,
//       "total_deposited_value": 2003213,
//       "yield_earned": 2,
//       "apy": 4.999327213904799,
//       "last_updated": "2026-01-07T18:32:05+00:00"
//     }
//   ],
//   "meta": {
//     "page": 1,
//     "per_page": 1000,
//     "total": 2,
//     "total_pages": 1,
//     "has_more": false
//   }
// }
Strategy Operations

getStrategyInfo(strategyId) Get detailed information about a specific strategy, including supported assets and APY data per asset.

const strategyInfo = await sdk.getStrategyInfo("your-strategy-id");

// Returns:
// {
//   "strategy_id": "your-strategy-id",
//   "strategy_name": "try-breeze-all-assets",
//   "assets": [
//     "So11111111111111111111111111111111111111112",
//     "jupSoLaHXQiZZTSfEWMTRRgpnyFm8f6sZdosWBjx93v",
//     "USDSwr9ApdHk5bvJKMjzff41FfuX8bSxdKcR81vTwcA",
//     "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
//     ...
//   ],
//   "apy": 4.297586617097455,
//   "apy_per_asset": {
//     "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v": 5.660193556175348,
//     "USDSwr9ApdHk5bvJKMjzff41FfuX8bSxdKcR81vTwcA": 3.9268279189073074,
//     "So11111111111111111111111111111111111111112": 2.7887160175531163,
//     ...
//   }
// }
Transaction Operations

createDepositTransaction(options) Create a deposit transaction. Identify the position with either fundId, or strategyId + baseAsset (mint address).

const depositTx = await sdk.createDepositTransaction({
  strategyId: "your-strategy-id", // Required
  baseAsset: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", // Required - token mint address (e.g., USDC)
  amount: 100, // Required
  userKey: "4Z9byLWE4DhH3KM84mjrkggkCxPuU8eBFgM44Enj41bh", // Required
  payerKey: "4Z9byLWE4DhH3KM84mjrkggkCxPuU8eBFgM44Enj41bh", // Optional
  all: false, // Optional: whether to deposit all available funds
});
// Returns a base64 transaction string, or { message } for a handled API error

createWithdrawTransaction(options) Create a withdraw transaction. Identify the position with either fundId, or strategyId + baseAsset (mint address).

const withdrawTx = await sdk.createWithdrawTransaction({
  strategyId: "your-strategy-id", // Required
  baseAsset: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", // Required - token mint address (e.g., USDC)
  amount: 50, // Required
  userKey: "7EcSQsLNbkorQr3igFzfEwFJoPEUgB3NfmDTAigEcoSY", // Required
  payerKey: "7EcSQsLNbkorQr3igFzfEwFJoPEUgB3NfmDTAigEcoSY", // Optional
  all: false, // Optional: whether to withdraw all amount
});
// Returns a base64 transaction string, or { message } for a handled API error

getDepositInstructions(options) Get Solana transaction instructions for deposits. It accepts the same position and amount options as createDepositTransaction.

const depositIx = await sdk.getDepositInstructions({
  strategyId: "your-strategy-id", // Required
  baseAsset: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", // Required - token mint address (e.g., USDC)
  amount: 100, // Required
  userKey: "7EcSQsLNbkorQr3igFzfEwFJoPEUgB3NfmDTAigEcoSY", // Required
  payerKey: "7EcSQsLNbkorQr3igFzfEwFJoPEUgB3NfmDTAigEcoSY", // Optional
  all: false, // Optional
});
// Returns: { deposit_instructions: [instruction_objects], lookup_table?: "..." }

getWithdrawInstructions(options) Get Solana transaction instructions for withdrawals. It accepts the same position and amount options as createWithdrawTransaction.

const withdrawIx = await sdk.getWithdrawInstructions({
  strategyId: "your-strategy-id", // Required
  baseAsset: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", // Required - token mint address (e.g., USDC)
  amount: 50, // Required
  userKey: "7EcSQsLNbkorQr3igFzfEwFJoPEUgB3NfmDTAigEcoSY", // Required
  payerKey: "7EcSQsLNbkorQr3igFzfEwFJoPEUgB3NfmDTAigEcoSY", // Optional
  all: false, // Optional
});
// Returns: { withdraw_instructions: [instruction_objects], lookup_table?: "..." }
Close User Account Operations

createCloseUserAccountTransaction(options) Close a user account and return a serialized transaction. You can identify the account by userPubkey + strategyId + mint.

const closeTx = await sdk.createCloseUserAccountTransaction({
  userPubkey: "your-user-pubkey", // Required
  strategyId: "your-strategy-id", // Required with userPubkey
  mint: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", // Required with userPubkey
  payer: "payer-pubkey", // Optional
  fundsRecipient: "funds-recipient-pubkey", // Optional
  userTokenAccount: "token-account-address", // Optional
});
// Returns base64 encoded transaction string

getCloseUserAccountInstructions(options) Get Solana instructions for closing a user account. Same parameters as above.

const closeIx = await sdk.getCloseUserAccountInstructions({
  userPubkey: "your-user-pubkey",
  strategyId: "your-strategy-id",
  mint: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
});
// Returns: { close_user_fund_instructions: [instruction_objects] }
Health Check

getHealth() Check if the API server is healthy.

const health = await sdk.getHealth();
// Returns: "OK"
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 "@solana/breeze-sdk";

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

  try {
    // 1. Get strategy information
    const strategyInfo = await sdk.getStrategyInfo("your-strategy-id");
    console.log("Strategy:", strategyInfo.strategy_name);
    console.log("Overall APY:", strategyInfo.apy);
    console.log("Supported assets:", strategyInfo.assets.length);

    // 2. Get user yield data
    const userYield = await sdk.getUserYield({
      userId: "7EcSQsLNbkorQr3igFzfEwFJoPEUgB3NfmDTAigEcoSY",
      page: 1,
      limit: 10,
    });
    console.log("Yield records:", userYield.data.length);

    // 3. Get breeze balances with strategy details
    const breezeBalances = await sdk.getBreezeBalances({
      userId: "your-user-id",
      strategyId: "your-strategy-id",
      asset: "USDC",
    });
    console.log("Breeze balances:", breezeBalances.data.length);
    breezeBalances.data.forEach((balance) => {
      console.log(
        `${balance.token_symbol}: ${balance.total_position_value} (APY: ${balance.apy}%)`,
      );
    });

    // 4. Get user balances
    const userBalances = await sdk.getUserBalances({
      userId: "7EcSQsLNbkorQr3igFzfEwFJoPEUgB3NfmDTAigEcoSY",
      asset: "USDC",
      sortBy: "balance",
      sortOrder: "desc",
    });
    console.log("Balance records:", userBalances.data.length);

    // 5. Create deposit transaction using strategyId + baseAsset (mint)
    const deposit = await sdk.createDepositTransaction({
      strategyId: "your-strategy-id",
      baseAsset: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", // USDC mint address
      amount: 100,
      userKey: "7EcSQsLNbkorQr3igFzfEwFJoPEUgB3NfmDTAigEcoSY",
    });
    if (typeof deposit !== "string") {
      throw new Error(deposit.message);
    }
    console.log("Serialized deposit transaction received:", deposit.length > 0);

    // 6. Get deposit instructions (for manual transaction building)
    const instructions = await sdk.getDepositInstructions({
      strategyId: "your-strategy-id",
      baseAsset: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", // USDC mint address
      amount: 100,
      userKey: "7EcSQsLNbkorQr3igFzfEwFJoPEUgB3NfmDTAigEcoSY",
    });
    console.log("Has instructions:", !!instructions.deposit_instructions);
  } catch (error) {
    console.error("Error:", error instanceof Error ? error.message : error);
  }
}

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 using strategyId + baseAsset (mint address)
const depositTx = await sdk.createDepositTransaction({
  strategyId: "your-strategy-id",
  baseAsset: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", // USDC mint address
  amount: 100,
  userKey: userKeypair.publicKey.toString(),
});

// Sign and send transaction
if (typeof depositTx !== "string") {
  throw new Error(depositTx.message);
}

const txBuffer = Buffer.from(depositTx, "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,
  getBreezeBalances,
  getStrategyInfo,
} from "@solana/breeze-sdk";

const apiClient = new ApiClient({
  apiKey: "your-api-key",
  baseUrl: "https://api.breeze.baby/",
});

// Get strategy info
const strategyInfo = await getStrategyInfo(apiClient, "strategy_id");

// Get user data
const userYield = await getUserYield(apiClient, { userId: "user_id" });
const userBalances = await getUserBalances(apiClient, { userId: "user_id" });

// Get breeze balances with strategy details
const breezeBalances = await getBreezeBalances(apiClient, {
  userId: "user_id",
  strategyId: "strategy_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
  • GET /breeze-balances/{user_id} - Breeze-specific balance information with strategy details
  • GET /strategy-info/{strategy_id} - Strategy information and APY data
  • POST /deposit/tx - Deposit transaction creation
  • POST /withdraw/tx - Withdraw transaction creation
  • POST /deposit/ix - Deposit instruction generation
  • POST /withdraw/ix - Withdraw instruction generation
  • POST /close-user-account/tx - Close user account transaction creation
  • POST /close-user-account/ix - Close user account instruction generation
  • GET /health - Health check

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 type {
  UserYield,
  UserBalances,
  BreezeBalancesResponse,
  StrategyInfo,
  InstructionsForDeposit,
} from "@solana/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 breezeBalances: BreezeBalancesResponse = await sdk.getBreezeBalances({
  userId: "user_123",
  strategyId: "strategy_123",
});

const strategyInfo: StrategyInfo = await sdk.getStrategyInfo("strategy_123");

const instructions: InstructionsForDeposit = await sdk.getDepositInstructions({
  strategyId: "strategy_123",
  baseAsset: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", // mint address
  amount: 100,
  userKey: "user_key",
});

Testing

Integration Tests

Run integration tests against real API server:

npm run test:all

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)
  • GET /user-balances/{user_id} - Get user balance information (supports asset filtering and sorting)
  • GET /breeze-balances/{user_id} - Get breeze balances with strategy details (requires strategyId, supports asset filtering, sorting, and pagination)
  • GET /strategy-info/{strategy_id} - Get strategy information including assets and APY data

POST Endpoints

  • POST /deposit/tx - Create a deposit transaction (position by fund ID or strategy + asset)
  • POST /withdraw/tx - Create a withdraw transaction (position by fund ID or strategy + asset)
  • POST /deposit/ix - Get deposit instructions (position by fund ID or strategy + asset)
  • POST /withdraw/ix - Get withdraw instructions (position by fund ID or strategy + asset)
  • POST /close-user-account/tx - Close user account transaction (requires userPubkey+strategyId+mint)
  • POST /close-user-account/ix - Close user account instructions (requires userPubkey+strategyId+mint)
  • GET /health - Health check

Development

Building

npm run build

Example Usage

The SDK includes comprehensive examples in the examples/ directory:

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

Project Structure

src/
├── client.ts       # ApiClient and BreezeApiError
├── sdk.ts          # BreezeSDK class
├── types.ts        # Request and response types
├── index.ts        # Public exports
└── endpoints/      # One module per endpoint group

Overview

Short overview over Breeze SDK

Developer Tooling

Additional tools and resources for Breeze integration

On this page

Breeze SDKInstallationQuick StartAPI ReferenceBreezeSDK ClassConstructorMethodsUser OperationsStrategy OperationsTransaction OperationsClose User Account OperationsHealth CheckUtility MethodsComplete ExampleTransaction Signing and ExecutionLow-Level APIRequired API EndpointError TypesTypeScript SupportTestingIntegration TestsExample ScriptsAPI EndpointsGET EndpointsPOST EndpointsDevelopmentBuildingExample UsageProject Structure