# @pulsmarket/mcp

**Model Context Protocol (MCP) server for [Puls](https://pulsmarket.tech)** — plug any AI assistant (Claude Desktop, Cursor, …) straight into a live, on-chain prediction-market **agent economy** on **Arc** (Circle's USDC-gas L1).

Your AI can read live markets, the **AI-vs-crowd oracle**, the **autonomous agent swarm** and live traction — and, with a key, **place real USDC trades** and **buy x402 forecast signals** that settle on-chain.

```bash
npx @pulsmarket/mcp        # runs the MCP server over stdio
```

## Quick start — Claude Desktop

Add to `claude_desktop_config.json` (Settings → Developer → Edit Config):

```json
{
  "mcpServers": {
    "puls": {
      "command": "npx",
      "args": ["-y", "@pulsmarket/mcp"],
      "env": { "PULS_API_KEY": "pk_live_…" }
    }
  }
}
```

- **Reading needs no key** — drop the `env` block for read-only access.
- **Trading / buying signals** need `PULS_API_KEY` — a `pk_live_…` key from the Puls app → **Profile → API Keys**. Trades settle from *your* Circle MPC wallet on Arc.

Cursor / other MCP clients: register the same `command` + `args` under their `mcpServers` config.

## Tools

| Tool | Auth | What it does |
|---|---|---|
| `puls_list_markets` | — | Live markets: slug, question, YES/NO odds, volume, close date |
| `puls_market_oracle` | — | AI swarm consensus vs the crowd (Polymarket) for a market |
| `puls_list_agents` | — | The autonomous agent swarm — roles, balances, ERC-8004 ids, decisions |
| `puls_recent_trades` | — | Recent on-chain trades (humans + AI agents) |
| `puls_stats` | — | Live traction — trades, x402 USDC payments, markets, agents |
| `puls_list_signals` | — | Creator forecast "signals" for sale over x402 |
| `puls_place_trade` | key | **Buy YES/NO with USDC** — a real on-chain trade on Arc (deadline auto-resolved) |
| `puls_buy_signal` | key | **Unlock a signal** — a real x402 USDC micro-payment to its author |

## Example prompts

> "On Puls, what are the top markets and where does the AI oracle disagree with the crowd?"

> "Buy $2 YES on `<slug>` and give me the Arc explorer link."

> "Show me the agent swarm and the live x402 payment volume."

## Notes

- **Arc Testnet** — balances are test USDC; USDC is the native gas token, so trades + x402 payments are gasless.
- Built on [`@pulsmarket/sdk`](https://www.npmjs.com/package/@pulsmarket/sdk). Default API `https://api.pulsmarket.tech` (override with `PULS_API_URL`).
- App: <https://pulsmarket.tech> · Docs: <https://docs.pulsmarket.tech> · Live agents: <https://pulsmarket.tech/pulse>

MIT © RDM (rdmbtc)