Installation & Setup

This guide will help you install the PerpCity Python SDK and configure it for your application.

Prerequisites

Python 3.10 or higher
pip package manager
A wallet with a private key
Access to a Base chain RPC endpoint

Installation

pip install perpcity-sdk

For development with testing and linting tools:

pip install perpcity-sdk[dev]

Environment Configuration

Create a .env file in your project root:

RPC_URL=https://your-rpc-endpoint.example/v2/YOUR_KEY
PRIVATE_KEY=0xYOUR_PRIVATE_KEY
PERP_MANAGER_ADDRESS=0xYOUR_PERP_MANAGER
USDC_ADDRESS=0xYOUR_USDC

Never commit your .env file to version control. Add it to .gitignore to protect your private key.

Basic Setup

import os
from dotenv import load_dotenv
from perpcity_sdk import PerpCityContext

load_dotenv()

context = PerpCityContext(
    rpc_url=os.environ["RPC_URL"],
    private_key=os.environ["PRIVATE_KEY"],
    perp_manager_address=os.environ["PERP_MANAGER_ADDRESS"],
    usdc_address=os.environ["USDC_ADDRESS"],
)

# Verify connection
context.validate_chain_id()

Constructor Parameters

Parameter	Type	Required	Default	Description
`rpc_url`	`str`	Yes	-	Base chain RPC endpoint URL
`private_key`	`str`	Yes	-	Wallet private key (with 0x prefix)
`perp_manager_address`	`str`	Yes	-	PerpManager contract address
`usdc_address`	`str`	Yes	-	USDC token contract address
`chain_id`	`int`	No	`84532`	Chain ID (84532 = Base Sepolia)

Verify Installation

Test your setup with a simple query:

perp_id = "0xYOUR_PERP_ID"  # replace with your perp market identifier
perp_data = context.get_perp_data(perp_id)
print(f"Mark price: {perp_data.mark}")

Dependencies

The SDK depends on:

web3>=7.0.0 -- Ethereum interaction via web3.py
cachetools>=5.0.0 -- TTL-based config caching

Next Steps

Browse the API Reference for all available functions and types
See the TypeScript SDK Core Concepts for architecture patterns (the Python SDK mirrors the same design)

On this page