@varla/polymarket 1.0.0

package/AGENTS.md

@@ -0,0 +1,243 @@
+# AGENTS.md - AI Coding Assistant Instructions
+
+This file provides context for AI coding assistants (Cursor, Cline, Copilot, etc.) working on `@varla/polymarket`.
+
+## Package Overview
+
+`@varla/polymarket` is a high-performance Polymarket SDK that's **139% faster** than the official `@polymarket/clob-client`. It provides full trading support for Polymarket's CLOB and Gamma APIs.
+
+## Tech Stack
+
+| Technology | Purpose |
+|------------|---------|
+| **Bun** | Runtime & package manager (not Node.js) |
+| **viem** | Ethereum wallet/signing (not ethers.js) |
+| **Web Crypto API** | HMAC/SHA256 (not node:crypto) |
+| **fetch** | HTTP (not axios) |
+| **SQLite** | Order persistence (via @varla/db) |
+| **Biome** | Linting & formatting |
+
+## Critical Rules
+
+### ❌ DO NOT USE
+```typescript
+// Node.js APIs - will fail in Bun/edge
+import crypto from "node:crypto";
+import fs from "node:fs";
+import { Buffer } from "node:buffer";
+
+// ethers.js - we use viem
+import { ethers } from "ethers";
+
+// axios - we use fetch
+import axios from "axios";
+```
+
+### ✅ DO USE
+```typescript
+// Web Crypto API
+const key = await crypto.subtle.importKey(...);
+const sig = await crypto.subtle.sign("HMAC", key, data);
+
+// viem for wallets
+import { createWalletClient, http } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+
+// Native fetch
+const res = await fetch(url, { headers });
+
+// Bun file APIs
+const file = Bun.file("path");
+await Bun.write("path", content);
+```
+
+## Project Structure
+
+```
+packages/polymarket/
+├── src/
+│   ├── index.ts              # Public exports
+│   ├── clob-client.ts        # Public CLOB API (read-only)
+│   ├── clob-trading-client.ts # Authenticated trading
+│   ├── clob-auth.ts          # API key management, EIP712 auth
+│   ├── clob-orders.ts        # Order building & signing
+│   ├── clob-persistence.ts   # SQLite order tracking
+│   ├── clob-ws.ts            # WebSocket client
+│   ├── gamma-client.ts       # Gamma API (markets, metadata)
+│   ├── signing/              # HMAC & EIP712 signatures
+│   ├── config/               # Contract addresses, endpoints
+│   └── abi/                  # Contract ABIs
+├── test/
+│   ├── unit/                 # Deterministic unit tests
+│   ├── integration/          # Network mocking tests
+│   ├── sdk/                  # Parity tests vs official SDK
+│   ├── live/                 # Real API tests (optional)
+│   └── bench/                # Performance benchmarks
+└── docs/
+    └── SDK_COMPARISON.md     # Official SDK comparison
+```
+
+## Key Patterns
+
+### EIP712 Signing (Orders & Auth)
+
+```typescript
+// Use viem's signTypedData
+const signature = await walletClient.signTypedData({
+  account,
+  domain: { name: "...", chainId: 137 },
+  types: { ... },
+  primaryType: "...",
+  message: { ... },
+});
+```
+
+### HMAC Signing (API Requests)
+
+```typescript
+// Use Web Crypto API
+export async function buildPolyHmacSignature(params: {
+  secret: string;
+  timestamp: number;
+  method: string;
+  path: string;
+  body?: string;
+}): Promise<string> {
+  const message = `${params.timestamp}${params.method}${params.path}${params.body ?? ""}`;
+  const key = await crypto.subtle.importKey(
+    "raw",
+    base64ToUint8Array(params.secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  const sig = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(message));
+  return btoa(String.fromCharCode(...new Uint8Array(sig)));
+}
+```
+
+### HTTP Requests
+
+```typescript
+// Always use native fetch with proper error handling
+const response = await fetch(url, {
+  method: "POST",
+  headers: {
+    "Content-Type": "application/json",
+    ...this.buildAuthHeaders(timestamp, method, path, body),
+  },
+  body: JSON.stringify(payload),
+});
+
+if (!response.ok) {
+  throw new ClobHttpError(response.status, await response.text());
+}
+```
+
+## Testing
+
+### Run Tests
+
+```bash
+# All unit tests
+bun test packages/polymarket/test/unit
+
+# All tests (including integration)
+bun test packages/polymarket
+
+# With coverage
+bun test packages/polymarket --coverage
+
+# Run benchmarks
+POLYMARKET_BENCH=true bun test packages/polymarket/test/sdk
+
+# Live tests (requires API keys)
+POLYMARKET_LIVE_TESTS=1 bun test packages/polymarket/test/live
+```
+
+### Test Patterns
+
+```typescript
+import { describe, test, expect, beforeEach, mock } from "bun:test";
+
+describe("Feature", () => {
+  test("does X", async () => {
+    // Arrange
+    const input = ...;
+    
+    // Act
+    const result = await fn(input);
+    
+    // Assert
+    expect(result).toEqual(...);
+  });
+});
+```
+
+## Common Tasks
+
+### Add New API Method
+
+1. Add type to `src/clob-trading-types.ts`
+2. Add method to `src/clob-trading-client.ts`
+3. Add test to `test/unit/clob-trading-client.test.ts`
+4. Update `src/index.ts` exports if needed
+
+### Add New Config
+
+1. Add to `src/config/*.ts`
+2. Export from `src/config/index.ts`
+3. Re-export from `src/index.ts`
+
+### Debug Signature Issues
+
+1. Run SDK comparison test: `bun test test/sdk/reference-examples.test.ts -t "signing"`
+2. Compare with `.reference/clob-client-repo/tests/` fixtures
+3. Check EIP712 domain/types match exactly
+
+## Performance
+
+Our SDK is significantly faster than the official SDK:
+
+| Metric | Value |
+|--------|-------|
+| Average speedup | **139%** |
+| Functions faster | 81/88 (92%) |
+| Best case | 1233% faster (RFQ cancel) |
+
+Key optimizations:
+- Native fetch vs axios
+- Web Crypto vs node:crypto polyfills
+- viem vs ethers.js
+- Zero unnecessary serialization
+
+## Environment Variables
+
+```bash
+# Required for trading
+POLYMARKET_API_KEY=...
+POLYMARKET_SECRET=...
+POLYMARKET_PASSPHRASE=...
+
+# Required for signing orders
+PRIVATE_KEY=0x...
+
+# Optional
+POLYMARKET_BASE_URL=https://clob.polymarket.com  # default
+```
+
+## Useful Commands
+
+```bash
+# Format code
+bun x biome format --write packages/polymarket
+
+# Lint
+bun x biome check packages/polymarket
+
+# Type check
+bun run typecheck
+
+# Check no Node imports
+bun run check:no-node-imports
+```

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Varla
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,354 @@
+# @varla/polymarket
+
+[![npm version](https://img.shields.io/npm/v/@varla/polymarket.svg)](https://www.npmjs.com/package/@varla/polymarket)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![CI](https://github.com/Varla-xyz/varla-api/actions/workflows/ci.yml/badge.svg)](https://github.com/Varla-xyz/varla-api/actions/workflows/ci.yml)
+
+**High-performance Polymarket SDK** — 139% faster than the official SDK.
+
+A modern, lightweight TypeScript client for Polymarket's CLOB and Gamma APIs with full trading support.
+
+## Why @varla/polymarket?
+
+| Metric | @varla/polymarket | @polymarket/clob-client |
+|--------|-------------------|-------------------------|
+| **Average Speed** | **139% faster** | baseline |
+| **Bundle Size** | ~50KB | ~500KB (ethers.js) |
+| **Runtime** | Bun/Node/Edge | Node.js only |
+| **Signing** | viem (native) | ethers.js |
+| **HTTP** | fetch | axios |
+
+### Benchmark Highlights
+
+| Function | Speedup |
+|----------|---------|
+| `getLastTradePrice` | 261% faster |
+| `getMidpoints` | 176% faster |
+| `deleteApiKey` | 144% faster |
+| `cancelOrder` | 73% faster |
+| `getOpenOrders` | 56% faster |
+
+<details>
+<summary>Full benchmark results (88 functions)</summary>
+
+- **81 functions faster** (92%)
+- **7 functions slower** (8%)
+- Best case: 1233% faster (RFQ operations)
+
+Run benchmarks yourself:
+```bash
+POLYMARKET_BENCH=true bun test packages/polymarket/test/sdk
+```
+</details>
+
+## Installation
+
+```bash
+bun add @varla/polymarket
+# or
+npm install @varla/polymarket
+# or
+pnpm add @varla/polymarket
+```
+
+**Peer dependencies:**
+- `viem` ^2.0.0
+
+## Quick Start
+
+### Read-Only (No Auth Required)
+
+```typescript
+import { GammaClient, ClobClient } from "@varla/polymarket";
+
+// Fetch markets from Gamma API
+const gamma = new GammaClient();
+const markets = await gamma.getMarkets({ limit: 10 });
+
+// Get orderbook from CLOB
+const clob = new ClobClient();
+const book = await clob.getBook(markets[0].clobTokenIds[0]);
+console.log("Best bid:", book.bids[0]);
+console.log("Best ask:", book.asks[0]);
+
+// Get prices
+const midpoint = await clob.getMidpoint(markets[0].clobTokenIds[0]);
+const spread = await clob.getSpread(markets[0].clobTokenIds[0]);
+```
+
+### Authenticated Trading
+
+```typescript
+import { createWalletClient, http } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import { polygon } from "viem/chains";
+import { ClobTradingClient } from "@varla/polymarket";
+
+// Create wallet
+const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
+const walletClient = createWalletClient({
+  account,
+  chain: polygon,
+  transport: http(),
+});
+
+// Create trading client
+const client = new ClobTradingClient(walletClient);
+await client.init(); // Derives API key from wallet
+
+// Place a limit order
+const response = await client.createAndPostOrder(
+  {
+    tokenId: "123456...",  // From Gamma API
+    price: 0.50,           // $0.50 per share
+    size: 100,             // 100 shares
+    side: "BUY",
+  },
+  {
+    tickSize: "0.01",      // From Gamma API
+    negRisk: false,        // From Gamma API
+  },
+  "GTC" // Good-Til-Cancelled
+);
+
+console.log("Order ID:", response.orderID);
+
+// Cancel order
+await client.cancelOrder(response.orderID);
+
+// Get open orders
+const orders = await client.getOpenOrders();
+```
+
+### WebSocket (Real-time Updates)
+
+```typescript
+import { ClobWsClient } from "@varla/polymarket";
+
+const ws = new ClobWsClient({
+  onBookUpdate: (update) => {
+    console.log("Market:", update.market);
+    console.log("Best bid:", update.bids[0]);
+    console.log("Best ask:", update.asks[0]);
+  },
+  onConnect: () => console.log("Connected"),
+  onDisconnect: (reason) => console.log("Disconnected:", reason),
+});
+
+ws.connect();
+ws.subscribeMarket("0x5f65177b394277fd294cd75650044e32ba009a95...");
+
+// Cleanup
+ws.close();
+```
+
+### Order Persistence (SQLite)
+
+Track orders locally for fast queries and restart recovery:
+
+```typescript
+import { 
+  ClobTradingClient, 
+  createSqliteOrderPersistence,
+  createTrackedOrder,
+} from "@varla/polymarket";
+
+const persistence = createSqliteOrderPersistence("./orders.db");
+
+// Track placed orders
+const order = createTrackedOrder({
+  orderId: response.orderID,
+  market: "0x...",
+  tokenId: "123456...",
+  side: "BUY",
+  price: 0.5,
+  size: 100,
+  orderType: "GTC",
+  status: "OPEN",
+});
+await persistence.save(order);
+
+// Query orders
+const openOrders = await persistence.getOpen();
+const marketOrders = await persistence.getByMarket("0x...");
+
+// Cleanup old orders
+await persistence.prune(24 * 60 * 60 * 1000); // 24h
+
+persistence.close();
+```
+
+## API Reference
+
+### Clients
+
+| Client | Purpose |
+|--------|---------|
+| `GammaClient` | Market discovery, metadata, token IDs |
+| `ClobClient` | Public orderbook, prices, trades (read-only) |
+| `ClobTradingClient` | Authenticated trading operations |
+| `ClobWsClient` | Real-time WebSocket updates |
+
+### ClobTradingClient Methods
+
+```typescript
+// Initialization
+client.init()                           // Derive/create API key
+client.setCredentials(creds)            // Set API key manually
+
+// Orders
+client.createOrder(params, options)     // Create signed order
+client.postOrder(order, type)           // Post to CLOB
+client.createAndPostOrder(params, options, type)  // Combined
+client.getOrder(orderId)                // Get order details
+client.getOpenOrders(filter?)           // List open orders
+
+// Cancellation
+client.cancelOrder(orderId)             // Cancel one order
+client.cancelOrders(orderIds)           // Cancel multiple
+client.cancelMarketOrders({ market })   // Cancel by market
+client.cancelAll()                      // Cancel all orders
+
+// Account
+client.getClosedOnlyMode()              // Check if account is restricted
+```
+
+### Order Types
+
+```typescript
+type Side = "BUY" | "SELL";
+type OrderType = "GTC" | "GTD" | "FOK";  // Good-Til-Cancel, Good-Til-Date, Fill-Or-Kill
+type OrderStatus = "OPEN" | "MATCHED" | "FILLED" | "CANCELLED" | "EXPIRED";
+```
+
+## Configuration
+
+### Environment Variables
+
+```bash
+# For authenticated trading
+POLYMARKET_API_KEY=...
+POLYMARKET_SECRET=...
+POLYMARKET_PASSPHRASE=...
+
+# For signing orders
+PRIVATE_KEY=0x...
+```
+
+### Custom Endpoints
+
+```typescript
+const client = new ClobTradingClient(walletClient, {
+  baseUrl: "https://clob.polymarket.com",  // default
+  requestTimeoutMs: 15000,
+  maxRetries: 3,
+});
+```
+
+### Signature Types
+
+| Type | Value | Use Case |
+|------|-------|----------|
+| EOA | 0 | Direct wallet (Metamask, Rabby, hardware) |
+| POLY_PROXY | 1 | Polymarket Magic/Email login |
+
+```typescript
+// For Magic/Email wallets
+const client = new ClobTradingClient(walletClient, {
+  signatureType: 1,  // POLY_PROXY
+  funderAddress: "0x...",  // Your Polymarket profile address
+});
+```
+
+## Error Handling
+
+```typescript
+import { OrderValidationError, ClobHttpError } from "@varla/polymarket";
+
+try {
+  await client.createAndPostOrder(params, options, "GTC");
+} catch (error) {
+  if (error instanceof OrderValidationError) {
+    console.error("Invalid order:", error.message);
+  } else if (error instanceof ClobHttpError) {
+    if (error.status === 401) {
+      // API key expired, reinitialize
+      await client.init();
+    }
+  }
+}
+```
+
+## Validation Utilities
+
+```typescript
+import { 
+  validateOrderParams, 
+  roundToTickSize,
+  isValidPrice,
+  getMinimumOrderSize,
+} from "@varla/polymarket";
+
+// Validate before creating
+validateOrderParams(params, options); // throws OrderValidationError
+
+// Round to valid tick
+const price = roundToTickSize(0.505, "0.01"); // 0.51
+
+// Check price validity
+isValidPrice(0.505, "0.01"); // false
+
+// Get minimum shares for $1 order
+getMinimumOrderSize(0.5); // 2 shares
+```
+
+## Testing
+
+```bash
+# Unit tests
+bun test packages/polymarket/test/unit
+
+# All tests
+bun test packages/polymarket
+
+# With coverage
+bun test packages/polymarket --coverage
+
+# Benchmarks (compare with official SDK)
+POLYMARKET_BENCH=true bun test packages/polymarket/test/sdk
+
+# Live tests (requires API keys)
+POLYMARKET_LIVE_TESTS=1 bun test packages/polymarket/test/live
+```
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    ClobTradingClient                        │
+│  - init(), createAndPostOrder(), cancelOrder(), etc.        │
+├─────────────────────┬───────────────────┬───────────────────┤
+│   ClobAuthManager   │  ClobOrderBuilder │  HTTP + Auth      │
+│   - L1/L2 auth      │  - EIP712 signing │  - HMAC headers   │
+│   - API key mgmt    │  - Validation     │                   │
+├─────────────────────┴───────────────────┴───────────────────┤
+│                       viem WalletClient                      │
+│                    (signTypedData, etc.)                     │
+└─────────────────────────────────────────────────────────────┘
+
+┌──────────────────┐  ┌─────────────────┐  ┌────────────────┐
+│ OrderPersistence │  │  ClobWsClient   │  │  GammaClient   │
+│ - SQLite/Memory  │  │  - WebSocket    │  │  - Markets     │
+│ - Order tracking │  │  - Book updates │  │  - Metadata    │
+└──────────────────┘  └─────────────────┘  └────────────────┘
+```
+
+## Related Packages
+
+- [`@varla/db`](../db) - SQLite persistence layer
+- [`@varla/rpc`](../rpc) - Resilient RPC client
+- [`@varla/runtime`](../runtime) - Service runtime utilities
+
+## License
+
+MIT © [Varla](https://varla.xyz)