shreed27/execution

Execution Service - Complete API Reference

Execute trades on Polymarket and Kalshi with slippage protection, maker orders, and order management.

Supported Platforms

| Platform | Order Types | Features | |----------|-------------|----------| | Polymarket | Limit, Market, Maker | -0.5% maker rebate, GTC/FOK | | Kalshi | Limit, Market | US regulated |

---

Chat Commands

Place Orders

/execute buy poly <market> YES 100 @ 0.52   # Limit buy on Polymarket
/execute sell kalshi <market> NO 50 @ 0.48  # Limit sell on Kalshi
/execute market-buy poly <market> YES 100   # Market buy
/execute market-sell poly <market> NO 50    # Market sell

Maker Orders (Rebates)

/execute maker-buy poly <market> YES 100 @ 0.52   # Post-only buy
/execute maker-sell poly <market> NO 50 @ 0.48    # Post-only sell

Protected Orders (Slippage Protection)

/execute protected-buy poly <market> YES 100 --max-slippage 1%
/execute protected-sell poly <market> NO 50 --max-slippage 0.5%

Order Management

/orders open                                # View open orders
/orders open poly                           # Open orders on Polymarket
/orders cancel <order-id>                   # Cancel specific order
/orders cancel-all                          # Cancel all open orders
/orders cancel-all poly                     # Cancel all on Polymarket

Slippage Estimation

/estimate-slippage poly <market> buy 1000   # Estimate slippage for $1000 buy
/estimate-slippage kalshi <market> sell 500 # Estimate for $500 sell

---

TypeScript API Reference

Create Execution Service

import { createExecutionService } from 'clodds/execution';

const executor = createExecutionService({
  polymarket: {
    apiKey: process.env.POLY_API_KEY,
    apiSecret: process.env.POLY_API_SECRET,
    passphrase: process.env.POLY_API_PASSPHRASE,
    privateKey: process.env.PRIVATE_KEY,
  },
  kalshi: {
    apiKey: process.env.KALSHI_API_KEY,
    privateKey: process.env.KALSHI_PRIVATE_KEY,
  },

  // Defaults
  defaultSlippageTolerance: 0.5,  // 0.5%
  autoLogTrades: true,
});

Limit Orders

// Buy limit order
const order = await executor.buyLimit({
  platform: 'polymarket',
  marketId: 'market-123',
  side: 'YES',
  size: 100,           // $100
  price: 0.52,         // 52 cents
  timeInForce: 'GTC',  // Good-til-cancel
});

console.log(`Order placed: ${order.orderId}`);
console.log(`Status: ${order.status}`);

// Sell limit order
const sellOrder = await executor.sellLimit({
  platform: 'polymarket',
  marketId: 'market-123',
  side: 'YES',
  size: 100,
  price: 0.55,
});

Market Orders

// Market buy - executes immediately at best price
const order = await executor.marketBuy({
  platform: 'polymarket',
  marketId: 'market-123',
  side: 'YES',
  size: 100,
});

console.log(`Filled at: ${order.avgFillPrice}`);
console.log(`Filled size: ${order.filledSize}`);

// Market sell
const sellOrder = await executor.marketSell({
  platform: 'kalshi',
  marketId: 'TRUMP-WIN',
  side: 'YES',
  size: 50,
});

Maker Orders (Post-Only)

// Maker buy - only executes as maker (gets rebate)
const order = await executor.makerBuy({
  platform: 'polymarket',
  marketId: 'market-123',
  side: 'YES',
  size: 100,
  price: 0.52,
});

// Will be rejected if it would execute immediately as taker
if (order.status === 'rejected') {
  console.log('Price too aggressive - would be taker');
}

// Maker sell
const sellOrder = await executor.makerSell({
  platform: 'polymarket',
  marketId: 'market-123',
  side: 'NO',
  size: 50,
  price: 0.48,
});

Protected Orders (Slippage Protection)

// Protected buy - checks slippage before executing
const order = await executor.protectedBuy({
  platform: 'polymarket',
  marketId: 'market-123',
  side: 'YES',
  size: 100,
  maxSlippage: 0.5,  // 0.5% max slippage
});

if (order.status === 'rejected') {
  console.log(`Rejected: slippage would be ${order.estimatedSlippage}%`);
} else {
  console.log(`Executed with ${order.actualSlippage}% slippage`);
}

// Protected sell
const sellOrder = await executor.protectedSell({
  platform: 'kalshi',
  marketId: 'TRUMP-WIN',
  side: 'YES',
  size: 50,
  maxSlippage: 1,
});

Order Management

// Cancel specific order
await executor.cancelOrder('polymarket', orderId);

// Cancel all orders on platform
await executor.cancelAllOrders('polymarket');

// Cancel all orders for a market
await executor.cancelAllOrders('polymarket', { marketId: 'market-123' });

// Get open orders
const openOrders = await executor.getOpenOrders('polymarket');

for (const order of openOrders) {
  console.log(`${order.orderId}: ${order.side} ${order.size} @ ${order.price}`);
  console.log(`  Status: ${order.status}`);
  console.log(`  Filled: ${order.filledSize}/${order.size}`);
}

Slippage Estimation

// Estimate slippage before executing
const estimate = await executor.estimateSlippage({
  platform: 'polymarket',
  marketId: 'market-123',
  side: 'buy',
  size: 1000,
});

console.log(`For $1000 buy:`);
console.log(`  Avg fill price: ${estimate.avgFillPrice}`);
console.log(`  Expected slippage: ${estimate.slippagePct}%`);
console.log(`  Total filled: ${estimate.totalFilled}`);
console.log(`  Levels consumed: ${estimate.levelsConsumed}`);

---

Order Types

| Type | Description | Best For | |------|-------------|----------| | Limit | Execute at specific price or better | Price-sensitive orders | | Market | Execute immediately at best available | Urgent execution | | Maker | Post-only, gets rebate | Collecting rebates | | Protected | Checks slippage before executing | Large orders |

Time In Force

| Value | Description | |-------|-------------| | GTC | Good-til-cancel (default) | | FOK | Fill-or-kill - all or nothing | | IOC | Immediate-or-cancel - fill what you can |

---

Fee Structure

Polymarket (Verified Jan 2026)

• Most markets: 0% maker, 0% taker (zero fees)
• 15-min crypto markets: Dynamic taker fees up to ~3% at 50/50 odds; makers eligible for rebate program

Kalshi

• Taker: Formula-based ~1.2% average, capped at ~2%
• Maker: ~0.17% (formula-based)

---

Best Practices

1. Use maker orders when possible - Pay no fees on Polymarket (most markets)
2. Check slippage before large orders
3. Use protected orders for size > $500
4. Set appropriate timeInForce - GTC for patient orders, FOK for all-or-nothing
5. Monitor open orders - Cancel stale orders
6. Start small - Test with small sizes first