API Reference

const sdk = @import("perpcity_sdk");

var ctx = sdk.context.PerpCityContext.init(
    allocator,
    "https://base-rpc-url.com",
    private_key,
    .{
        .perp_manager = perp_manager_addr,
        .usdc = usdc_addr,
    },
);
ctx.fixPointers();
defer ctx.deinit();

const position = try sdk.perp_manager.openTakerPosition(&ctx, perp_id, .{
    .is_long = true,
    .margin = 1000.0,
    .leverage = 10.0,
    .unspecified_amount_limit = 0,
});

const position = try sdk.perp_manager.openMakerPosition(&ctx, perp_id, .{
    .margin = 10000.0,
    .price_lower = 2900.0,
    .price_upper = 3100.0,
    .liquidity = 1000000,
    .max_amt0_in = 1000000,
    .max_amt1_in = 1000000,
});

const result = try sdk.perp_manager.closePosition(&ctx, perp_id, position_id, .{
    .min_amt0_out = 0,
    .min_amt1_out = 0,
    .max_amt1_in = 1000000,
});

_ = try sdk.perp_manager.adjustNotional(&ctx, .{
    .position_id = pos_id,
    .usd_delta = 5000,
    .perp_limit = 0,
});

_ = try sdk.perp_manager.adjustMargin(&ctx, .{
    .position_id = pos_id,
    .margin_delta = 1000,
});

const perp_id = try sdk.perp_manager.createPerp(&ctx, .{
    .starting_price = 3000.0,
    .beacon = beacon_addr,
});

const live = try position.liveDetails();
const result = try position.closePosition(.{ ... });
_ = try position.adjustNotional(5000, 0);
_ = try position.adjustMargin(1000);
const hex = position.perpIdHex(); // [64]u8 hex string

var nonce_mgr = sdk.nonce.HftNonceManager.init(allocator, starting_nonce);
const nonce = nonce_mgr.acquireNonce(); // lock-free atomic
try nonce_mgr.trackSubmission(nonce, tx_hash);
nonce_mgr.confirmNonce(nonce);   // on success
nonce_mgr.releaseNonce(nonce);   // on failure
nonce_mgr.resync(on_chain_nonce);

var cache = sdk.gas.GasCache.init(.{});
cache.updateFromBlock(base_fee, now_ms);
const fees = cache.feesForUrgency(.critical, now_ms);

var rpc = try sdk.multi_rpc.MultiRpcProvider.init(allocator, &.{
    "https://primary-rpc.com",
    "https://fallback-rpc.com",
});
const endpoint = rpc.selectEndpoint(now_ms);

var tracker = sdk.latency.LatencyTracker{};
tracker.recordSample(latency_ns);
const stats = tracker.getStats(); // .p50_ns, .p95_ns, .p99_ns

var cache = sdk.state_cache.StateCache.init(allocator, .{
    .slow_ttl = 60,  // Fees, bounds (60s)
    .fast_ttl = 2,   // Mark prices (2s, ~1 Base L2 block)
});

var pm = sdk.position_manager.PositionManager.init(allocator);
try pm.track(.{
    .perp_id = perp_id,
    .position_id = pos_id,
    .is_long = true,
    .is_maker = false,
    .entry_price = 3000.0,
    .margin = 1000.0,
    .stop_loss = 2800.0,
    .take_profit = 3500.0,
    .trailing_stop_pct = 0.05,
});
const actions = pm.checkTriggers(current_price);

pub const Address = [20]u8;
pub const Bytes32 = [32]u8;

pub const PerpCityDeployments = struct {
    perp_manager: Address,
    usdc: Address,
    fees_module: ?Address = null,
    margin_ratios_module: ?Address = null,
    lockup_period_module: ?Address = null,
    sqrt_price_impact_limit_module: ?Address = null,
};

pub const PerpData = struct {
    id: Bytes32, tick_spacing: i24, mark: f64,
    beacon: Address, bounds: Bounds, fees: Fees,
};
pub const Bounds = struct {
    min_margin: f64, min_taker_leverage: f64,
    max_taker_leverage: f64, liquidation_taker_ratio: f64,
};
pub const Fees = struct {
    creator_fee: f64, insurance_fee: f64,
    lp_fee: f64, liquidation_fee: f64,
};

pub const OpenPositionData = struct {
    perp_id: Bytes32, position_id: u256,
    is_long: ?bool = null, is_maker: ?bool = null,
    live_details: LiveDetails,
};
pub const LiveDetails = struct {
    pnl: f64, funding_payment: f64,
    effective_margin: f64, is_liquidatable: bool,
};
pub const PositionRawData = struct {
    perp_id: Bytes32, position_id: u256, margin: f64,
    entry_perp_delta: i256, entry_usd_delta: i256,
    margin_ratios: MarginRatios,
};

pub const OpenTakerPositionParams = struct {
    is_long: bool, margin: f64, leverage: f64,
    unspecified_amount_limit: u128,
};
pub const OpenMakerPositionParams = struct {
    margin: f64, price_lower: f64, price_upper: f64,
    liquidity: u128, max_amt0_in: u128, max_amt1_in: u128,
};
pub const ClosePositionParams = struct {
    min_amt0_out: u128, min_amt1_out: u128, max_amt1_in: u128,
};
pub const AdjustNotionalParams = struct {
    position_id: u256, usd_delta: i128, perp_limit: u128,
};
pub const AdjustMarginParams = struct {
    position_id: u256, margin_delta: i128,
};

const position = sdk.perp_manager.openTakerPosition(&ctx, perp_id, params) catch |err| {
    switch (err) {
        error.MarginMustBePositive => ...,
        error.TransactionReverted => ...,
        error.RpcError => ...,
        else => ...,
    }
};