Installation & Setup

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

Prerequisites

Node.js 18 or higher
pnpm, npm, or yarn package manager
A wallet with a private key or connection to a wallet provider
Access to a Base chain RPC endpoint

Installation

Install the SDK using your preferred package manager:

# pnpm
pnpm add @strobelabs/perpcity-sdk

# npm
npm install @strobelabs/perpcity-sdk

# yarn
yarn add @strobelabs/perpcity-sdk

Environment Configuration

Create a .env file in your project root with the required configuration:

# Required
RPC_URL=https://mainnet.base.org
PRIVATE_KEY=your_private_key_here  # Without 0x prefix
PERP_MANAGER_ADDRESS=0x...
USDC_ADDRESS=0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913  # Base mainnet USDC

# Optional - Module addresses for perp creation
FEES_MODULE_ADDRESS=0x...
MARGIN_RATIOS_MODULE_ADDRESS=0x...
LOCKUP_PERIOD_MODULE_ADDRESS=0x...
PRICE_IMPACT_LIMITS_MODULE_ADDRESS=0x...

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

Basic Setup

Option 1: Using Private Key (for scripts and bots)

import { PerpCityContext } from '@strobelabs/perpcity-sdk'
import { createWalletClient, http } from 'viem'
import { base } from 'viem/chains'
import { privateKeyToAccount } from 'viem/accounts'

// Create account from private key
const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`)

// Create wallet client
const walletClient = createWalletClient({
  account,
  chain: base,
  transport: http(process.env.RPC_URL)
})

// Initialize PerpCity context
const context = new PerpCityContext({
  walletClient,
  rpcUrl: process.env.RPC_URL!,
  deployments: {
    perpManager: process.env.PERP_MANAGER_ADDRESS as `0x${string}`,
    usdc: process.env.USDC_ADDRESS as `0x${string}`
  }
})

Option 2: Using Wagmi (for React applications)

import { useWalletClient } from 'wagmi'
import { PerpCityContext } from '@strobelabs/perpcity-sdk'
import { useMemo } from 'react'

function usePerpCity() {
  const { data: walletClient } = useWalletClient()

  const context = useMemo(() => {
    if (!walletClient) return null

    return new PerpCityContext({
      walletClient,
      rpcUrl: process.env.NEXT_PUBLIC_RPC_URL!,
      deployments: {
        perpManager: '0x...',
        usdc: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
      }
    })
  }, [walletClient])

  return context
}

See Wagmi Integration for a complete example.

Verify Installation

Test your setup with a simple query:

import { getUserUsdcBalance } from '@strobelabs/perpcity-sdk'

// Step 1: Fetch user data via context method
const userData = await context.getUserData(
  walletClient.account.address,
  [] // No positions needed for balance check
)

// Step 2: Extract balance using pure function
const balance = getUserUsdcBalance(userData)
console.log(`USDC Balance: ${balance}`)

// Optional: verify RPC endpoint matches wallet chain
await context.validateChainId()

Next Steps

Now that you have the SDK installed and configured:

Troubleshooting

RPC Rate Limiting

If you encounter rate limiting errors, consider using a paid RPC provider like:

TypeScript Errors

Ensure you have the correct TypeScript configuration:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "strict": true
  }
}

On this page