# clawpump — Jupiter Limit Orders for AI Agents

Set trigger-based limit orders on Jupiter. Create orders that execute automatically when your target price is reached, view order history, and cancel open orders.

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

---

## Quick Start

### Step 1 — Create a Limit Order

```
POST https://clawpump.tech/api/agent/limit-orders/create
Authorization: Bearer cpk_...
Content-Type: application/json

{
  "jwt": "eyJhbGciOiJFZDI1NTE5...",
  "inputMint": "So11111111111111111111111111111111111111112",
  "outputMint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "inputAmount": "1000000000",
  "triggerPrice": "150.50",
  "expiry": 86400
}
```

Response:
```json
{
  "transaction": "AQAAAAAAAA...",
  "orderId": "order_abc123",
  "inputMint": "So11111111111111111111111111111111111111112",
  "outputMint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "inputAmount": "1000000000",
  "triggerPrice": "150.50",
  "expiry": 86400
}
```

### Step 2 — 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("Limit order placed:", txHash);
```

### Step 3 — View Order History

```
GET https://clawpump.tech/api/agent/limit-orders/history
Authorization: Bearer cpk_...
```

Response:
```json
{
  "orders": [
    {
      "orderId": "order_abc123",
      "inputMint": "So11111111111111111111111111111111111111112",
      "outputMint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "inputAmount": "1000000000",
      "triggerPrice": "150.50",
      "status": "open",
      "createdAt": "2026-03-27T12:00:00Z",
      "expiry": 86400
    }
  ]
}
```

### Step 4 — Cancel an Order

```
POST https://clawpump.tech/api/agent/limit-orders/cancel
Authorization: Bearer cpk_...
Content-Type: application/json

{
  "jwt": "eyJhbGciOiJFZDI1NTE5...",
  "orderId": "order_abc123"
}
```

Response:
```json
{
  "transaction": "AQAAAAAAAA...",
  "orderId": "order_abc123"
}
```

Sign and submit the cancellation transaction the same way.

---

## API Reference

### Create Limit Order

**POST** `/api/agent/limit-orders/create`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `jwt` | string | Yes | JWT from Jupiter Trigger v2 challenge/verify flow |
| `inputMint` | string | Yes | Mint address of the token you're selling |
| `outputMint` | string | Yes | Mint address of the token you're buying |
| `inputAmount` | string | Yes | Amount in smallest unit (lamports for SOL) |
| `triggerPrice` | string | Yes | Price at which the order executes |
| `expiry` | number | No | Time-to-live in seconds (60 to 2,592,000 = 30 days) |

### View Order History

**GET** `/api/agent/limit-orders/history`

Requires `Authorization: Bearer cpk_...` header and `jwt` query parameter. Returns all your limit orders with status.

### Cancel Order

**POST** `/api/agent/limit-orders/cancel`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `jwt` | string | Yes | JWT from Jupiter Trigger v2 challenge/verify flow |
| `orderId` | string | Yes | ID of the order to cancel |

**Error responses:**

`400` — Validation error:
```json
{ "error": "Validation failed", "details": { "triggerPrice": ["Trigger price is required"] } }
```

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

---

## Authentication

Limit orders use Jupiter Trigger v2's JWT-based authentication. The flow:

1. Request a challenge from Jupiter's auth endpoint
2. Sign the challenge with your wallet
3. Verify the signature to receive a JWT
4. Pass the JWT in all limit order API calls

This JWT proves wallet ownership without exposing private keys to ClawPump.

---

## Common Token Mints

| Token | Mint Address |
|-------|-------------|
| SOL (Wrapped) | `So11111111111111111111111111111111111111112` |
| USDC | `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v` |
| USDT | `Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB` |

**Amount units:** Always use the smallest unit. For SOL, 1 SOL = `1000000000` lamports. For USDC, 1 USDC = `1000000` micro-units.

---

## How It Works

1. Create a limit order with your desired trigger price via `/api/agent/limit-orders/create`
2. Sign the returned transaction and submit to Solana
3. Jupiter Trigger v2 monitors the market and executes your order when the price is reached
4. Monitor your orders via `/api/agent/limit-orders/history`
5. Cancel unfilled orders via `/api/agent/limit-orders/cancel`

Orders execute automatically through Jupiter's keeper network. No need to monitor prices yourself.

---

## Tips

- **Set realistic trigger prices.** Orders far from the current market price may never fill.
- **Use expiry** to auto-cancel stale orders. Default is no expiry. Maximum is 30 days (2,592,000 seconds).
- **Check order status** via `/api/agent/limit-orders/history`. Statuses: `open`, `filled`, `cancelled`, `expired`.
- **Amount precision:** Always pass amounts as strings to avoid JavaScript floating-point issues.
- **Transaction expiry:** Transactions expire after ~60 seconds. Get and submit quickly.
- **Cancel before re-creating.** If you want to update a price, cancel the old order first.

---

## 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)
- Prediction markets: [jupiter-predictions.md](https://clawpump.tech/jupiter-predictions.md)
- DCA orders: [jupiter-dca.md](https://clawpump.tech/jupiter-dca.md)