> ## Documentation Index
> Fetch the complete documentation index at: https://docs.limitless.exchange/llms.txt
> Use this file to discover all available pages before exploring further.

# Build a trading agent

> Open-source TypeScript template for autonomous trading agents on Limitless — fork it, configure a strategy, and ship a bot in minutes

[**agents-starter**](https://github.com/limitless-labs-group/agents-starter) is the canonical end-to-end starter for building an autonomous trading agent on Limitless. Fork it, set two env vars, and run a strategy in DRY\_RUN within five minutes.

<Info>
  This is for **individual traders, builders, and AI agents** who want a working code template, not a partner integration. If you're building a platform where other users trade through your product, see [Programmatic API](/developers/programmatic-api) instead.
</Info>

## What's included

agents-starter is a small TypeScript project. It uses the official [`@limitless-exchange/sdk`](/developers/sdk/typescript/getting-started) for order placement, market data, and websocket streaming, plus a few hand-rolled helpers (Pyth price feed, Polymarket adapter, diagnostics) that aren't in the SDK.

| File                  | What it does                                                                                                                                                       |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `src/strategies/`     | Three strategies: **cross-market-mm** (flagship — see [Cross-market market making](/developers/cross-market-market-making)), **oracle-arb**, **certainty-closer**. |
| `src/core/limitless/` | Thin wrappers over the SDK + utilities the strategies share.                                                                                                       |
| `src/core/kelly.ts`   | Fractional-Kelly position-sizing util.                                                                                                                             |
| `src/scripts/`        | One-shot diagnostic scripts (balance check, orderbook inspector).                                                                                                  |
| `SKILL.md`            | OpenClaw / Claude Code skill manifest — agents can read it and run the bot end-to-end.                                                                             |

## 5-minute setup

<Warning>
  Generate a **dedicated** wallet for this bot. Fund it with only what you're prepared to lose. Do not use your main wallet.
</Warning>

```bash theme={null}
git clone https://github.com/limitless-labs-group/agents-starter.git
cd agents-starter
npm install

cp .env.example .env
chmod 600 .env
# Edit .env, fill in PRIVATE_KEY (your dedicated wallet) + a Limitless scoped HMAC token
```

Get your scoped HMAC token from the Limitless UI (see [Authentication](/developers/authentication)):

1. [limitless.exchange](https://limitless.exchange) → Connect wallet
2. API token modal → **API Tokens** tab → Derive
3. Copy the `tokenId` + `secret` into `.env` as `LMTS_TOKEN_ID` + `LMTS_TOKEN_SECRET`

## Run a strategy

Always start with `DRY_RUN=true` in `.env` — every order intent is logged but nothing signs or posts.

```bash theme={null}
# Dry run (no real trades)
DRY_RUN=true npm run oracle-arb

# Live trading once you're satisfied with the dry-run log
DRY_RUN=false npm run oracle-arb
```

<Note>
  Use a small `usdAmount` for your first live runs (start at $2-$5 per order). Strategies are conservative by default but no bot is bug-free.
</Note>

## Built-in strategies

Each strategy is an entry point — pick one or fork it.

### `cross-market-mm` (flagship)

Cross-venue market making: quote on Limitless, hedge fills on Polymarket to stay delta-neutral. Earns the cross-venue spread plus Limitless maker rebates + LP rewards. It has its own full guide — see [**Cross-market market making**](/developers/cross-market-market-making).

```bash theme={null}
npm run cross-market-mm            # dry-run by default
```

### `oracle-arb`

Cross-references a Pyth (Hermes SSE) oracle price against Limitless markets that resolve on the same underlying. Submits FOK/FAK orders when the implied probability strays far enough from the oracle to cover fees + slippage. The price-feed / edge-detection archetype.

```bash theme={null}
npm run oracle-arb
```

### `certainty-closer`

The simplest on-ramp — SDK-only, no external feeds. Filters markets near resolution and buys the favourite, sized via fractional Kelly (`src/core/kelly.ts`). Honestly framed: on its own it has no independent edge (the edge is one you assert); it's the cleanest example of the market-filter → decide → execute loop.

```bash theme={null}
npm run certainty-closer
```

## Bring your own strategy

The example strategies (`oracle-arb`, `certainty-closer`) extend `BaseStrategy` (`src/strategies/base-strategy.ts`); the flagship `cross-market-mm` has its own runtime loop. To build one on `BaseStrategy`:

1. Implement `tick()` — return a list of `TradeDecision`s based on whatever signal you care about.
2. Implement `initialize()` / `shutdown()` for setup + teardown.
3. The base class runs the tick loop and handles order placement + DRY\_RUN gating.

```typescript theme={null}
import { BaseStrategy } from './base-strategy.js';

export class MyStrategy extends BaseStrategy {
  async scan() {
    // your edge logic — return TradeDecision[]
  }

  async shouldExit() {
    // your exit logic — return positions to close
  }
}
```

Create a `run.ts` next to it that wires up the runtime, and add an entry to `package.json` scripts.

## Under the hood

agents-starter uses the official [`@limitless-exchange/sdk`](/developers/sdk/typescript/getting-started) for everything order-related. The signing path is [EIP-712](/developers/eip712-signing); the SDK handles venue-specific routing (default CTF vs neg-risk exchange) automatically based on the market metadata.

<Note>
  **Taker delay.** Some markets apply a short hold to marketable (taker) orders — the FOK/FAK orders strategies like `oracle-arb` submit — before the matching engine fills them. On such a market, order submission is asynchronous: the create-order response comes back with `settlementStatus: "DELAYED"` and an `eligibleAt` timestamp rather than a finished fill, and the actual fill arrives later over the order-events websocket (provisional `MATCHED` → terminal `MINED` / `FAILED`). Observe the fill on that stream — don't treat the `DELAYED` response or the gap before the fill as an error. If maintenance mode is active when `eligibleAt` passes, the fill may be postponed until trading is available again. `postOnly` maker quotes are never delayed. See [WebSocket Events](/developers/websocket-events#subscribing-to-order-events) and [Maintenance Mode](/developers/maintenance-mode).
</Note>

For background on the protocol layers the agent is interacting with, see:

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/developers/authentication">
    API tokens, HMAC scoping, and which auth mode to use for which flow.
  </Card>

  <Card title="EIP-712 signing" icon="signature" href="/developers/eip712-signing">
    The exact typed-data structure your wallet signs to place an order.
  </Card>

  <Card title="Venue system" icon="server" href="/developers/venue-system">
    Default CTF vs neg-risk exchange routing and why it matters.
  </Card>

  <Card title="WebSocket events" icon="bolt" href="/developers/websocket-events">
    Real-time price + fill + portfolio updates.
  </Card>
</CardGroup>

## AI agent operation

`SKILL.md` in the repo is the operating manual for an AI agent. Feed it to Claude Code, OpenClaw, or any coding agent with shell + file access. The agent handles:

* Environment + dependency setup
* Wallet configuration
* Strategy selection based on what you ask
* Deployment + monitoring + iteration

The manual covers SDK reference, partner integration flows, error handling, and known footguns — designed to remove the back-and-forth of "what API do I call for X?"

## What's next

Recently shipped, and on the roadmap:

* **[Cross-market market making](/developers/cross-market-market-making)** — the `replicator` strategy mirrors a Polymarket book onto Limitless as resting quotes and hedges fills back on Polymarket to stay delta-neutral. Earns the spread + Limitless maker rebates.
* Inline tutorial prompts so a fresh agent run starts with "which strategy do you want?"
* Per-strategy backtesting against historical fill data.

## Support

* Builders Chat: [t.me/LimitlessBuildersChat](https://t.me/LimitlessBuildersChat) — Telegram community for API/SDK builders
* Repo issues: [github.com/limitless-labs-group/agents-starter/issues](https://github.com/limitless-labs-group/agents-starter/issues)
* Live MCP docs server for AI agents: `https://docs.limitless.exchange/mcp`
* SDK reference: [TypeScript SDK guide](/developers/sdk/typescript/getting-started)