Custom skills.

// Module 10: smart-buy.ts (a custom skill for your runtime LLM agent)
//
// Built on the official @limitless-exchange/sdk so it runs anywhere: no
// agents-starter clone required. Walks the asks, splits the requested USD
// across multiple GTC limit orders within a basis-point slippage budget,
// and returns a single JSON summary the LLM can act on.
//
// Verified against docs.limitless.exchange/developers/sdk/typescript/orders.

import { ethers } from 'ethers';
import {
  HttpClient,
  MarketFetcher,
  OrderClient,
  OrderType,
  Side,
} from '@limitless-exchange/sdk';
import 'dotenv/config';

const httpClient    = new HttpClient({
  baseURL: 'https://api.limitless.exchange',
  apiKey:  process.env.LIMITLESS_API_KEY,
});
const wallet        = new ethers.Wallet(process.env.PRIVATE_KEY!);
const marketFetcher = new MarketFetcher(httpClient);
const orderClient   = new OrderClient({ httpClient, wallet, marketFetcher });

export const smartBuyYesTool = {
  name:        'smart_buy_yes',
  description: 'Buy YES on a Limitless CLOB market with slippage control. Fetches the market and orderbook, walks the asks within a basis-point budget, splits the requested USD across multiple GTC limit orders. Use only when you already know the market_slug, prefer browse_markets to discover new ones. A mirror smart_buy_no skill targets the NO token.',
  input_schema: {
    type: 'object',
    properties: {
      market_slug:     { type: 'string' },
      target_size_usd: { type: 'number', minimum: 1 },
      max_slippage_bp: { type: 'number', default: 50, description: 'Max slippage in basis points (50 = 0.5%)' },
    },
    required: ['market_slug', 'target_size_usd'],
  },
} as const;

interface SmartBuyYesArgs {
  market_slug: string;
  target_size_usd: number;
  max_slippage_bp?: number;
}

export async function smartBuyYes(args: SmartBuyYesArgs): Promise<string> {
  const maxBp = args.max_slippage_bp ?? 50;

  // Fetch the market once. MarketFetcher caches venue + token IDs internally
  // so the OrderClient signing path stays fast across the split legs.
  const market = await marketFetcher.getMarket(args.market_slug);

  // OrderbookLevel: { price: number (0–1, probability), size: number (shares) }.
  const book = await marketFetcher.getOrderBook(args.market_slug);
  const levels = book.asks;
  if (!levels?.length) {
    return JSON.stringify({ ok: false, reason: 'empty asks' });
  }

  const refPrice   = levels[0].price;
  const worstPrice = refPrice * (1 + maxBp / 10_000);

  // Walk the asks. usd-at-level = price × shares.
  const plan: { price: number; shares: number }[] = [];
  let remainingUsd = args.target_size_usd;
  for (const lvl of levels) {
    if (remainingUsd <= 0) break;
    if (lvl.price > worstPrice) break;
    const usdAtLevel = lvl.price * lvl.size;
    const takeUsd    = Math.min(remainingUsd, usdAtLevel);
    plan.push({ price: lvl.price, shares: takeUsd / lvl.price });
    remainingUsd -= takeUsd;
  }

  if (plan.length === 0) {
    return JSON.stringify({ ok: false, reason: 'no liquidity within slippage budget', ref_price: refPrice });
  }

  // Each leg is a GTC limit order. OrderClient handles EIP-712 signing,
  // profile-id resolution, and venue caching.
  const results = await Promise.all(plan.map(p =>
    orderClient.createOrder({
      marketSlug: args.market_slug,
      tokenId:    market.positionIds[0],   // YES token
      side:       Side.BUY,
      price:      p.price,                 // probability 0–1 (NOT cents)
      size:       p.shares,                // number of shares
      orderType:  OrderType.GTC,
    })
  ));

  const filledUsd    = args.target_size_usd - remainingUsd;
  const filledShares = plan.reduce((s, p) => s + p.shares, 0);
  return JSON.stringify({
    ok:         true,
    filled_usd: filledUsd,
    unfilled:   remainingUsd,
    avg_price:  filledShares > 0 ? filledUsd / filledShares : 0,  // VWAP
    legs:       results.length,
    order_ids:  results.map(r => r.order.id),
  });
}

# Module 10: smart_buy.py (a custom skill for your runtime LLM agent)
#
# Async-first via the official limitless-sdk Python package.
# Verified against docs.limitless.exchange/developers/sdk/python/orders.

import asyncio
import json
import os
from typing import Any
from eth_account import Account
from limitless_sdk.api import HttpClient
from limitless_sdk.markets import MarketFetcher
from limitless_sdk.orders import OrderClient
from limitless_sdk.types import Side, OrderType

http_client    = HttpClient()  # auto-loads LIMITLESS_API_KEY from env
account        = Account.from_key(os.environ["PRIVATE_KEY"])
market_fetcher = MarketFetcher(http_client)
order_client   = OrderClient(http_client, account)

smart_buy_yes_tool: dict[str, Any] = {
    "type": "function",
    "function": {
        "name": "smart_buy_yes",
        "description": (
            "Buy YES on a Limitless CLOB market with slippage control. Fetches "
            "the market and orderbook, walks the asks within a basis-point "
            "budget, splits the requested USD across multiple GTC limit "
            "orders. Use only when you already know the market_slug: prefer "
            "browse_markets to discover new ones."
        ),
        "parameters": {
            "type": "object",
            "properties": {
                "market_slug":     {"type": "string"},
                "target_size_usd": {"type": "number", "minimum": 1},
                "max_slippage_bp": {"type": "number", "default": 50,
                                   "description": "Max slippage in basis points (50 = 0.5%)"},
            },
            "required": ["market_slug", "target_size_usd"],
        },
    },
}


async def smart_buy_yes(
    market_slug:     str,
    target_size_usd: float,
    max_slippage_bp: float = 50,
) -> str:
    # Fetch the market once. MarketFetcher caches venue + token IDs.
    market = await market_fetcher.get_market(market_slug)

    # Orderbook level: { price: float (0–1), size: float (shares) }
    book   = await market_fetcher.get_order_book(market_slug)
    levels = book.asks
    if not levels:
        return json.dumps({"ok": False, "reason": "empty asks"})

    ref_price   = levels[0].price
    worst_price = ref_price * (1 + max_slippage_bp / 10_000)

    # Walk the asks. usd-at-level = price × shares.
    plan: list[tuple[float, float]] = []  # [(price, shares), ...]
    remaining_usd = target_size_usd
    for lvl in levels:
        if remaining_usd <= 0:
            break
        if lvl.price > worst_price:
            break
        usd_at_level = lvl.price * lvl.size
        take_usd     = min(remaining_usd, usd_at_level)
        plan.append((lvl.price, take_usd / lvl.price))
        remaining_usd -= take_usd

    if not plan:
        return json.dumps({"ok": False, "reason": "no liquidity within slippage budget",
                           "ref_price": ref_price})

    # Each leg is a GTC BUY on the YES token.
    receipts = await asyncio.gather(*[
        order_client.create_order(
            token_id    = market.tokens.yes,
            price       = price,
            size        = shares,
            side        = Side.BUY,
            order_type  = OrderType.GTC,
            market_slug = market_slug,
        )
        for price, shares in plan
    ])

    filled_usd    = target_size_usd - remaining_usd
    filled_shares = sum(shares for _, shares in plan)
    return json.dumps({
        "ok":         True,
        "filled_usd": filled_usd,
        "unfilled":   remaining_usd,
        "avg_price":  filled_usd / filled_shares if filled_shares > 0 else 0,  # VWAP
        "legs":       len(receipts),
    })