prediction-market-arbitrage v1.0.1A

Immutable. This exact content never changes and is served at /api/v1/blob/ddb2adcbd5a70d4a.

---
name: prediction-market-arbitrage
description: Find and analyze arbitrage opportunities across prediction markets like Polymarket and Kalshi.
license: MIT
compatibility: Works with any agentskills.io-compatible harness — Claude Code, Claude, OpenCode, Cursor, Codex, Gemini CLI, OpenClaw, Hermes, Goose, and others. Requires Python 3, a POSIX shell, and AISA_API_KEY.
metadata:
  version: "1.0.1"
  aisa:
    emoji: ⚖️
    homepage: https://aisa.one
    requires:
      bins:
      - curl
      - python3
      env:
      - AISA_API_KEY
    primaryEnv: AISA_API_KEY
    harnesses:
    - claude-code
    - claude
    - opencode
    - cursor
    - codex
    - gemini-cli
    - openclaw
    - hermes
    - goose
---
# Cross-Platform Prediction Market Arbitrage ⚖️

<!-- aisa-rules:start -->
## AIsa agent rules (shared)

<!-- Generated from _shared/aisa-rules.md by scripts/sync_shared_rules.py. Do not edit this block in place. -->

These rules apply to every AIsa-backed skill and are copied from https://aisa.one/llms.txt, the single authoritative agent rule source. When this block and the rest of this skill disagree, follow this block.

### Connect (MCP first)

Pick the first option that applies. Run the command yourself; the user only approves the browser sign-in.

- **A. Your client supports remote MCP and can open a browser (default).** Add a remote MCP server named `AIsa` with URL `https://mcp.aisa.one/mcp` (Streamable HTTP), using your client's own command or config file. Auth: browser OAuth, no key needed. In a chat app (Claude, ChatGPT), the user adds it as a custom connector in settings. Adding the server does not always start sign-in. If no sign-in window opens, start it from the client's own MCP authentication entry (a menu, command, or connector button); if only the user can reach that entry, tell them where it is. Sign-in is the slow step, not the API. Before it starts, tell the user in one line that an AIsa sign-in window or card is about to open and to click **Allow** (one click if the browser is already signed in to AIsa). Do not call step 2 until the user says sign-in is done or the AIsa tools appear; calling it earlier only returns 401, so do not retry in a loop. If the client must restart to load the server, tell the user and wait. If you cannot add the connector yourself (sandbox, permission denied), give the user the server name and URL above and wait. Do not fall back to another method.
- **B. Your client supports remote MCP but has no browser (CI, SSH, container).** Same endpoint, with the header `Authorization: Bearer $AISA_API_KEY` set in your client's MCP config instead of browser sign-in. If `AISA_API_KEY` is not set, ask the user to create a key at https://console.aisa.one/api-keys and set it in the environment; never ask them to paste it into chat. Never print, log, or commit the key.
- **C. The client has no MCP support.** Use the CLI: `npm install -g @aisa-one/cli && aisa login` (Node.js 18+). Guide: https://aisa.one/docs/get-started/cli.md
- **D. Calling AIsa over HTTP from your own code.** LLMs, OpenAI-compatible: `https://api.aisa.one/v1` (Gemini GenerateContent: `https://api.aisa.one/v1beta`). Data APIs: `https://api.aisa.one/apis/v1`. Auth: `Authorization: Bearer $AISA_API_KEY`. Exact paths and schemas: https://aisa.one/docs/api-reference

Direct HTTP (D) is a gated fallback, not the default. Gate (https://aisa.one/docs/get-started/cli.md#direct-http-fallback): "CLI and MCP are both unavailable, HTTP requests are supported, and a valid existing AIsa API key is already available." The curl and script examples in this skill exist for that fallback; when a connection exists, run the same operation through MCP (`search` → `batch_get_schema` → `batch_quote` → `batch_use`) or the CLI (`aisa search` → `aisa schema` → `aisa quote` → `aisa call`). Take tool names and arguments from `search` or `batch_get_schema`. Never invent them.

### Verify (step 2)

Make one free authenticated call on the interface you connected:

- MCP (A, B): call `account` (no arguments). If it is not in the tool list, call `use` with `{"operation_id": "account"}` instead. Returns the key, balance, and usage.
- CLI (C): `aisa balance`. (`aisa whoami` is local only and does not count.)
- HTTP (D): `GET https://api.aisa.one/v1/models` with the Bearer header returns 200.

AIsa is connected only when this call succeeds. A tool list or a 401 response does not count.

### Spending (approval before paid calls)

- Free: docs, `GET /v1/models`, MCP `search`, `list_categories`, `batch_get_schema`, `batch_quote`, `account`, and CLI `aisa search`, `aisa schema`, `aisa quote`, `aisa balance`.
- Quote the exact calls before running them: MCP `batch_quote`, CLI `aisa quote --json`. Run only what you quoted; re-quote if the tools or arguments change. Neither `batch_use` nor `aisa call` takes a price cap.
- If the quote reports `auto_execute_eligible: true` (a small total), run it without asking, unless the user set a tighter limit or asked only for a quote.
- Otherwise, before the first such call, tell the user in one message what you plan to call, the quoted price, and a total budget for the task in USD. Wait for approval, then run calls within that budget without asking again. Ask again only if the task changes or the next call would exceed the remaining budget.
- For operations billed by rows or credits, also set the operation's own limit (for example `limit`) so the cost stays bounded.
- Do not retry a failed paid call without telling the user.
- Direct HTTP (D) follows the stricter rule at https://aisa.one/docs/get-started/cli.md#direct-http-fallback: read the endpoint's reference and published pricing first; state the exact endpoint and scope, formula or rate, and documented maximum USD exposure; then wait for a separate user message explicitly approving that scope and cap. Do not make paid calls to test availability. Docs, `/v1/models`, and capability or MCP discovery are allowed before approval.

### Cost accounting

The settled cost of a direct HTTP call is reported by the response header `X-AISA-Customer-Cost-Micros-USD` (integer micro-USD; 1 USD = 1,000,000 micro-USD), or by a successful native Tool result's `customer_cost_micros_usd`. Missing cost metadata means unknown, not free. Response bodies do not carry `usage.cost` or `usage.credits_remaining`; do not report those fields as the charge. Reference: https://aisa.one/docs/guides/pricing

### Errors

- `401`: not signed in or invalid key. Redo Connect option A (step 1A in llms.txt) or check the key.
- `402`: low balance, or the operation requires the Go-to-Market plan. The response says which and where to resolve it. Tell the user which one it is (top up the balance, or subscribe to the plan) with the link from the response; do not retry.
- `429`: rate limited. Wait and retry with backoff. Details: https://aisa.one/docs/api-reference/rate-limits
<!-- aisa-rules:end -->

**Find arbitrage opportunities across prediction markets for autonomous agents. Powered by AIsa.**

One API key. Match events across Polymarket and Kalshi to detect price discrepancies and potential risk-free profit opportunities.

## Compatibility

Works with any [agentskills.io](https://agentskills.io)-compatible
harness, including:

- **Claude Code** and **Claude** (Anthropic)
- **OpenAI Codex**
- **Cursor**
- **Gemini CLI** (Google)
- **OpenCode**, **Goose**, **OpenClaw**, **Hermes**
- and any other harness that implements the [Agent Skills
  specification](https://agentskills.io/specification)

Requires Python 3, a POSIX shell, and `AISA_API_KEY` (get one at
[aisa.one](https://aisa.one)).

## What Can You Do?

### Detect Price Discrepancies
```text
"Find the current price difference for the US election market between Polymarket and Kalshi."
```

### Match Cross-Platform Markets
```text
"Find the Kalshi equivalent for this Polymarket sports event."
```

### Track Arbitrage Spreads
```text
"Monitor the price spread for the upcoming NBA game across all supported prediction markets."
```

### Analyze Orderbook Depth
```text
"Check the orderbook depth on both platforms to see if the arbitrage opportunity is actionable."
```

## Quick Start

```bash
export AISA_API_KEY="your-key"
```

## How to Look Up IDs

Most endpoints require an ID from the `/markets` or `/matching-markets` responses. Always query markets first, then pass the relevant ID to downstream endpoints.

1. **Polymarket `token_id`**: Query `/polymarket/markets`, find `side_a.id` or `side_b.id` in the response, then use that value in the market price and orderbook endpoints.
2. **Kalshi `market_ticker`**: Query `/kalshi/markets`, find `market_ticker` in the response, then use that value in the market price and orderbook endpoints.

## Core Capabilities

### 1. Find Matching Markets

The first step in arbitrage is finding the same event on multiple platforms.

#### Match by Event Ticker or Slug

```bash
# Find equivalent markets across platforms using a Polymarket slug
curl -X GET "https://api.aisa.one/apis/v1/matching-markets/sports?polymarket_market_slug={polymarket_market_slug}" \
  -H "Authorization: Bearer $AISA_API_KEY"

# Or find equivalent markets using a Kalshi event ticker
curl -X GET "https://api.aisa.one/apis/v1/matching-markets/sports?kalshi_event_ticker={kalshi_event_ticker}" \
  -H "Authorization: Bearer $AISA_API_KEY"
```

#### Match Sports by Date

```bash
# Find all matching sports markets across platforms for a specific date
curl -X GET "https://api.aisa.one/apis/v1/matching-markets/sports/{sport}?date={date}" \
  -H "Authorization: Bearer $AISA_API_KEY"
```

### 2. Compare Prices

Once matching markets are found, fetch the current prices on both platforms to calculate the spread.

#### Get Polymarket Price

```bash
# token_id comes from side_a.id or side_b.id in /polymarket/markets response
curl -X GET "https://api.aisa.one/apis/v1/polymarket/market-price/{token_id}" \
  -H "Authorization: Bearer $AISA_API_KEY"
```

#### Get Kalshi Price

```bash
# market_ticker comes from /kalshi/markets response
curl -X GET "https://api.aisa.one/apis/v1/kalshi/market-price/{market_ticker}" \
  -H "Authorization: Bearer $AISA_API_KEY"
```

### 3. Verify Liquidity

A price discrepancy is only actionable if there is enough liquidity to execute the trades.

#### Polymarket Orderbook

```bash
# token_id comes from side_a.id or side_b.id in /polymarket/markets response
curl -X GET "https://api.aisa.one/apis/v1/polymarket/orderbooks?token_id={token_id}" \
  -H "Authorization: Bearer $AISA_API_KEY"
```

#### Kalshi Orderbook

```bash
# ticker is the same value as market_ticker from /kalshi/markets response
curl -X GET "https://api.aisa.one/apis/v1/kalshi/orderbooks?ticker={ticker}" \
  -H "Authorization: Bearer $AISA_API_KEY"
```

## Contract status

Validated against the published OpenAPI contract (https://aisa.one/openapi.json) on 2026-10-20. The routes below, used by this skill and its bundled client, are **not in the published contract** and may return 404. They are tracked with reasons in `scripts/validate_skills_known_issues.json` until the owner maps or removes them; the published operations that cover the same data have different parameters, so they were not substituted automatically:

| Legacy route in this skill | Published operation to migrate to |
|---|---|
| `GET /polymarket/market-price/{token_id}` | `GET /polymarket/price?token_id=&side=`, `GET /polymarket/midpoint?token_id=`, `GET /polymarket/prices-history?market=` |
| `GET /polymarket/orderbooks` | `GET /polymarket/book?token_id=`, `GET /polymarket/books?token_ids=` |
| `GET /polymarket/orders` (trade history) | `GET /polymarket/activity`, `GET /polymarket/data/orders` (the published `/polymarket/orders` is POST/DELETE order management) |
| `GET /polymarket/candlesticks/{condition_id}` | `GET /polymarket/prices-history?market=&interval=&fidelity=` |
| `GET /polymarket/positions/wallet/{wallet_address}` | `GET /polymarket/positions?user=` |
| `GET /polymarket/wallet`, `GET /polymarket/wallet/pnl/{wallet_address}` | `GET /polymarket/public-profile?address=`, `GET /polymarket/closed-positions?user=`, `GET /polymarket/value?user=` |
| `GET /kalshi/market-price/{market_ticker}` | `GET /kalshi/markets/{ticker}` |
| `GET /kalshi/orderbooks` | `GET /kalshi/markets/{ticker}/orderbook` |
| `GET /matching-markets/sports[/{sport}]` | no published equivalent (`GET /polymarket/sports` lists Polymarket sports only) |

## API Endpoints Reference

### Cross-Platform Endpoints

| Endpoint | Description | Key Params |
|----------|-------------|------------|
| `/matching-markets/sports` | Find matching sports markets | `polymarket_market_slug` or `kalshi_event_ticker` |
| `/matching-markets/sports/<sport>` | Find sports markets by date | `sport`, `date` |

### Price and Liquidity Endpoints

| Endpoint | Description | Key Params |
|----------|-------------|------------|
| `/polymarket/market-price/<token_id>` | Get Polymarket price | `token_id`, `at_time` |
| `/kalshi/market-price/<market_ticker>` | Get Kalshi price | `market_ticker`, `at_time` |
| `/polymarket/orderbooks` | Get Polymarket orderbook | `token_id`, `start_time`, `end_time` |
| `/kalshi/orderbooks` | Get Kalshi orderbook | `ticker`, `start_time`, `end_time` |

## Important Note About cURL Placeholders

The `{...}` values in the cURL examples are product-level placeholders and must be replaced before execution.

Execution constraint:
- Before running `curl`, the agent or runner must verify that every `{...}` placeholder has been replaced with a concrete value.
- If any placeholder such as `{token_id}`, `{market_ticker}`, `{sport}`, or `{date}` is still present in the final command, do not execute the command. Fail fast and surface a missing-parameter error instead.

This constraint is required because a literal brace placeholder may be interpreted by `curl` as URL globbing syntax rather than as plain text.

## Understanding Arbitrage and Odds

- **Prices as probabilities**: Prices are usually shown as decimals, for example `0.65` means a 65% implied probability.
- **Arbitrage opportunity**: An opportunity exists when the combined price of all mutually exclusive outcomes across different platforms is less than `1.0`. For example, if "Yes" is trading at `0.40` on Polymarket and "No" is trading at `0.55` on Kalshi, buying both guarantees a payout of `1.00` for a total cost of `0.95`, before fees and slippage.
- **Liquidity check**: Always check the `/orderbooks` endpoints. A price difference might exist, but if the orderbook lacks depth, executing the trade may eliminate the profit.

## Pricing

| API | Cost |
|-----|------|
| Prediction market read query | $0.01 |

## Get Started

1. Sign up at [aisa.one](https://aisa.one)
2. Get your API key
3. Add credits (pay-as-you-go)
4. Set environment variable: `export AISA_API_KEY="your-key"`

## Full API Reference

See [API Reference](https://aisa.one/docs/api-reference/) for complete endpoint documentation.