Bull vs. Bear Integration

Bull vs. Bear is Neutron's innovative narrative trading platform that enables long-short strategies through Clusters. This guide provides developers with the tools and knowledge needed to integrate with the platform or build similar functionality.

Integration Tools

How Bull vs. Bear Works

Bull vs. Bear enables sophisticated trading strategies through its Cluster system:

Understanding Clusters

Clusters are the core innovation of Bull vs. Bear, allowing narrative-based trading:

What are Clusters?

Clusters package multiple long and short positions into a single tradable unit, enabling traders to express views on broader market narratives rather than individual assets.

Example Cluster Strategies

Key Features for Developers

Leveraged Trading

• Uses Mars Protocol for borrowing and lending
• Single-transaction execution of complex strategies
• Automatic liquidation protection

Position Management

• Independent position isolation (no cross-collateralization)
• Real-time P&L tracking
• Flexible position sizing with minimum $10 trades

Risk Management

• Liquidation price calculation and monitoring
• Funding rate tracking and optimization
• Position-specific risk containment

Integration Examples

Basic Position Query

// Example using BullBearLib
import { BullBearClient } from '@deploydon/bullbear-lib';

const client = new BullBearClient({
  rpcEndpoint: 'https://rpc-neutron.keplr.app',
  restEndpoint: 'https://rest-neutron.keplr.app'
});

// Get user positions
const positions = await client.getUserPositions(userAddress);
console.log('Active positions:', positions);

// Get cluster information
const cluster = await client.getClusterDetails(clusterId);
console.log('Cluster composition:', cluster);

Creating Custom Clusters

// Define a custom cluster
const customCluster = {
  name: "My Custom Strategy",
  description: "Custom long-short narrative play",
  positions: [
    {
      asset: "BTC",
      direction: "long",
      weight: 40,
      leverage: 3
    },
    {
      asset: "ETH", 
      direction: "short",
      weight: 60,
      leverage: 2
    }
  ]
};

// Execute cluster trade
const result = await client.executeClusterTrade({
  cluster: customCluster,
  collateralAmount: "1000", // USDC
  userAddress: userAddress
});

Position Monitoring

// Monitor position performance
const monitorPosition = async (positionId) => {
  const position = await client.getPosition(positionId);
  
  console.log({
    pnl: position.unrealizedPnl,
    liquidationPrice: position.liquidationPrice,
    fundingRate: position.currentFundingRate,
    timeToLiquidation: position.estimatedLiquidationTime
  });
  
  // Check if position needs attention
  if (position.healthFactor < 1.2) {
    console.warn('Position approaching liquidation!');
  }
};

Mars Protocol Integration

Bull vs. Bear leverages Mars Protocol for its lending and borrowing infrastructure:

Key Mars Features Used

Integration with Mars

// Example Mars Protocol interaction
import { MarsClient } from '@mars-protocol/mars.js';

const marsClient = new MarsClient(neutronRpc);

// Check lending rates
const lendingRates = await marsClient.getLendingRates();
console.log('USDC lending APY:', lendingRates.USDC);

// Monitor health factors
const healthFactor = await marsClient.getHealthFactor(userAddress);
if (healthFactor < 1.0) {
  console.warn('Position at risk of liquidation');
}

Risk Management

Liquidation Mechanics

Key Risk Factors

1. Leverage Risk: Higher leverage amplifies both gains and losses
2. Funding Costs: Negative funding rates can erode profits over time
3. Liquidation Risk: Positions can be liquidated if health factor drops too low
4. Market Risk: Narrative trades can be subject to sudden sentiment shifts

Risk Monitoring Tools

// Comprehensive risk monitoring
const riskMetrics = await client.getRiskMetrics(positionId);

console.log({
  healthFactor: riskMetrics.healthFactor,
  liquidationPrice: riskMetrics.liquidationPrice,
  timeToLiquidation: riskMetrics.estimatedTimeToLiquidation,
  fundingCost: riskMetrics.dailyFundingCost,
  unrealizedPnl: riskMetrics.unrealizedPnl
});

Building Trading Bots

The BullBearLib is designed to support automated trading strategies:

Bot Architecture

class TradingBot {
  constructor(config) {
    this.client = new BullBearClient(config);
    this.strategies = config.strategies;
  }
  
  async runStrategy(strategyName) {
    const strategy = this.strategies[strategyName];
    
    // Analyze market conditions
    const marketData = await this.client.getMarketData();
    
    // Check if strategy conditions are met
    if (strategy.shouldExecute(marketData)) {
      // Execute cluster trade
      await this.client.executeClusterTrade(strategy.cluster);
    }
    
    // Monitor existing positions
    await this.monitorPositions();
  }
  
  async monitorPositions() {
    const positions = await this.client.getUserPositions();
    
    for (const position of positions) {
      if (position.healthFactor < 1.2) {
        // Close position to avoid liquidation
        await this.client.closePosition(position.id);
      }
    }
  }
}

Development Resources

Common Use Cases

Portfolio Hedging

Use clusters to hedge existing crypto positions by creating inverse exposure to market segments.

Narrative Trading

Express views on emerging market themes like "AI tokens vs traditional crypto" or "L1 vs L2 performance."

Yield Enhancement

Combine position trading with USDC lending yield for enhanced returns on capital.

Arbitrage Opportunities

Capitalize on funding rate differentials across different assets and time periods.

Getting Started