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.
Platform Overview: Bull vs. Bear allows users to execute leveraged long-short strategies in a single transaction using USDC as collateral, with 100% of USDC earning lending yield while trading.

Integration Tools

How Bull vs. Bear Works

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

Deposit USDC

Users deposit USDC as collateral, which earns lending yield while trading
2

Select Strategy

Choose from pre-made Clusters or create custom long-short combinations
3

Configure Position

Set position size, leverage, and asset weights within the Cluster
4

Execute Trade

Deploy the entire strategy in a single transaction
5

Monitor & Manage

Track performance and manage positions through the platform interface

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

Strategy: Bitcoin outperforms major altcoins
{
  "name": "BTC vs Blue Chips",
  "positions": {
    "BTC": { "direction": "long", "weight": 50 },
    "ETH": { "direction": "short", "weight": 25 },
    "SOL": { "direction": "short", "weight": 25 }
  }
}

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

Lending Yield

USDC collateral earns lending yield while positions are active, maximizing capital efficiency.

Borrowing for Leverage

Automated borrowing enables leveraged positions without manual debt management.

Liquidation Protection

Mars Protocol’s liquidation engine ensures borrowed funds are protected.

Multi-Asset Support

Support for multiple assets enables diverse cluster compositions.

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

Important: Liquidation occurs when a position’s value drops too far relative to borrowed amount. The platform automatically closes positions to protect borrowed funds.

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

1

Install Dependencies

npm install @deploydon/bullbear-lib
# or
git clone https://github.com/Deploydon/BullBearLib.git
2

Configure Connection

Set up your Neutron RPC connection and wallet integration
3

Explore Strategies

Study existing clusters and market conditions to identify opportunities
4

Start Small

Begin with small position sizes to understand the platform mechanics
5

Build & Iterate

Develop your integration and gradually increase complexity
Community Support: Join the Neutron Builders Chat for questions, strategy discussions, and integration support.