API Reference

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

let transport = HftTransport::new(
    TransportConfig::builder()
        .shared_endpoint("https://base.g.alchemy.com/v2/KEY")
        .read_endpoint("https://base-rpc.publicnode.com")
        .build()?,
)?;

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

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

use perpcity_sdk::{OpenTakerParams, Urgency};

let result = 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?;

println!("Position ID: {}", result.pos_id);
println!("Entry deltas: perp={}, usd={}", result.perp_delta, result.usd_delta);

use perpcity_sdk::OpenMakerParams;

let result = 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: u128::MAX,
}, Urgency::Normal).await?;

println!("Net margin returned: {:.2}", result.net_margin);
println!("Was liquidated: {}", result.was_liquidated);

use perpcity_sdk::AdjustNotionalParams;

let result = client.adjust_notional(pos_id, &AdjustNotionalParams {
    usd_delta: 5.0,          // positive = receive USD / reduce exposure
    perp_limit: u128::MAX,   // slippage limit
}, Urgency::Normal).await?;

println!("New perp delta: {}", result.new_perp_delta);

use perpcity_sdk::AdjustMarginParams;

let result = client.adjust_margin(pos_id, &AdjustMarginParams {
    margin_delta: 50.0,  // positive = deposit, negative = withdraw
}, Urgency::Normal).await?;

println!("New margin: {:.2}", result.new_margin);

let tx_hash = client.transfer_eth(recipient, amount_wei, Urgency::Normal).await?;

let tx_hash = client.transfer_usdc(recipient, 100.0, Urgency::Normal).await?;

let (config, snapshot) = client.get_perp_snapshot(perp_id).await?;

// Static config
println!("Beacon: {:?}", config.beacon);
println!("Max leverage: {:.0}x", config.bounds.max_taker_leverage);

// Live market data
println!("Mark: {:.2}, Index: {:.2}", snapshot.mark_price, snapshot.index_price);
println!("Funding: {:.4}/day", snapshot.funding_rate_daily);
println!("OI -- long: {:.2}, short: {:.2}", snapshot.open_interest.long_oi, snapshot.open_interest.short_oi);

// Single address
let (usdc, eth) = client.get_balances(address).await?;

// Multiple addresses -- 1 CU regardless of count
let balances = client.get_balances_batch(&[addr1, addr2, addr3]).await?;
for (usdc, eth) in &balances {
    println!("USDC: {usdc}, ETH: {eth}");
}

let config  = client.get_perp_config(perp_id).await?;   // mark, fees, bounds
let mark    = client.get_mark_price(perp_id).await?;     // f64 price
let funding = client.get_funding_rate(perp_id).await?;   // daily rate
let oi      = client.get_open_interest(perp_id).await?;  // long/short OI
let live    = client.get_live_details(pos_id).await?;     // PnL, funding, liquidation
let balance = client.get_usdc_balance().await?;           // wallet USDC

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?;

Read request:  read_endpoints → shared_endpoints (fallback)
Write request: write_endpoints → shared_endpoints (fallback)

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

let transport = HftTransport::new(
    TransportConfig::builder()
        .shared_endpoint("https://base.g.alchemy.com/v2/KEY")  // writes + read fallback
        .read_endpoint("https://base-rpc.publicnode.com")       // dedicated reads (free)
        .strategy(Strategy::LatencyBased)
        .request_timeout(Duration::from_secs(2))
        .build()?,
)?;

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

let transport = HftTransport::new(
    TransportConfig::builder()
        .shared_endpoint("https://primary-rpc.com")
        .circuit_breaker(CircuitBreakerConfig {
            failure_threshold: 3,
            recovery_timeout: Duration::from_secs(30),
            half_open_max_requests: 1,
        })
        .build()?,
)?;

use perpcity_sdk::transport::config::{ReadRetryConfig, WriteRetryConfig};

let transport = HftTransport::new(
    TransportConfig::builder()
        .shared_endpoint("https://rpc.com")
        .read_retry(ReadRetryConfig {
            max_retries: 2,
            base_delay: Duration::from_millis(100),
        })
        .write_retry(WriteRetryConfig {
            max_retries: 3,
            base_delay: Duration::from_millis(500),
        })
        .build()?,
)?;

use perpcity_sdk::{MarketFeed, MarketEvent};
use perpcity_sdk::transport::ws::{WsManager, ReconnectConfig};

// Connect to WebSocket
let ws = WsManager::connect("wss://base-rpc.publicnode.com", ReconnectConfig::default()).await?;

// Subscribe to events for a specific perp
let mut feed = MarketFeed::new(&ws, perp_id).await?;

while let Some(event) = feed.next().await {
    match event {
        MarketEvent::PositionOpened { pos_id, mark_price, long_oi, short_oi, .. } => {
            println!("Position opened: {pos_id}, mark: {mark_price}");
        }
        MarketEvent::PositionClosed { pos_id, was_liquidated, net_margin, .. } => {
            println!("Position closed: {pos_id}, liquidated: {was_liquidated}");
        }
        MarketEvent::NotionalAdjusted { pos_id, mark_price, .. } => {
            println!("Notional adjusted: {pos_id}");
        }
        MarketEvent::IndexUpdated { index } => {
            println!("Oracle index: {index}");
        }
    }
}

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),
    trailing_stop_anchor: None,
});

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 PerpSnapshot {
    pub mark_price: f64,
    pub index_price: f64,
    pub funding_rate_daily: f64,
    pub open_interest: OpenInterest,
}

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

pub struct OpenResult {
    pub pos_id: U256,
    pub is_maker: bool,
    pub perp_delta: f64,
    pub usd_delta: f64,
    pub tick_lower: i32,
    pub tick_upper: i32,
}

pub struct CloseResult {
    pub tx_hash: B256,
    pub was_maker: bool,
    pub was_liquidated: bool,
    pub exit_perp_delta: f64,
    pub exit_usd_delta: f64,
    pub net_usd_delta: f64,
    pub funding: f64,
    pub utilization_fee: f64,
    pub adl: f64,
    pub liquidation_fee: f64,
    pub net_margin: f64,
    pub remaining_position_id: Option<U256>,
}

pub struct AdjustNotionalResult {
    pub new_perp_delta: f64,
    pub swap_perp_delta: f64,
    pub swap_usd_delta: f64,
    pub funding: f64,
    pub utilization_fee: f64,
    pub adl: f64,
    pub trading_fees: f64,
}

pub struct AdjustMarginResult {
    pub new_margin: f64,
}

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,
}

pub struct AdjustNotionalParams {
    pub usd_delta: f64,
    pub perp_limit: u128,
}

pub struct AdjustMarginParams {
    pub margin_delta: f64,
}

use perpcity_sdk::PerpCityError;

match client.open_taker(perp_id, &params, Urgency::Normal).await {
    Ok(result) => println!("Opened position: {}", result.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}"),
}