@vaultlayer/vincent-ability-polymarket

A Vincent Ability for interacting with Polymarket prediction markets on Polygon. This ability supports USDC.e approval, placing orders (buy/sell), canceling orders, and redeeming positions.

Overview

This ability enables users to interact with Polymarket's decentralized prediction markets through the Vincent system. It supports all main operations:

• Approve: Approve USDC.e spending for the Polymarket Exchange contract
• Place Order: Create and submit buy/sell orders to Polymarket's CLOB (Central Limit Order Book)
• Cancel Order: Cancel existing orders (single or batch)
• Redeem Positions: Redeem winning conditional tokens for collateral after market resolution

Prerequisites

• Funds must already be on Polygon as USDC.e
• The ability assumes the user's PKP wallet has USDC.e balance for trading

Installation

pnpm add @vaultlayer/vincent-ability-polymarket

Configuration

The ability uses the following Polygon addresses:

• USDC.e: 0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174
• CTF Exchange: 0x4bFb41d5B3570DeFd03C39a9A4D8dE6Bd8B8982E
• Neg Risk CTF Exchange: 0xC5d563A36AE78145C45a50134d48A1215220f80a
• CTF Contract: 0x4D97DCd97eC945f40cF65F87097ACe5EA0476045
• Chain ID: 137 (Polygon Mainnet)

Usage

1. Approve USDC.e

Approve USDC.e spending for the Exchange contract:

import { PolymarketOperation } from '@vaultlayer/vincent-ability-polymarket';

const abilityParams = {
  operation: PolymarketOperation.APPROVE,
  amount: '1000000', // Amount in smallest unit (6 decimals), optional - defaults to max if not provided
  spender: '0x4bFb41d5B3570DeFd03C39a9A4D8dE6Bd8B8982E', // Optional - defaults to CTF Exchange
  rpcUrl: 'https://polygon-rpc.com', // Optional
};

2. Place Order

Place a buy or sell order on Polymarket:

import { PolymarketOperation, OrderSide, OrderType } from '@vaultlayer/vincent-ability-polymarket';

// Buy order example
const buyOrderParams = {
  operation: PolymarketOperation.PLACE_ORDER,
  tokenId: '71321045679252212594626385532706912750332728571942532289631379312455583992563', // ERC1155 token ID
  side: OrderSide.BUY,
  price: 0.5, // Price per share (0-1 range)
  size: 100, // Order size in dollars for BUY orders
  orderType: OrderType.GTC, // Good-Til-Cancelled
  feeRateBps: 0, // Fee rate in basis points
  nonce: 0, // Exchange nonce (optional)
  rpcUrl: 'https://polygon-rpc.com', // Optional
};

// Sell order example
const sellOrderParams = {
  operation: PolymarketOperation.PLACE_ORDER,
  tokenId: '71321045679252212594626385532706912750332728571942532289631379312455583992563',
  side: OrderSide.SELL,
  price: 0.6,
  size: 50, // Order size in shares for SELL orders
  orderType: OrderType.GTC,
  feeRateBps: 0,
  rpcUrl: 'https://polygon-rpc.com',
};

// GTD (Good-Til-Date) order example
const gtdOrderParams = {
  operation: PolymarketOperation.PLACE_ORDER,
  tokenId: '71321045679252212594626385532706912750332728571942532289631379312455583992563',
  side: OrderSide.BUY,
  price: 0.5,
  size: 100,
  orderType: OrderType.GTD,
  expiration: Math.floor(Date.now() / 1000) + 3600, // Unix timestamp (1 hour from now)
  feeRateBps: 0,
  rpcUrl: 'https://polygon-rpc.com',
};

Order Types:

• GTC (Good-Til-Cancelled): Order remains active until filled or cancelled
• GTD (Good-Til-Date): Order expires at the specified timestamp
• FOK (Fill-Or-Kill): Order must be filled immediately in its entirety or cancelled
• FAK (Fill-And-Kill): Order fills as much as possible immediately, remaining portion is cancelled

3. Cancel Order

Cancel one or more orders:

// Cancel single order
const cancelSingleParams = {
  operation: PolymarketOperation.CANCEL_ORDER,
  orderId: '0x1234...',
  rpcUrl: 'https://polygon-rpc.com', // Optional
};

// Cancel multiple orders (batch)
const cancelBatchParams = {
  operation: PolymarketOperation.CANCEL_ORDER,
  orderIds: ['0x1234...', '0x5678...', '0x9abc...'],
  rpcUrl: 'https://polygon-rpc.com', // Optional
};

Note: Cancel operations require CLOB API key authentication. The ability prepares the cancellation request, but API key headers need to be added by the calling code.

4. Redeem Positions

Redeem winning conditional tokens for collateral after market resolution:

const redeemParams = {
  operation: PolymarketOperation.REDEEM_POSITIONS,
  conditionId: '0x1234...', // Condition ID of the market
  indexSets: [1], // Array of index sets (outcome indices), typically [1] for YES or [2] for NO
  collateralToken: '0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174', // Optional - defaults to USDC.e
  parentCollectionId: '0x0000000000000000000000000000000000000000000000000000000000000000', // Optional - defaults to bytes32(0)
  rpcUrl: 'https://polygon-rpc.com', // Optional
};

Response Schemas

Precheck Success

{
  operationValid: boolean;
  chainValid: boolean;
  balance?: string; // Current balance without decimals
  allowance?: string; // Current allowance without decimals
  estimatedGas?: string; // Estimated gas cost
  orderExists?: boolean; // For cancel operations
  canRedeem?: boolean; // For redeem operations
}

Execute Success

{
  txHash?: string; // Transaction hash for on-chain operations
  orderId?: string; // Order ID from CLOB API (for place_order)
  orderHashes?: string[]; // Transaction hashes if order was immediately matched
  approvalTxHash?: string; // Approval transaction hash if one was needed
  operation: PolymarketOperation;
  cancelledOrderIds?: string[]; // For cancel operations
}

Important Notes

EIP-712 Order Signing

The PLACE_ORDER operation uses EIP-712 signing for order creation. The signature is generated using Lit Actions' PKP signing capabilities. The signature will be available in the Lit SDK response and needs to be extracted and included when submitting the order to the CLOB API.

Current Limitation: The ability initiates the EIP-712 signing process, but the actual signature extraction and CLOB API submission requires additional implementation to handle the Lit SDK response properly.

API Key Authentication

Cancel order operations and order placement require CLOB API key authentication. The ability prepares the requests, but API key headers (POLY_ADDRESS, POLY_SIGNATURE, POLY_TIMESTAMP, POLY_API_KEY, POLY_PASSPHRASE) need to be added by the calling code or handled through a separate authentication mechanism.

Order Amounts

• BUY orders: size is in dollars (USDC.e), makerAmount is calculated as price * size in USDC.e (6 decimals), takerAmount is in shares (18 decimals)
• SELL orders: size is in shares, makerAmount is in shares (18 decimals), takerAmount is calculated as price * size in USDC.e (6 decimals)

Development

Build

pnpm nx build ability-polymarket

Deploy to IPFS

pnpm nx action:deploy ability-polymarket

Test

pnpm test ability-polymarket

References

• Polymarket Documentation
• Polymarket CLOB API
• Conditional Token Framework

License

See the main repository license.