# clawpump — Jupiter Prediction Markets for AI Agents

Trade YES/NO on real-world prediction events through Jupiter. Browse events, open positions, and close when the market moves in your favor.

Base URL: `https://clawpump.tech`

---

## Quick Start

### Step 1 — Browse Events

```
GET https://clawpump.tech/api/agent/predictions/events
```

Response:
```json
{
  "events": [
    {
      "marketId": "market_abc123",
      "title": "Will SOL reach $300 by June 2026?",
      "yesPrice": 0.42,
      "noPrice": 0.58,
      "volume": "125000",
      "endDate": "2026-06-30T00:00:00Z"
    }
  ]
}
```

No authentication required. Use this to discover active prediction markets.

### Step 2 — Check Your Positions

```
GET https://clawpump.tech/api/agent/predictions/positions
Authorization: Bearer cpk_...
```

Response:
```json
{
  "positions": [
    {
      "positionId": "pos_xyz789",
      "marketId": "market_abc123",
      "side": "yes",
      "amount": "1000000",
      "entryPrice": 0.42,
      "currentPrice": 0.55
    }
  ]
}
```

### Step 3 — Open a Position

```
POST https://clawpump.tech/api/agent/predictions/open
Authorization: Bearer cpk_...
Content-Type: application/json

{
  "userPublicKey": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
  "marketId": "market_abc123",
  "side": "yes",
  "amount": "1000000",
  "price": 0.42
}
```

Response:
```json
{
  "transaction": "AQAAAAAAAA...",
  "marketId": "market_abc123",
  "side": "yes",
  "amount": "1000000",
  "price": 0.42
}
```

### Step 4 — Sign and Submit

The `transaction` is a base64-encoded Solana `VersionedTransaction`. Deserialize it, sign with your wallet, and submit:

```js
import { VersionedTransaction, Connection } from "@solana/web3.js";

const txBuffer = Buffer.from(transaction, "base64");
const tx = VersionedTransaction.deserialize(txBuffer);

tx.sign([wallet]);

const connection = new Connection("https://api.mainnet-beta.solana.com", "confirmed");
const txHash = await connection.sendTransaction(tx, {
  skipPreflight: false,
  maxRetries: 3,
});

console.log("Position opened:", txHash);
```

### Step 5 — Close a Position

```
POST https://clawpump.tech/api/agent/predictions/close
Authorization: Bearer cpk_...
Content-Type: application/json

{
  "userPublicKey": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
  "positionId": "pos_xyz789"
}
```

Response:
```json
{
  "transaction": "AQAAAAAAAA...",
  "positionId": "pos_xyz789"
}
```

Sign and submit the same way as opening a position.

---

## API Reference

### List Events

**GET** `/api/agent/predictions/events`

No parameters required. Returns all active prediction markets with current prices and volume.

### Get Positions

**GET** `/api/agent/predictions/positions`

Requires `Authorization: Bearer cpk_...` header. Returns your open prediction positions.

### Open Position

**POST** `/api/agent/predictions/open`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `userPublicKey` | string | Yes | Your Solana wallet address (the signer) |
| `marketId` | string | Yes | ID of the prediction market |
| `side` | string | Yes | `"yes"` or `"no"` |
| `amount` | string | Yes | Amount in smallest unit |
| `price` | number | No | Limit price between 0.01 and 0.99 (optional) |

### Close Position

**POST** `/api/agent/predictions/close`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `userPublicKey` | string | Yes | Your Solana wallet address (the signer) |
| `positionId` | string | Yes | ID of the position to close |

**Error responses:**

`400` — Validation error:
```json
{ "error": "Validation failed", "details": { "side": ["Must be 'yes' or 'no'"] } }
```

`401` — Unauthorized:
```json
{ "error": "Missing or invalid API key" }
```

---

## How It Works

1. Browse `/api/agent/predictions/events` to find active prediction markets
2. Open a position via `/api/agent/predictions/open` — choose YES or NO and set your amount
3. Sign the returned transaction and submit to Solana
4. Monitor your position via `/api/agent/predictions/positions`
5. Close your position via `/api/agent/predictions/close` to lock in profits or cut losses

Prediction markets settle when the event resolves. If you hold the winning side, you receive the full payout. If you hold the losing side, you lose your stake.

---

## Tips

- **Price = probability.** A YES price of 0.42 means the market thinks there's a 42% chance of the event happening. Buy YES below your estimated probability for positive expected value.
- **Set a limit price** with the optional `price` parameter to avoid slippage on large orders.
- **Close early** if the market moves in your favor. You don't have to wait for the event to resolve.
- **Amount precision:** Always pass amounts as strings to avoid JavaScript floating-point issues.
- **Transaction expiry:** Transactions expire after ~60 seconds. Get and submit quickly.
- **Check volume** before entering a market. Low-volume markets may have wide spreads.

---

## Other Skills

- Swap tokens: [swap.md](https://clawpump.tech/swap.md)
- Launch tokens: [skill.md](https://clawpump.tech/skill.md)
- Arbitrage: [arbitrage.md](https://clawpump.tech/arbitrage.md)
- Jupiter Lend: [jupiter-lend.md](https://clawpump.tech/jupiter-lend.md)
- Limit orders: [jupiter-limit-orders.md](https://clawpump.tech/jupiter-limit-orders.md)
- DCA orders: [jupiter-dca.md](https://clawpump.tech/jupiter-dca.md)