TypeScript Reference

npm install @rebelfi/sdk

import { RebelfiClient } from '@rebelfi/sdk';

const client = new RebelfiClient(config: RebelfiClientConfig);

interface RebelfiClientConfig {
  /** Your RebelFi API key (required) */
  apiKey: string;

  /** API base URL (default: https://midas.rebelfi.io) */
  baseUrl?: string;

  /** Request timeout in milliseconds (default: 60000) */
  timeout?: number;
}

async list(query?: VenueQuery): Promise<VenueListResponse>

interface VenueQuery {
  /** Filter by blockchain */
  blockchain?: 'solana' | 'polygon' | 'ethereum';
  /** Filter by token symbol (e.g., 'USDC') */
  token?: string;
}

interface VenueListResponse {
  venues: Venue[];
  /** Total number of venues */
  count: number;
  /** Total number of strategies across all venues */
  strategyCount: number;
}

async get(id: number): Promise<Venue>

interface Venue {
  /** Venue identifier */
  id: number;
  /** Display name (e.g., 'Kamino') */
  name: string;
  /** Protocol identifier (e.g., 'kamino') */
  protocol: string;
  /** Blockchain network */
  blockchain: 'solana' | 'polygon' | 'ethereum';
  /** Venue icon URL */
  iconUrl?: string;
  /** Venue status */
  status: 'active' | 'paused' | 'deprecated';
  /** Available strategies */
  strategies: Strategy[];
}

interface Strategy {
  /** Strategy identifier - use for supply/unwind */
  strategyId: number;
  /** Strategy display name */
  name: string;
  /** Token symbol (e.g., 'USDC') */
  token: string;
  /** Token contract address */
  tokenAddress: string;
  /** Current APY as decimal (0.085 = 8.5%) */
  apy: number;
  /** Total value locked */
  tvl?: string;
  /** Minimum deposit in base units */
  minDeposit?: string;
  /** Maximum deposit in base units */
  maxDeposit?: string;
  /** Strategy status */
  status: 'active' | 'paused';
}

async list(query: AllocationQuery): Promise<AllocationListResponse>

interface AllocationQuery {
  /** User wallet address (required) */
  walletAddress: string;
  /** Filter by blockchain */
  blockchain?: 'solana' | 'polygon' | 'ethereum';
}

interface AllocationListResponse {
  allocations: Allocation[];
  /** Sum of all allocation values */
  totalValue: string;
  /** Sum of all yield earned */
  totalYieldEarned: string;
}

async get(venueId: number, walletAddress: string): Promise<Allocation>

async earnings(query: EarningsQuery): Promise<EarningsResponse>

interface EarningsQuery {
  /** User wallet address */
  walletAddress: string;
  /** Blockchain network */
  blockchain: 'solana' | 'polygon' | 'ethereum';
  /** Token symbol */
  token: string;
  /** Number of days of history (default: 30) */
  days?: number;
  /** Include per-venue breakdown */
  includeBreakdown?: boolean;
}

interface EarningsResponse {
  walletAddress: string;
  blockchain: string;
  token: string;
  /** Period start date (YYYY-MM-DD) */
  periodStart: string;
  /** Period end date (YYYY-MM-DD) */
  periodEnd: string;
  /** First date with activity (null if never active) */
  firstActivityDate: string | null;
  /** Total yield in period (base units) */
  totalYieldEarned: string;
  /** Total yield in USD */
  totalYieldEarnedUsd: string;
  /** Daily history (sparse - only dates with data) */
  history: EarningsDay[];
  /** Per-venue breakdown (if includeBreakdown=true) */
  byVenue?: VenueEarnings[];
}

interface EarningsDay {
  /** Date (YYYY-MM-DD) */
  date: string;
  /** Yield earned (base units, can be negative) */
  yieldEarned: string;
  /** Yield earned in USD */
  yieldEarnedUsd: string;
  /** Cumulative yield from first activity */
  cumulativeYield: string;
  /** Closing position value */
  positionValue: string;
}

interface VenueEarnings {
  venueId: number;
  venueName: string;
  totalYieldEarned: string;
  totalYieldEarnedUsd: string;
  history: VenueEarningsDay[];
}

interface Allocation {
  /** Strategy identifier - use for unwind */
  strategyId: number;
  /** Strategy display name */
  strategyName: string;
  /** Venue identifier */
  venueId: number;
  /** Venue display name */
  venueName: string;
  /** User wallet address */
  walletAddress: string;
  /** Blockchain network */
  blockchain: 'solana' | 'polygon' | 'ethereum';
  /** Token symbol */
  token: string;
  /** Token contract address */
  tokenAddress: string;
  /** Principal deposited (base units) */
  principal: string;
  /** Current value including yield (base units) */
  currentValue: string;
  /** Total yield earned (base units) */
  yieldEarned: string;
  /** Current APY as decimal */
  apy: number;
  /** Last update (ISO 8601) */
  lastUpdated: string;
}

async supply(request: SupplyRequest): Promise<OperationResponse>

interface SupplyRequest {
  /** User wallet address */
  walletAddress: string;
  /** Target strategy ID */
  strategyId: number;
  /** Amount in base units (e.g., '1000000' for 1 USDC) */
  amount: string;
  /** Token contract address */
  tokenAddress: string;
}

async unwind(request: UnwindRequest): Promise<OperationResponse>

interface UnwindRequest {
  /** User wallet address */
  walletAddress: string;
  /** Strategy ID to unwind from */
  strategyId: number;
  /** Amount to unwind in base units */
  amount: string;
}

async get(id: number): Promise<OperationResponse>

interface OperationResponse {
  /** Operation identifier */
  operationId: number;
  /** Operation type */
  type: 'supply' | 'unwind';
  /** Current status */
  status: 'pending' | 'awaiting_signature' | 'submitted' | 'confirmed' | 'failed';
  /** Transactions in this operation */
  transactions: Transaction[];
  /** When unsigned transactions expire (ISO 8601) */
  expiresAt: string;
}

interface Transaction {
  id: number;
  blockchain: 'solana' | 'polygon' | 'ethereum';
  status: 'unsigned' | 'pending' | 'confirmed' | 'failed';
  /** Base64-encoded unsigned transaction (when unsigned) */
  unsignedTransaction?: string;
  /** Human-readable description */
  description?: string;
  /** On-chain hash (after submission) */
  txHash?: string;
  /** Block confirmations */
  confirmations?: number;
  /** Block number */
  blockNumber?: number;
  /** Error message if failed */
  error?: string;
  /** Machine-readable failure code */
  failureCode?: TransactionFailureCode;
  /** Contract revert reason */
  revertReason?: string;
}

async submitHash(request: SubmitHashRequest): Promise<TransactionStatusResponse>

interface SubmitHashRequest {
  /** Operation ID from supply/unwind */
  operationId: number;
  /** On-chain transaction hash */
  txHash: string;
}

async submitSigned(request: SubmitSignedRequest): Promise<TransactionStatusResponse>

interface SubmitSignedRequest {
  /** Operation ID from supply/unwind */
  operationId: number;
  /** Signed transaction (base64 for Solana) */
  signedTransaction: string;
  /** Optional - computed from signedTransaction if not provided */
  txHash?: string;
}

async get(id: number): Promise<TransactionStatusResponse>

interface TransactionStatusResponse {
  id: number;
  operationId: number;
  status: 'unsigned' | 'pending' | 'confirmed' | 'failed';
  txHash?: string;
  confirmations?: number;
  blockNumber?: number;
  error?: string;
}

class RebelfiError extends Error {
  constructor(
    message: string,
    statusCode: number,
    code?: ErrorCode | string,
    details?: Record<string, unknown>
  );

  /** HTTP status code */
  readonly statusCode: number;

  /** Machine-readable error code */
  readonly code?: ErrorCode | string;

  /** Additional error context */
  readonly details?: Record<string, unknown>;

  /** Check if error matches a specific code */
  is(code: ErrorCode): boolean;
}

enum ErrorCode {
  // Validation
  INVALID_AMOUNT = 'INVALID_AMOUNT',
  INVALID_ADDRESS = 'INVALID_ADDRESS',
  INVALID_TOKEN = 'INVALID_TOKEN',

  // Business logic
  INSUFFICIENT_BALANCE = 'INSUFFICIENT_BALANCE',
  STRATEGY_NOT_ACTIVE = 'STRATEGY_NOT_ACTIVE',
  ALLOCATION_NOT_FOUND = 'ALLOCATION_NOT_FOUND',
  OPERATION_EXPIRED = 'OPERATION_EXPIRED',
  OPERATION_ALREADY_SUBMITTED = 'OPERATION_ALREADY_SUBMITTED',
  TOKEN_MISMATCH = 'TOKEN_MISMATCH',

  // Resources
  VENUE_NOT_FOUND = 'VENUE_NOT_FOUND',
  STRATEGY_NOT_FOUND = 'STRATEGY_NOT_FOUND',
  OPERATION_NOT_FOUND = 'OPERATION_NOT_FOUND',
  TRANSACTION_NOT_FOUND = 'TRANSACTION_NOT_FOUND',
  WALLET_NOT_FOUND = 'WALLET_NOT_FOUND',
  ORGANIZATION_NOT_FOUND = 'ORGANIZATION_NOT_FOUND',
  TOKEN_NOT_FOUND = 'TOKEN_NOT_FOUND',

  // Simulation
  INSUFFICIENT_GAS = 'INSUFFICIENT_GAS',
  SIMULATION_FAILED = 'SIMULATION_FAILED',

  // Client
  INVALID_API_KEY = 'INVALID_API_KEY',
  API_KEY_DISABLED = 'API_KEY_DISABLED',
  RATE_LIMIT_EXCEEDED = 'RATE_LIMIT_EXCEEDED',
  TIMEOUT = 'TIMEOUT',
  NETWORK_ERROR = 'NETWORK_ERROR',
  UNKNOWN_ERROR = 'UNKNOWN_ERROR',
}

enum TransactionFailureCode {
  /** Smart contract reverted */
  REVERTED = 'REVERTED',
  /** Ran out of gas */
  OUT_OF_GAS = 'OUT_OF_GAS',
  /** Not confirmed in time */
  TIMEOUT = 'TIMEOUT',
  /** Nonce already used */
  NONCE_TOO_LOW = 'NONCE_TOO_LOW',
  /** Not enough native token for gas */
  INSUFFICIENT_FUNDS = 'INSUFFICIENT_FUNDS',
  /** Replaced by another transaction */
  REPLACED = 'REPLACED',
  /** Dropped from mempool */
  DROPPED = 'DROPPED',
  /** Unknown failure */
  UNKNOWN = 'UNKNOWN',
}

type Blockchain = 'solana' | 'polygon' | 'ethereum';

type VenueStatus = 'active' | 'paused' | 'deprecated';

type StrategyStatus = 'active' | 'paused';

type TransactionStatus = 'unsigned' | 'pending' | 'confirmed' | 'failed';

type OperationType = 'supply' | 'unwind';

type OperationStatus = 'pending' | 'awaiting_signature' | 'submitted' | 'confirmed' | 'failed';