Installation

Prerequisites

Zig >= 0.15.2
A wallet private key
Access to a Base chain RPC endpoint
Anvil / Foundry (optional, for integration tests)

Add as a Dependency

Add to your build.zig.zon:

.dependencies = .{
    .perpcity_sdk = .{
        .url = "git+https://github.com/StrobeLabs/perpcity-zig-sdk.git#main",
        .hash = "...", // run `zig build` and it will tell you the expected hash
    },
},

The SDK's dependency on eth.zig is fetched automatically.

Configure build.zig

const sdk_dep = b.dependency("perpcity_sdk", .{
    .target = target,
    .optimize = optimize,
});
exe.root_module.addImport("perpcity_sdk", sdk_dep.module("perpcity_sdk"));

For pure math only (no network, no eth.zig dependency):

exe.root_module.addImport("perpcity_math", sdk_dep.module("math_root"));

Basic Setup

const std = @import("std");
const sdk = @import("perpcity_sdk");

pub fn main() !void {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer _ = gpa.deinit();
    const allocator = gpa.allocator();

    const private_key: [32]u8 = undefined; // TODO: your private key bytes
    const perp_manager_addr: [20]u8 = undefined; // TODO: PerpManager contract address
    const usdc_addr: [20]u8 = undefined; // TODO: USDC contract address

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

    try ctx.setupForTrading();
}

Always call ctx.fixPointers() immediately after init(). This updates internal pointer references between the transport, provider, and wallet.

Build Commands

zig build                  # Build
zig build test             # Unit tests (pure math, no network)
zig build integration-test # Integration tests (requires Anvil)
zig fmt --check src/ tests/ # Format check

Next Steps

Browse the API Reference for all types, functions, and HFT infrastructure
See eth.zig for the underlying Ethereum library