Skip to content

Real Execution Engine Implementation Plan (Phase 5)

Goal

Implement PolymarketClient and KalshiClient structs that comply with the ExchangeClient trait, enabling the ExecutionActor to perform real trades.

Design Philosophy

  • Manual Implementation: We will implement the API calls and Authentication logic directly using robust cryptographic libraries (alloy, rsa) rather than relying on third-party SDK wrappers. This ensures:
  • Control: We own the retry logic, timeout handling, and serialization.
  • Minimal Dependencies: Avoids bloat from full SDKs.
  • Security: Direct handling of logical signatures.

1. Polymarket Client

Dependencies

  • alloy: For Ethereum EIP-712 signing.
  • reqwest: For HTTP requests (CLOB).
  • serde: For JSON.

Authentication (L1/L2)

Polymarket uses a hybrid auth: 1. L1: Orders are signed using EIP-712 with the wallet's Private Key. This is required for placing orders. 2. L2: API Key (Proxy) can be used for fetching data, but we focus on Execution (L1 Signing). * Correction: CLOB API uses L2 Headers (Api-Key, Signature) for access, but the Order Payload itself must correspond to the L1 address credentials or be signed? * Research Update: To place an order, you POST signed EIP-712 data. You also need to authenticate the HTTP request via Headers (L2 API Key) deriving from the L1 key. * Simplification: We will implement L2 Header generation (signing timestamp+request) AND Order Signing (EIP-712).

Structs

pub struct PolymarketClient {
    client: reqwest::Client,
    signer: alloy::signers::LocalWallet, // Private Key
    l2_gateway_key: String, // Derived/provided API Key
}

EIP-712 Domain

{
  "name": "Polymarket CTF Exchange",
  "version": "1",
  "chainId": 137,
  "verifyingContract": "0x4bFb41d5B3570DeFd03C39a9A4D8DQE5806f0694"
}

2. Kalshi Client

Dependencies

  • rsa: For RSA-PSS signing.
  • reqwest: For HTTP.
  • base64.

Authentication

Kalshi v2 requires: - KALSHI-ACCESS-KEY: UUID. - KALSHI-ACCESS-SIGNATURE: RSA-PSS-SHA256 signature of timestamp + method + path. - KALSHI-ACCESS-TIMESTAMP: Current time.

Structs

pub struct KalshiClient {
    client: reqwest::Client,
    key_id: String,
    private_key: rsa::RsaPrivateKey,
}

3. Configuration & Safety

  • Environment Variables:
  • POLY_PRIVATE_KEY (Hex)
  • POLY_API_KEY (UUID/String)
  • POLY_API_SECRET (String)
  • POLY_API_PASSPHRASE (String)
  • KALSHI_API_KEY (UUID)
  • KALSHI_PRIVATE_KEY (PEM Content or Path)
  • Feature Flags:
  • Use mock_execution flag in main.rs to toggle between Mock and Real clients easily.

4. Verification

  • Unit Tests: Test signature generation logic against known vectors.
  • Integration: "Paper Trade" attempt (Place order far from market? Or use Testnet if available).
  • Polymarket: Examples on Mumbai/Amoy testnet?
  • Kalshi: Demo env?
  • Council: Verify implementation of Auth logic.