# Assymetrix agent tools

Prediction market data from **Polymarket, Kalshi and Limitless** for AI agents, from the [Assymetrix](https://assymetrix.com) Data API:

- **`@assymetrix/mcp-server`**: an MCP server with three read-only tools, in [`packages/mcp-server`](packages/mcp-server).
- **`prediction-market-data`**: an Agent Skill that teaches an agent to use the same API with `curl`, in [`skills/prediction-market-data`](skills/prediction-market-data).
- **A Claude Code plugin** that bundles both ([`.claude-plugin/`](.claude-plugin)).

Everything here only **reads** market data. Nothing places orders, moves money or links wallets, and nothing here is financial advice. You use your own Assymetrix API key, and a free key works.

## Get an API key

1. Create a free account at https://dashboard.assymetrix.com/signup?utm_source=github&utm_campaign=agent-tools
2. Open **API Keys** and create a key. It is shown once and starts with `asy_`.
3. Keep it in an environment variable, for example in your shell profile: `export ASSYMETRIX_API_KEY=asy_...`

The Free plan includes 10,000 requests per rolling 30 days, 1 request per second and 30 days of history. Each tool call is one request. Paid plans: https://dashboard.assymetrix.com/billing

## Install

### Recommended: the Claude Code plugin (MCP server and skill)

```text
/plugin marketplace add assymetrix/assymetrix-agent-tools
/plugin install assymetrix@assymetrix
```

Claude Code asks for your API key when you enable the plugin and keeps it in your system's secure store, so the key never sits in a config file or the chat.

### Other clients

These read the key from an environment variable or their own config file. Keep the key in your shell profile (`export ASSYMETRIX_API_KEY=asy_...`) rather than typing it into a command.

Claude Code without the plugin (`--transport` goes before the name):

```bash
claude mcp add --env ASSYMETRIX_API_KEY="$ASSYMETRIX_API_KEY" --transport stdio assymetrix -- npx -y @assymetrix/mcp-server
```

Codex:

```bash
codex mcp add assymetrix --env ASSYMETRIX_API_KEY="$ASSYMETRIX_API_KEY" -- npx -y @assymetrix/mcp-server
```

Cursor (`~/.cursor/mcp.json` or `.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "assymetrix": {
      "command": "npx",
      "args": ["-y", "@assymetrix/mcp-server"],
      "env": { "ASSYMETRIX_API_KEY": "${env:ASSYMETRIX_API_KEY}" }
    }
  }
}
```

Claude Desktop (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "assymetrix": {
      "command": "npx",
      "args": ["-y", "@assymetrix/mcp-server"],
      "env": { "ASSYMETRIX_API_KEY": "asy_..." }
    }
  }
}
```

VS Code (`.vscode/mcp.json`, which asks for the key and hides it):

```json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "assymetrix-key",
      "description": "Assymetrix API key",
      "password": true
    }
  ],
  "servers": {
    "assymetrix": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@assymetrix/mcp-server"],
      "env": { "ASSYMETRIX_API_KEY": "${input:assymetrix-key}" }
    }
  }
}
```

### Skill only (Claude Code, Codex, Cursor and other agents)

```bash
npx skills add assymetrix/assymetrix-agent-tools
```

The skill reads `ASSYMETRIX_API_KEY` from the agent's environment and never prints it.

## Tools

| Tool                 | What it returns                                                                                                         |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `search_markets`     | Markets whose question contains your text, sorted by 24-hour volume: id, venue, last price, best bid and ask, end date. |
| `get_market_prices`  | One market's current odds: last price, bid, ask, spread, price changes, each outcome's price, volume and liquidity.     |
| `get_market_history` | OHLCV candles for a time range (the interval is picked to fit), or the market's trades, newest first.                   |

Prices are probabilities from 0 to 1. How far back history goes depends on your plan; when your plan cuts a range, the result says so.

## Configuration

| Variable                  | Default                             | Meaning                                                                 |
| ------------------------- | ----------------------------------- | ----------------------------------------------------------------------- |
| `ASSYMETRIX_API_KEY`      | none                                | Your API key. Without it the server starts and explains how to get one. |
| `ASSYMETRIX_API_BASE_URL` | `https://api.assymetrix.com/api/v1` | Only for testing. Must be https (plain http only for localhost).        |
| `ASSYMETRIX_TIMEOUT_MS`   | `15000`                             | Timeout for one API request, 1000 to 60000.                             |
| `ASSYMETRIX_LOG_LEVEL`    | `warn`                              | `error`, `warn`, `info` or `debug`. Logs go to stderr.                  |

## Privacy

- The MCP server talks only to the Assymetrix Data API, sending your key in the `x-api-key` header, a `User-Agent` with its version, and a random request id that support can use to find a call.
- It collects no telemetry, writes nothing to disk, and never logs or returns your key.
- The skill runs `curl` against the same API from your own machine.
- Privacy policy: https://www.assymetrix.com/privacy-policy. Support: support@assymetrix.com.

## Development

```bash
cd packages/mcp-server
pnpm install
pnpm run check      # type check, build, then the tests (no network)
node ../../skills/validate-skill.cjs ../../skills/prediction-market-data            # skill format checks
node ../../skills/validate-skill.cjs ../../skills/prediction-market-data --release  # also fails on open TODO markers
```

## License

[MIT](LICENSE)