@varla/polymarket 1.0.0 → 1.1.2

package/AGENTS.md

@@ -6,6 +6,8 @@ This file provides context for AI coding assistants (Cursor, Cline, Copilot, etc
 
 `@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.
 
+**Total API Coverage: 91 methods across 6 clients**
+
 ## Tech Stack
 
 | Technology | Purpose |
@@ -14,7 +16,6 @@ This file provides context for AI coding assistants (Cursor, Cline, Copilot, etc
 | **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
@@ -57,13 +58,15 @@ await Bun.write("path", content);
 packages/polymarket/
 ├── src/
 │   ├── index.ts              # Public exports
-│   ├── clob-client.ts        # Public CLOB API (read-only)
-│   ├── clob-trading-client.ts # Authenticated trading
+│   ├── gamma-client.ts       # Gamma API (28 methods)
+│   ├── clob-client.ts        # Public CLOB API (5 methods)
+│   ├── clob-trading-client.ts # Authenticated trading (30 methods)
+│   ├── data-api-client.ts    # Data/Analytics API (16 methods)
+│   ├── bridge-client.ts      # Bridge API (5 methods)
+│   ├── clob-ws.ts            # WebSocket client (7 methods)
 │   ├── 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)
+│   ├── clob-persistence.ts   # Order tracking (in-memory)
 │   ├── signing/              # HMAC & EIP712 signatures
 │   ├── config/               # Contract addresses, endpoints
 │   └── abi/                  # Contract ABIs
@@ -77,6 +80,212 @@ packages/polymarket/
     └── SDK_COMPARISON.md     # Official SDK comparison
 ```
 
+---
+
+## Complete API Reference
+
+### GammaClient (28 methods)
+
+Market discovery, metadata, and content API.
+
+```typescript
+import { GammaClient } from "@varla/polymarket";
+const gamma = new GammaClient(opts?: GammaClientOpts);
+```
+
+| Method | Parameters | Returns |
+|--------|------------|---------|
+| **Markets** | | |
+| `listMarkets` | `{ active?, closed?, limit?, offset?, tag_id? }` | `Promise<GammaMarket[]>` |
+| `getMarketsByConditionIds` | `conditionIds: string[]` | `Promise<GammaMarket[]>` |
+| `getMarketById` | `id: string` | `Promise<GammaMarket>` |
+| `getMarketBySlug` | `slug: string` | `Promise<GammaMarket>` |
+| `getMarketTags` | `marketId: string` | `Promise<GammaTag[]>` |
+| **Events** | | |
+| `listEvents` | `{ active?, closed?, limit?, offset?, tag_id?, series_id?, order?, ascending? }` | `Promise<GammaEvent[]>` |
+| `getEventById` | `id: string` | `Promise<GammaEvent>` |
+| `getEventBySlug` | `slug: string` | `Promise<GammaEvent>` |
+| `getEventTags` | `eventId: string` | `Promise<GammaTag[]>` |
+| **Tags** | | |
+| `listTags` | `{ limit?, offset? }` | `Promise<GammaTag[]>` |
+| `getTagById` | `id: string` | `Promise<GammaTag>` |
+| `getTagBySlug` | `slug: string` | `Promise<GammaTag>` |
+| `getRelatedTagsById` | `id: string` | `Promise<GammaTag[]>` |
+| `getRelatedTagsBySlug` | `slug: string` | `Promise<GammaTag[]>` |
+| `getTagRelationshipsById` | `id: string` | `Promise<GammaTagRelationship[]>` |
+| `getTagRelationshipsBySlug` | `slug: string` | `Promise<GammaTagRelationship[]>` |
+| **Sports** | | |
+| `getSports` | — | `Promise<GammaSport[]>` |
+| `listTeams` | `{ sport?, limit?, offset? }` | `Promise<GammaTeam[]>` |
+| `getValidSportsMarketTypes` | — | `Promise<GammaSportsMarketType[]>` |
+| **Series** | | |
+| `listSeries` | `{ limit?, offset? }` | `Promise<GammaSeries[]>` |
+| `getSeriesById` | `id: string` | `Promise<GammaSeries>` |
+| **Search** | | |
+| `search` | `query: string, { limit?, offset? }` | `Promise<GammaSearchResult>` |
+| **Profiles** | | |
+| `getPublicProfile` | `address: string` | `Promise<GammaPublicProfile>` |
+| **Comments** | | |
+| `listComments` | `{ eventId?, marketId?, limit?, offset? }` | `Promise<GammaComment[]>` |
+| `getCommentById` | `id: string` | `Promise<GammaComment>` |
+| `getCommentsByUser` | `address: string, { limit?, offset? }` | `Promise<GammaComment[]>` |
+| **Builders** | | |
+| `getBuilderLeaderboard` | `{ period?, limit?, offset? }` | `Promise<GammaBuilderLeaderboardEntry[]>` |
+| `getBuilderVolume` | `{ address?, startDate?, endDate? }` | `Promise<GammaBuilderVolumePoint[]>` |
+| **Health** | | |
+| `healthCheck` | — | `Promise<{ status: string }>` |
+
+---
+
+### ClobClient (5 methods)
+
+Public orderbook, prices (read-only with circuit breaker & rate limiting).
+
+```typescript
+import { ClobClient } from "@varla/polymarket";
+const clob = new ClobClient(config?: Partial<ClobClientConfig>);
+```
+
+| Method | Parameters | Returns |
+|--------|------------|---------|
+| `getMidpoint` | `tokenId: string` | `Promise<ClobMidpointResponse>` |
+| `getBook` | `tokenId: string` | `Promise<ClobBookResponse>` |
+| `getPricesHistory` | `{ tokenId, startTs, endTs, interval, fidelity? }` | `Promise<ClobPricesHistoryResponse>` |
+| `getMetrics` | — | `ClobClientMetrics` |
+| `getCircuitState` | — | `CircuitState` |
+| `resetCircuitBreaker` | — | `void` |
+
+---
+
+### ClobTradingClient (30 methods)
+
+Authenticated trading operations.
+
+```typescript
+import { ClobTradingClient } from "@varla/polymarket";
+const client = new ClobTradingClient(walletClient, config?: ClobTradingClientConfig);
+```
+
+| Method | Parameters | Returns |
+|--------|------------|---------|
+| **Initialization** | | |
+| `init` | — | `Promise<void>` |
+| `isInitialized` | — | `boolean` |
+| `getCredentials` | — | `ApiKeyCreds` |
+| `setCredentials` | `creds: ApiKeyCreds` | `void` |
+| **Orders** | | |
+| `createOrder` | `params: OrderParams, options: MarketOptions` | `Promise<SignedOrder>` |
+| `postOrder` | `signedOrder: SignedOrder, orderType?: OrderType` | `Promise<OrderResponse>` |
+| `createAndPostOrder` | `params: OrderParams, options: MarketOptions, orderType?: OrderType` | `Promise<OrderResponse>` |
+| `postOrders` | `signedOrders: SignedOrder[], orderType?: OrderType` | `Promise<BatchOrderResponse>` |
+| `createAndPostOrders` | `ordersParams: Array<{params, options}>, orderType?: OrderType` | `Promise<BatchOrderResponse>` |
+| `getOrder` | `orderId: string` | `Promise<Order>` |
+| `getOpenOrders` | `filter?: OpenOrdersFilter` | `Promise<Order[]>` |
+| **Market Orders** | | |
+| `marketBuy` | `params: MarketBuyParams, options: MarketOptions, timeInForce?: TimeInForce` | `Promise<OrderResponse>` |
+| `marketSell` | `params: MarketSellParams, options: MarketOptions, timeInForce?: TimeInForce` | `Promise<OrderResponse>` |
+| `getOrderBook` | `tokenId: string` | `Promise<OrderBook>` |
+| **Cancellation** | | |
+| `cancelOrder` | `orderId: string` | `Promise<CancelResponse>` |
+| `cancelOrders` | `orderIds: string[]` | `Promise<CancelResponse>` |
+| `cancelMarketOrders` | `{ market?, asset_id? }` | `Promise<CancelResponse>` |
+| `cancelAll` | — | `Promise<CancelResponse>` |
+| **Account** | | |
+| `getClosedOnlyMode` | — | `Promise<{ closedOnly: boolean; reason?: string }>` |
+| `getApiKeys` | — | `Promise<{ apiKeys: Array<{apiKey, createdAt}> }>` |
+| `deleteApiKey` | — | `Promise<void>` |
+| **Trades & History** | | |
+| `getTrades` | `filter?: TradeHistoryFilter` | `Promise<Trade[]>` |
+| `heartbeat` | — | `Promise<HeartbeatResponse>` |
+| **Rewards** | | |
+| `getEarningsForDay` | `date: string` | `Promise<UserEarnings>` |
+| `getTotalEarningsForDay` | `date: string` | `Promise<UserEarnings>` |
+| `getLiquidityRewardPercentages` | — | `Promise<LiquidityRewardPercentages>` |
+| `getRewardsMarkets` | — | `Promise<RewardsMarket[]>` |
+| **Builder API** | | |
+| `createBuilderApiKey` | — | `Promise<BuilderApiKey>` |
+| `getBuilderApiKeys` | — | `Promise<BuilderApiKeyInfo[]>` |
+| `revokeBuilderApiKey` | — | `Promise<void>` |
+| `getBuilderTrades` | `filter?: BuilderTradesFilter, cursor?: string` | `Promise<BuilderTradesResponse>` |
+
+---
+
+### DataApiClient (16 methods)
+
+Positions, trades, leaderboards, and analytics.
+
+```typescript
+import { DataApiClient } from "@varla/polymarket";
+const data = new DataApiClient(opts?: DataApiClientOpts);
+```
+
+| Method | Parameters | Returns |
+|--------|------------|---------|
+| **Positions** | | |
+| `getCurrentPositions` | `{ address, conditionId?, limit?, offset? }` | `Promise<DataPosition[]>` |
+| `getClosedPositions` | `{ address, limit?, offset? }` | `Promise<DataClosedPosition[]>` |
+| `getTotalPositionValue` | `address: string` | `Promise<DataPositionValue>` |
+| **Trades & Activity** | | |
+| `getTrades` | `{ address?, conditionId?, limit?, offset? }` | `Promise<DataTrade[]>` |
+| `getUserActivity` | `{ address, limit?, offset? }` | `Promise<DataActivity[]>` |
+| **Analytics** | | |
+| `getTopHolders` | `{ conditionId, outcomeIndex?, limit? }` | `Promise<DataTopHolder[]>` |
+| `getTraderLeaderboard` | `{ period?, category?, order?, limit?, offset? }` | `Promise<DataLeaderboardEntry[]>` |
+| `getOpenInterest` | `{ conditionId?, asset? }` | `Promise<DataOpenInterest>` |
+| `getLiveVolume` | `{ eventId?, conditionId? }` | `Promise<DataVolume>` |
+| **Pricing & Orderbook** | | |
+| `getPriceHistory` | `{ tokenId, interval?, startTs?, endTs?, fidelity? }` | `Promise<DataPriceHistory>` |
+| `getOrderBookSummary` | `tokenId: string` | `Promise<DataOrderBookSummary>` |
+| `getOrderBookSummaries` | `tokenIds: string[]` | `Promise<DataOrderBookSummary[]>` |
+| `getSpreads` | `tokenIds: string[]` | `Promise<DataSpread[]>` |
+| **Misc** | | |
+| `getTotalMarketsTraded` | `address: string` | `Promise<DataMarketsTraded>` |
+| `getAccountingSnapshot` | `address: string` | `Promise<Response>` |
+| `healthCheck` | — | `Promise<{ status: string }>` |
+
+---
+
+### BridgeClient (5 methods)
+
+Deposit/withdrawal through Relay bridge.
+
+```typescript
+import { BridgeClient } from "@varla/polymarket";
+const bridge = new BridgeClient(opts?: BridgeClientOpts);
+```
+
+| Method | Parameters | Returns |
+|--------|------------|---------|
+| `createDepositAddresses` | `{ userAddress, chain, asset? }` | `Promise<BridgeDepositAddress>` |
+| `createWithdrawalAddresses` | `{ userAddress, destinationAddress, chain, asset, amount }` | `Promise<BridgeWithdrawalAddress>` |
+| `getQuote` | `{ fromChain, toChain, fromAsset, toAsset, amount }` | `Promise<BridgeQuote>` |
+| `getSupportedAssets` | — | `Promise<BridgeSupportedAsset[]>` |
+| `getTransactionStatus` | `transactionId: string` | `Promise<BridgeTransactionStatus>` |
+
+---
+
+### ClobWsClient (7 methods)
+
+Real-time WebSocket updates.
+
+```typescript
+import { ClobWsClient } from "@varla/polymarket";
+const ws = new ClobWsClient(events?: ClobWsEvents, config?: ClobWsConfig);
+```
+
+| Method | Parameters | Returns |
+|--------|------------|---------|
+| `connect` | — | `void` |
+| `close` | — | `void` |
+| `subscribeMarket` | `market: string` | `void` |
+| `unsubscribeMarket` | `market: string` | `void` |
+| `subscribeMarkets` | `markets: string[]` | `void` |
+| `getState` | — | `ClobWsState` |
+| `isConnected` | — | `boolean` |
+| `getSubscribedMarkets` | — | `string[]` |
+
+---
+
 ## Key Patterns
 
 ### EIP712 Signing (Orders & Auth)
@@ -178,10 +387,12 @@ describe("Feature", () => {
 
 ### 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
+1. Add type to `src/types.ts` or `src/clob-trading-types.ts`
+2. Add method to appropriate client file
+3. Add unit test to `test/unit/`
+4. Add live test to `test/live/` (optional)
+5. Update `src/index.ts` exports if needed
+6. Update this AGENTS.md API reference
 
 ### Add New Config