@orch8.io/polymarket-worker

Polymarket V2 CLOB connector for the Orch8 workflow engine. Enables prediction market trading through declarative workflow tasks.

What is Orch8?

Orch8 is a durable workflow engine that orchestrates multi-step, long-running processes across workers. This package provides a worker that connects to the Orch8 engine and exposes Polymarket trading operations as declarative tasks. You can use it standalone (programmatically via PolymarketClient) or as part of an Orch8 workflow.

Setup

pnpm install
pnpm build

Environment Variables

Variable	Required	Default	Description
ORCH8_URL	No	http://localhost:8080	Orch8 engine URL
HOSTNAME	No	local	Worker instance identifier
POLYMARKET_CLOB_URL	No	https://clob.polymarket.com	Override CLOB API base URL

Running

pnpm start

The worker connects to the Orch8 engine and polls for tasks matching its registered handler names. It runs up to 50 concurrent tasks.

Handlers

All handlers receive a WorkerTask from the Orch8 engine with params and context fields.

Handler	Description	Required Params	Required Context
poly_create_api_key	Derive API credentials from a private key	private_key	-
poly_place_order	Place a limit order on Polymarket	token_id, side, size, price, order_type	private_key, api_credentials
poly_cancel_order	Cancel an existing order	order_id	api_credentials
poly_cancel_all_orders	Cancel all open orders	-	api_credentials
poly_get_order	Get order status and fill details	order_id	-
poly_get_orders	List open orders	-	api_credentials
poly_get_orderbook	Get orderbook with spread/mid-price	token_id	-
poly_get_positions	Get account positions	account_address	-
poly_get_market	Get market details and token prices	market_id	-
poly_get_price	Get current token price	token_id	-
poly_get_trades	Get trade history for a token	token_id	api_credentials
poly_get_balance	Get balance and allowance	address (optional)	api_credentials
poly_get_midpoint	Get midpoint price	token_id	-
poly_get_spread	Get bid-ask spread	token_id	-
poly_get_tick_size	Get market tick size	token_id	-
poly_get_neg_risk	Check negative risk flag	token_id	-

Context Fields

Some handlers require secrets passed via workflow context (not params):

// api_credentials — required for authenticated endpoints
{
  api_key: string;
  api_secret: string;     // base64-encoded
  api_passphrase: string;
}

// private_key — required for order signing
"0x..."  // Ethereum private key (hex)

Handler Details

poly_create_api_key

Derives Polymarket API credentials by signing an EIP-712 message with the provided private key.

{ "private_key": "0xabc..." }

Returns: { api_key, api_secret, api_passphrase }

poly_place_order

Places a limit order. Signs the order using EIP-712 typed data and submits via HMAC-authenticated endpoint.

{
  "token_id": "12345",
  "side": "BUY",
  "size": "10",
  "price": "0.55",
  "order_type": "GTC",
  "expiration": 1735689600,
  "builder_code": "optional-builder"
}

Order types: GTC (good-til-cancelled), GTD (good-til-date, requires expiration), FOK (fill-or-kill).

Returns: { order_id, status, size_matched, price, timestamp, transaction_hash? }

Error Handling

All handlers throw PolymarketError with structured error information:

Code	Status	Retryable	Description
INSUFFICIENT_BALANCE	400	No	Not enough funds
ORDER_TOO_SMALL	400	No	Below minimum order size
INVALID_SIGNATURE	400	No	EIP-712 signature invalid
ORDER_EXPIRED	400	No	Order past expiration
BAD_REQUEST	400	No	Generic client error
UNAUTHORIZED	401	No	Invalid API credentials
FORBIDDEN	403	No	API key revoked
NOT_FOUND	404	No	Resource not found
CONFLICT	409	No	Order already exists
RATE_LIMITED	429	Yes	Back off and retry
SERVER_ERROR	5xx	Yes	Polymarket server error

The Orch8 engine uses the retryable flag to decide whether to retry failed tasks.

Example Workflow

A typical trading workflow using these handlers:

1. poly_create_api_key     → derive credentials
2. poly_get_market          → find token IDs and prices
3. poly_get_orderbook       → check liquidity and spread
4. poly_place_order         → submit order
5. poly_get_order           → poll for fill status
6. poly_get_price           → monitor position (in loop)

Architecture

Orch8 Engine ←→ polymarket-worker ←→ Polymarket CLOB API
                     │
                     ├── handlers/     (17 task handlers)
                     ├── client.ts     (API client, signing, HMAC auth)
                     └── types.ts      (EIP-712 constants, interfaces)

• Handlers validate params/context and delegate to PolymarketClient
• PolymarketClient handles API calls, EIP-712 order signing, and HMAC authentication
• Error classification maps HTTP status codes to structured PolymarketError with retry semantics

Testing

pnpm test
pnpm test:watch

Test Suite Overview

This package is tested as part of the full Orch8 stack:

Layer	Tests	Scope
Rust unit + integration	1,255	Storage backends, evaluator, scheduler, handlers, config parsing, state machine transitions, gRPC auth, full engine integration
TypeScript E2E	773	202 test files hitting the live HTTP API — sequences, instances, workers, cron, triggers, webhooks, approvals, sessions, plugins, credentials, pools, cluster, SSE streaming

Polymarket-worker exact test count — 109 total

Suite	Tests	Focus
types.test.ts	9	Constants, error types, EIP-712 schemas
client.test.ts	47	HTTP client, retry logic, HMAC auth, error classification, all API methods
handlers.test.ts	47	Param validation, context checks, handler-to-client delegation
integration.test.ts	6	End-to-end workflows, cross-handler error propagation, full trading flows

Total: 109 tests — verified via vitest run.

License

BUSL-1.1