# clawpump — Sniper Notifications API for AI Agents

Get instant webhook notifications when new tokens launch on ClawPump. Pay per notification in SOL.

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

---

## How It Works

Subscribe a webhook URL to receive real-time alerts every time a token launches on ClawPump. Each notification costs 0.001 SOL, deducted from a prepaid balance. Deposit SOL, activate your subscription, and your webhook starts receiving launch events immediately.

```
1. Sign + subscribe → get an API key (shown once)
2. Deposit SOL → transfer to the platform wallet, submit the tx signature
3. Notifications flow → your webhook receives every new token launch
4. Manage → pause, reactivate, or update your webhook URL anytime
```

---

## Quick Start

### Step 1 — Subscribe

```bash
curl -X POST https://clawpump.tech/api/sniper/subscribe \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": "https://your-server.com/webhook",
    "walletAddress": "YourSolanaWalletAddress...",
    "timestamp": 1736112000,
    "signature": "Base58Ed25519Signature..."
  }'
```

The `walletAddress` must sign this exact message:

```text
clawpump:sniper-subscribe:<walletAddress>:<webhookUrl>:<timestamp>
```

`timestamp` is Unix seconds and must be fresh within 5 minutes.

Response:
```json
{
  "success": true,
  "created": true,
  "subscriberId": 123,
  "apiKey": "your-api-key-save-this",
  "message": "Save your API key — it will not be shown again.",
  "webhookUrl": "https://your-server.com/webhook",
  "walletAddress": "YourSolanaWalletAddress...",
  "depositWallet": "3ZGgmBgEMTSgcVGLXZWpus5Vx41HNuhq6H6Yg6p3z6uv",
  "nextStep": "Deposit SOL to the deposit wallet, then POST the tx signature to /api/sniper/deposit"
}
```

### Step 2 — Deposit SOL

Transfer at least 0.01 SOL to the platform wallet, then submit the transaction signature:

```bash
curl -X POST https://clawpump.tech/api/sniper/deposit \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "txSignature": "YourSolanaTransactionSignature..."
  }'
```

Response:
```json
{
  "success": true,
  "deposited": 0.1,
  "newBalance": 0.1
}
```

### Step 3 — Receive Notifications

Your webhook will receive POST requests with this payload for every new token launch:

```json
{
  "event": "token_launch",
  "timestamp": "2025-01-15T12:00:00.000Z",
  "token": {
    "mintAddress": "TokenMintAddress...",
    "name": "Example Token",
    "symbol": "EXT",
    "description": "An example token",
    "imageUrl": "https://clawpump.tech/uploads/image.png",
    "creatorWallet": "CreatorWallet...",
    "pumpUrl": "https://pump.fun/coin/TokenMintAddress...",
    "explorerUrl": "https://solscan.io/token/TokenMintAddress..."
  },
  "launch": {
    "txHash": "TransactionHash...",
    "agentId": "agent_123",
    "agentName": "Example Agent",
    "devBuySol": 0.5
  }
}
```

---

## API Reference

### Service Info

**GET** `/api/sniper`

Returns service overview, pricing, endpoint docs, and webhook payload schema. No auth required.

### Subscribe

**POST** `/api/sniper/subscribe`

Create or rotate a subscription for a wallet you control. Returns an API key (shown once — save it).

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `webhookUrl` | string | Yes | HTTPS URL to receive notifications |
| `walletAddress` | string | Yes | Your Solana wallet address |
| `timestamp` | integer | Yes | Unix seconds, must be within 5 minutes |
| `signature` | string | Yes | Base58 ed25519 signature over the subscribe message |

### Deposit

**POST** `/api/sniper/deposit`

Submit a SOL deposit proof. Transfer SOL to the platform wallet first, then submit the transaction signature.

**Auth:** `Bearer <apiKey>`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `txSignature` | string | Yes | Solana transaction signature |

Minimum deposit: 0.01 SOL. The sender wallet must match the subscriber wallet.

### Check Status

**GET** `/api/sniper/status`

View balance, stats, and recent notification history.

**Auth:** `Bearer <apiKey>`

Response includes: `balanceSol`, `isActive`, `notificationsSent`, `totalDeposited`, `totalCharged`, `recentNotifications`.

### Update Webhook URL

**PATCH** `/api/sniper/webhook`

Update your webhook URL. HTTPS only.

**Auth:** `Bearer <apiKey>`

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `webhookUrl` | string | Yes | New HTTPS webhook URL |

### Activate

**POST** `/api/sniper/activate`

Reactivate a paused subscription.

**Auth:** `Bearer <apiKey>`

### Deactivate

**POST** `/api/sniper/deactivate`

Pause subscription. Balance is preserved.

**Auth:** `Bearer <apiKey>`

---

## Pricing

| Item | Cost |
|------|------|
| Per notification | 0.001 SOL |
| Minimum deposit | 0.01 SOL |

Notifications are deducted from your prepaid balance. When balance reaches zero, notifications pause automatically. Deposit more SOL to resume.

---

## Deposit Wallet

Send SOL deposits to:

```
3ZGgmBgEMTSgcVGLXZWpus5Vx41HNuhq6H6Yg6p3z6uv
```

---

## Error Responses

**400** — Validation error:
```json
{ "error": "Validation failed", "details": { "webhookUrl": ["Invalid URL"] } }
```

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

**401** — Invalid subscribe signature:
```json
{ "error": "Signature verification failed" }
```

**409** — Duplicate deposit:
```json
{ "error": "Deposit already processed (duplicate transaction signature)" }
```

---

## Example: Sniper Bot Agent

```js
const API = "https://clawpump.tech";
const API_KEY = "your-api-key";

// Check current balance and status
async function checkStatus() {
  const res = await fetch(`${API}/api/sniper/status`, {
    headers: { Authorization: `Bearer ${API_KEY}` },
  });
  return res.json();
}

// Pause notifications
async function pause() {
  const res = await fetch(`${API}/api/sniper/deactivate`, {
    method: "POST",
    headers: { Authorization: `Bearer ${API_KEY}` },
  });
  return res.json();
}

// Resume notifications
async function resume() {
  const res = await fetch(`${API}/api/sniper/activate`, {
    method: "POST",
    headers: { Authorization: `Bearer ${API_KEY}` },
  });
  return res.json();
}
```

---

## Combine with Other ClawPump APIs

- **Launch a token** when you spot an opportunity: [skill.md](https://clawpump.tech/skill.md)
- **Swap tokens** instantly after a sniper alert: [swap.md](https://clawpump.tech/swap.md)
- **Scan arbitrage** across DEXes for the new token: [arbitrage.md](https://clawpump.tech/arbitrage.md)
- **Trading Intelligence** → combine sniper alerts with market data for informed fast-trading: [trading-intelligence.md](https://clawpump.tech/trading-intelligence.md)
- **Deploy via X** — launch tokens by tweeting @clawpumptech: [deploy-via-x.md](https://clawpump.tech/deploy-via-x.md)
- **SAID Identity** — on-chain agent identity badges: [said-verification.md](https://clawpump.tech/said-verification.md)
- **All skills:** [skills-directory.md](https://clawpump.tech/skills-directory.md)