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.
How Bull vs. Bear Works
Bull vs. Bear enables sophisticated trading strategies through its Cluster system:
Deposit USDC
Users deposit USDC as collateral, which earns lending yield while trading
Select Strategy
Choose from pre-made Clusters or create custom long-short combinations
Configure Position
Set position size, leverage, and asset weights within the Cluster
Execute Trade
Deploy the entire strategy in a single transaction
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
BTC Dominance
Ethereum L2s
Funding Arbitrage
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
Leverage Risk : Higher leverage amplifies both gains and losses
Funding Costs : Negative funding rates can erode profits over time
Liquidation Risk : Positions can be liquidated if health factor drops too low
Market Risk : Narrative trades can be subject to sudden sentiment shifts
// 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
Install Dependencies
npm install @deploydon/bullbear-lib
# or
git clone https://github.com/Deploydon/BullBearLib.git
Configure Connection
Set up your Neutron RPC connection and wallet integration
Explore Strategies
Study existing clusters and market conditions to identify opportunities
Start Small
Begin with small position sizes to understand the platform mechanics
Build & Iterate
Develop your integration and gradually increase complexity
Community Support: Join the Neutron Builders Chat for questions, strategy discussions, and integration support.