PolymarketService

PolymarketService is a direct HTTP client for the Polymarket CLOB endpoints exposed by the ILLA gateway. Reach it through the sdk.polymarket getter when you want to place, cancel, read, redeem, or withdraw imperatively — without going through the agent and the chat/tool loop. The instance is created lazily on first access and reused for the lifetime of the SDK instance.

import { IllaSDK } from '@illalabs/sdk'

const sdk = new IllaSDK({ apiKey: process.env.ILLA_API_KEY! })

const polymarket = sdk.polymarket // PolymarketService (lazy, cached)

You can pass a polymarket block to the IllaSDK constructor config to override the base URL, timeout, headers, or route paths for this service.

Authentication model

At the ILLA edge these routes pass the same gateway authentication as every other endpoint — an OAuth session bearer or an x-api-key (the SDK supplies the apiKey you configured). Inside the API there is no additional user-session binding for these routes; Polymarket-level authentication happens at the protocol level via a signed authData object passed in the request body — obtain it (and the order signature) beforehand by signing with POST /api/v1/signatures/sign.

authData is { signature, timestamp, nonce, address } (all strings); getOrders in particular requires auth data signed immediately before the call.

Methods

// Each method POSTs to a Polymarket route on the ILLA gateway and resolves to a PolymarketResult.
postOrder(body: PolymarketPostOrderBody, options?):
  Promise<PolymarketResult<PolymarketPostOrderSuccessResponse>>      // /api/v1/polymarket/post-order
postRedeem(body: PolymarketPostRedeemBody, options?):
  Promise<PolymarketResult<PolymarketSafeExecuteSuccessResponse>>    // /api/v1/polymarket/post-redeem
postWithdraw(body: PolymarketPostWithdrawBody, options?):
  Promise<PolymarketResult<PolymarketSafeExecuteSuccessResponse>>    // /api/v1/polymarket/post-withdraw
getOrders(body: PolymarketGetOrdersBody, options?):
  Promise<PolymarketResult<PolymarketGetOrdersSuccessResponse>>      // /api/v1/polymarket/get-orders
cancelOrder(body: PolymarketCancelOrderBody, options?):
  Promise<PolymarketResult<PolymarketCancelOrderSuccessResponse>>    // /api/v1/polymarket/cancel-order
getRoutes(): PolymarketRoutes

options is { signal?: AbortSignal }. postRedeem and postWithdraw submit signed Safe or deposit-wallet operations to the Polymarket relayer; both resolve to a PolymarketSafeExecuteSuccessResponse.

`PolymarketResult` envelope

Every method resolves to a discriminated result rather than throwing on request failure:

type PolymarketResult<T> =
  | { isError: false; data: T }
  | { isError: true; error: PolymarketErrorResponse }

PolymarketErrorResponse is a union of a validation error ({ name: 'PolymarketInvalidParams', statusCode: 400, details.validationErrors[] }) and an action error ({ success: false, error: string }).

const result = await sdk.polymarket.postOrder({
  order: signedOrder,
  signature: orderSignature,
  authData: { signature, timestamp, nonce, address },
  // optional: additionalSignatures, orderType ('GTC' | 'GTD' | 'FOK')
})

if (result.isError) {
  console.error(result.error) // PolymarketErrorResponse
} else {
  console.log('Order placed:', result.data.orderId, result.data.status)
}

Routing by action

routePolymarketAction dispatches a single tagged request to the matching PolymarketService method. sdk.postPolymarketAction(request, options) is the built-in facade shortcut that routes against sdk.polymarket.

routePolymarketAction(
  service: PolymarketService,
  request: PolymarketActionRequest,
  options?: PolymarketRequestOptions,
): Promise<PolymarketResult<PolymarketActionSuccessResponse>>

PolymarketActionRequest is a discriminated union on action:

`action`	Method
`polymarketPostOrder`	`postOrder`
`polymarketPostRedeem`	`postRedeem`
`polymarketPostWithdraw`	`postWithdraw`
`polymarketPostGetOrders`	`getOrders`
`polymarketPostCancelOrder`	`cancelOrder`

The polymarketAuth action is intentionally excluded — it is handled client-side and has no server endpoint.

import { IllaSDK, routePolymarketAction } from '@illalabs/sdk'
import type { PolymarketActionRequest } from '@illalabs/sdk'

const sdk = new IllaSDK({ apiKey: process.env.ILLA_API_KEY! })

const request: PolymarketActionRequest = {
  action: 'polymarketPostCancelOrder',
  body: { authData, orderId: '0xorder...' },
}

// Facade shortcut:
const result = await sdk.postPolymarketAction(request)

// ...or route against any PolymarketService instance directly:
// const result = await routePolymarketAction(sdk.polymarket, request)

if (result.isError) {
  console.error(result.error)
} else {
  console.log('Success:', result.data) // PolymarketActionSuccessResponse
}