Skip to main content

​
Introduction

Staxiq provides a comprehensive set of services and React hooks for building Bitcoin DeFi applications on the Stacks blockchain. The API is organized into services for blockchain interactions and React hooks for state management.

​
Architecture

The Staxiq API follows a modular architecture:

Services

Core blockchain and AI services for direct function calls

React Hooks

State management hooks for React components

Authentication

Wallet connection and user session management

Protocol Data

Static protocol information and configurations

​
Core Services

​
AI Service

Generate personalized DeFi strategies using Google’s Gemini AI, tailored to user portfolios and risk profiles. View AI Service Documentation →

​
Contract Service

Interact with Stacks smart contracts for on-chain profile management, strategy anchoring, and risk profile storage. View Contract Service Documentation →

​
Stacks API Service

Fetch real-time blockchain data including STX balances, token balances, transaction history, and market prices. View Stacks API Documentation →

​
DefiLlama Service

Fetch live protocol data including TVL and APY from DefiLlama API for all supported Stacks DeFi protocols. View DefiLlama Service Documentation →

​
Portfolio Protocols Service

Detect which DeFi protocols a wallet has positions in by analyzing token balances and transaction history. View Portfolio Protocols Documentation →

​
React Hooks

​
useWallet

Manage wallet connections with automatic network detection and session persistence. View useWallet Documentation →

​
useAIAdvisor

Access AI-powered strategy generation with loading states and error handling. View useAIAdvisor Documentation →

​
usePortfolio

Fetch and auto-refresh portfolio data including balances and transaction history. View usePortfolio Documentation →

​
useProtocols

Filter and sort protocol data with built-in loading states. View useProtocols Documentation →

​
useProtocolData

Fetch live protocol data from DefiLlama with automatic 5-minute refresh intervals. View useProtocolData Documentation →

​
useWalletProtocols

Detect and track which DeFi protocols a connected wallet has active positions in. View useWalletProtocols Documentation →

​
Quick Start

import { getSTXBalance } from './services/stacksApi';
import { getAIStrategy } from './services/aiService';
import { saveRiskProfile } from './services/contractService';

// Fetch balance
const balance = await getSTXBalance(address);

// Generate strategy
const strategy = await getAIStrategy({
  address,
  stxBalance: '100',
  totalUSD: '285',
  riskProfile: 'Balanced',
  protocols: PROTOCOLS
});

// Save to chain
const txid = await saveRiskProfile('Balanced');

​
Network Detection

All services automatically detect the appropriate network (testnet/mainnet) based on:
  • Wallet address prefix (ST for testnet, SP for mainnet)
  • Environment hostname (localhost uses testnet)
  • NetworkContext provider settings

​
Error Handling

Services return graceful fallbacks on errors:
  • Balance services return '0' on error
  • Transaction history returns empty array []
  • Price services return cached values or sensible defaults
Hooks provide explicit error states: 
const { portfolio, loading, error } = usePortfolio(address);
if (error) console.error(error);

​
Environment Variables

​
VITE_GEMINI_API_KEY
string
required
Google Gemini API key for AI strategy generation

​
Type Safety

While Staxiq is written in JavaScript, all functions include JSDoc comments for IDE type hints. TypeScript definitions can be added by creating .d.ts files in your project.

​
Next Steps

Authentication

Set up wallet authentication

AI Service

Generate AI strategies

useWallet Hook

Connect user wallets

Protocol Data

Access protocol information

Build docs developers (and LLMs) love

Get started for freeTalk to us