API Reference

from perpcity_sdk import PerpCityContext

context = PerpCityContext(
    rpc_url="https://your-rpc-endpoint.example/v2/YOUR_KEY",
    private_key="0xYOUR_PRIVATE_KEY",
    perp_manager_address="0xPERP_MANAGER",
    usdc_address="0xUSDC",
    chain_id=84532,  # optional, defaults to Base Sepolia
)

perp_data = context.get_perp_data(perp_id)
print(perp_data.mark)      # Current mark price
print(perp_data.beacon)    # Oracle address
print(perp_data.bounds)    # Market bounds
print(perp_data.fees)      # Fee structure

from perpcity_sdk import create_perp, CreatePerpParams

perp_id = create_perp(context, CreatePerpParams(
    starting_price=3000.0,
    beacon="0x...",
))

from perpcity_sdk import open_taker_position, OpenTakerPositionParams

position = open_taker_position(context, perp_id, OpenTakerPositionParams(
    is_long=True,
    margin=1000,
    leverage=5,
    unspecified_amount_limit=0,
))

from perpcity_sdk import open_maker_position, OpenMakerPositionParams

position = open_maker_position(context, perp_id, OpenMakerPositionParams(
    margin=10000,
    price_lower=2900,
    price_upper=3100,
    liquidity=1000000,
    max_amt0_in=1000000,
    max_amt1_in=1000000,
))

# Close the position
result = position.close_position(ClosePositionParams(
    min_amt0_out=0,
    min_amt1_out=0,
    max_amt1_in=1000000,
))

# Check live details
details = position.live_details()
print(details.pnl)
print(details.effective_margin)
print(details.is_liquidatable)

from perpcity_sdk import close_position, ClosePositionParams

result = close_position(context, perp_id, position_id, ClosePositionParams(
    min_amt0_out=0,
    min_amt1_out=0,
    max_amt1_in=1000000,
))

@dataclass(frozen=True)
class PerpData:
    id: str
    tick_spacing: int
    mark: float
    beacon: str
    bounds: Bounds
    fees: Fees

@dataclass(frozen=True)
class Bounds:
    min_margin: float
    min_taker_leverage: float
    max_taker_leverage: float
    liquidation_taker_ratio: float

@dataclass(frozen=True)
class Fees:
    creator_fee: float
    insurance_fee: float
    lp_fee: float
    liquidation_fee: float

@dataclass(frozen=True)
class LiveDetails:
    pnl: float
    funding_payment: float
    effective_margin: float
    is_liquidatable: bool

@dataclass(frozen=True)
class OpenPositionData:
    perp_id: str
    position_id: int
    live_details: LiveDetails
    is_long: bool | None = None
    is_maker: bool | None = None

@dataclass(frozen=True)
class UserData:
    wallet_address: str
    usdc_balance: float
    open_positions: list[OpenPositionData]

@dataclass(frozen=True)
class PositionRawData:
    perp_id: str
    position_id: int
    margin: float
    entry_perp_delta: int
    entry_usd_delta: int
    margin_ratios: MarginRatios

@dataclass
class OpenTakerPositionParams:
    is_long: bool
    margin: float
    leverage: float
    unspecified_amount_limit: int

@dataclass
class OpenMakerPositionParams:
    margin: float
    price_lower: float
    price_upper: float
    liquidity: int
    max_amt0_in: int
    max_amt1_in: int

@dataclass
class ClosePositionParams:
    min_amt0_out: float
    min_amt1_out: float
    max_amt1_in: float

@dataclass
class CreatePerpParams:
    starting_price: float
    beacon: str
    fees: str | None = None
    margin_ratios: str | None = None
    lockup_period: str | None = None
    sqrt_price_impact_limit: str | None = None

from perpcity_sdk import PerpCityError

try:
    position = open_taker_position(context, perp_id, params)
except PerpCityError as e:
    print(f"Error: {e}")