API Reference

use perpcity_sdk::{PerpClient, Deployments};
use perpcity_sdk::transport::TransportConfig;

let transport = TransportConfig::new(vec!["https://base-rpc-url.com".into()])
    .build()?;

let deployments = Deployments {
    perp_manager: "0x...".parse()?,
    usdc: "0x...".parse()?,
    ..Default::default()
};

let mut client = PerpClient::new_base_mainnet(transport, signer, deployments)?;
client.sync_nonce().await?;
client.refresh_gas().await?;

use perpcity_sdk::{OpenTakerParams, Urgency};

let pos_id = client.open_taker(perp_id, OpenTakerParams {
    is_long: true,
    margin: 100.0,       // 100 USDC
    leverage: 10.0,      // 10x
    unspecified_amount_limit: 0,
}, Urgency::Normal).await?;

use perpcity_sdk::OpenMakerParams;

let pos_id = client.open_maker(perp_id, OpenMakerParams {
    margin: 10000.0,
    price_lower: 2900.0,
    price_upper: 3100.0,
    liquidity: 1_000_000,
    max_amt0_in: 1_000_000,
    max_amt1_in: 1_000_000,
}, Urgency::Normal).await?;

use perpcity_sdk::CloseParams;

let result = client.close_position(pos_id, CloseParams {
    min_amt0_out: 0,
    min_amt1_out: 0,
    max_amt1_in: 1_000_000,
}, Urgency::Normal).await?;

println!("tx: {:?}", result.tx_hash);
if let Some(remaining) = result.remaining_position_id {
    println!("Partial close, remaining: {remaining}");
}

client.adjust_notional(pos_id, 5000, 0, Urgency::Normal).await?;

client.adjust_margin(pos_id, 1000, Urgency::Normal).await?;

let config = client.get_perp_config(perp_id).await?;
println!("Mark: {:.2}", config.mark);
println!("Max leverage: {:.0}x", config.bounds.max_taker_leverage);
println!("Tick spacing: {}", config.tick_spacing);

let (beacon, tick_spacing, mark) = client.get_perp_data(perp_id).await?;

let mark = client.get_mark_price(perp_id).await?;

let rate = client.get_funding_rate(perp_id).await?;

let oi = client.get_open_interest(perp_id).await?;
println!("Long OI: {:.2}, Short OI: {:.2}", oi.long_oi, oi.short_oi);

let position = client.get_position(pos_id).await?;

let details = client.get_live_details(pos_id).await?;
println!("PnL: {:.2}", details.pnl);
println!("Funding: {:.2}", details.funding_payment);
println!("Effective margin: {:.2}", details.effective_margin);
println!("Liquidatable: {}", details.is_liquidatable);

let balance = client.get_usdc_balance().await?;

let quote = client.quote_open_taker(perp_id, OpenTakerParams {
    is_long: true,
    margin: 100.0,
    leverage: 10.0,
    unspecified_amount_limit: 0,
}).await?;
println!("Perp delta: {:.6}, USD delta: {:.2}", quote.perp_delta, quote.usd_delta);

let quote = client.quote_open_maker(perp_id, OpenMakerParams {
    margin: 10000.0,
    price_lower: 2900.0,
    price_upper: 3100.0,
    liquidity: 1_000_000,
    max_amt0_in: 1_000_000,
    max_amt1_in: 1_000_000,
}).await?;

let quote = client.quote_swap(
    perp_id,
    true,           // zero_for_one
    true,           // is_exact_in
    1_000_000,      // amount (6-decimal)
    None,           // sqrt_price_limit (optional)
).await?;

use perpcity_sdk::transport::{TransportConfig, Strategy};
use std::time::Duration;

let transport = TransportConfig::new(vec![
    "https://primary-rpc.com".into(),
    "https://fallback-rpc.com".into(),
])
.strategy(Strategy::Hedged { fan_out: 2 })
.request_timeout(Duration::from_secs(2))
.build()?;

use perpcity_sdk::transport::CircuitBreakerConfig;
use std::time::Duration;

let transport = TransportConfig::new(vec![
    "https://primary-rpc.com".into(),
    "https://fallback-rpc.com".into(),
])
.circuit_breaker(CircuitBreakerConfig {
    failure_threshold: 3,                        // consecutive failures before opening
    recovery_timeout: Duration::from_secs(30),   // wait before probing again
    half_open_max_requests: 1,                   // concurrent probes in half-open state
})
.build()?;

use perpcity_sdk::transport::RetryConfig;

let transport = TransportConfig::new(vec!["https://rpc.com".into()])
.retry(RetryConfig {
    max_retries: 2,                             // retry attempts for reads
    base_delay: Duration::from_millis(100),     // delay scales by 2^attempt
})
.build()?;

use perpcity_sdk::transport::ws::{WsManager, ReconnectConfig};
use std::time::Duration;

let ws = WsManager::connect(
    "wss://base-ws-url.com",
    ReconnectConfig {
        initial_backoff: Duration::from_millis(500),
        max_backoff: Duration::from_secs(30),
        backoff_multiplier: 2,
        max_attempts: 0,  // 0 = unlimited
    },
).await?;

// Subscribe to new block headers
let mut blocks = ws.subscribe_blocks().await?;
tokio::spawn(async move {
    while let Some(header) = blocks.recv().await {
        println!("New block: {}", header.number);
    }
});

// Subscribe to contract event logs
let mut logs = ws.subscribe_logs(filter).await?;
tokio::spawn(async move {
    while let Some(log) = logs.recv().await {
        println!("Event: {:?}", log);
    }
});

use perpcity_sdk::hft::position_manager::PositionManager;

let mut pm = PositionManager::new();

pm.track(ManagedPosition {
    perp_id,
    position_id: 42,
    is_long: true,
    entry_price: 3000.0,
    margin: 1000.0,
    stop_loss: Some(2800.0),
    take_profit: Some(3500.0),
    trailing_stop_pct: Some(0.05),   // 5% trailing stop
    trailing_stop_anchor: None,       // auto-set on first check
});

// In your trading loop, check all triggers against current prices
let actions = pm.check_triggers(current_price);
for action in actions {
    match action.trigger {
        TriggerType::StopLoss => { /* close position */ }
        TriggerType::TakeProfit => { /* close position */ }
        TriggerType::TrailingStop => { /* close position */ }
    }
}

pub struct Deployments {
    pub perp_manager: Address,
    pub usdc: Address,
    pub fees_module: Option<Address>,
    pub margin_ratios_module: Option<Address>,
    pub lockup_period_module: Option<Address>,
    pub sqrt_price_impact_limit_module: Option<Address>,
}

pub struct PerpData {
    pub id: B256,
    pub tick_spacing: i32,
    pub mark: f64,
    pub beacon: Address,
    pub bounds: Bounds,
    pub fees: Fees,
}

pub struct Bounds {
    pub min_margin: f64,
    pub min_taker_leverage: f64,
    pub max_taker_leverage: f64,
    pub liquidation_taker_ratio: f64,
}

pub struct Fees {
    pub creator_fee: f64,
    pub insurance_fee: f64,
    pub lp_fee: f64,
    pub liquidation_fee: f64,
}

pub struct OpenInterest {
    pub long_oi: f64,
    pub short_oi: f64,
}

pub struct LiveDetails {
    pub pnl: f64,
    pub funding_payment: f64,
    pub effective_margin: f64,
    pub is_liquidatable: bool,
}

pub struct CloseResult {
    pub tx_hash: B256,
    pub remaining_position_id: Option<U256>,
}

pub struct OpenTakerQuote {
    pub perp_delta: f64,
    pub usd_delta: f64,
}

pub struct OpenMakerQuote {
    pub perp_delta: f64,
    pub usd_delta: f64,
}

pub struct SwapQuote {
    pub perp_delta: f64,
    pub usd_delta: f64,
}

pub struct ManagedPosition {
    pub perp_id: [u8; 32],
    pub position_id: u64,
    pub is_long: bool,
    pub entry_price: f64,
    pub margin: f64,
    pub stop_loss: Option<f64>,
    pub take_profit: Option<f64>,
    pub trailing_stop_pct: Option<f64>,
    pub trailing_stop_anchor: Option<f64>,
}

pub enum TriggerType {
    StopLoss,
    TakeProfit,
    TrailingStop,
}

pub struct ReconnectConfig {
    pub initial_backoff: Duration,    // default: 500ms
    pub max_backoff: Duration,        // default: 30s
    pub backoff_multiplier: u32,      // default: 2
    pub max_attempts: u32,            // default: 0 (unlimited)
}

pub struct OpenTakerParams {
    pub is_long: bool,
    pub margin: f64,
    pub leverage: f64,
    pub unspecified_amount_limit: u128,
}

pub struct OpenMakerParams {
    pub margin: f64,
    pub price_lower: f64,
    pub price_upper: f64,
    pub liquidity: u128,
    pub max_amt0_in: u128,
    pub max_amt1_in: u128,
}

pub struct CloseParams {
    pub min_amt0_out: u128,
    pub min_amt1_out: u128,
    pub max_amt1_in: u128,
}

use perpcity_sdk::PerpCityError;

match client.open_taker(perp_id, params, Urgency::Normal).await {
    Ok(pos_id) => println!("Opened position: {pos_id}"),
    Err(PerpCityError::InvalidMargin { reason }) => eprintln!("Bad margin: {reason}"),
    Err(PerpCityError::TxReverted { reason }) => eprintln!("Reverted: {reason}"),
    Err(PerpCityError::TooManyInFlight { count, max }) => {
        eprintln!("Too many in-flight txs: {count}/{max}");
    }
    Err(e) => eprintln!("Error: {e}"),
}