# DrainBrain by RugSlayer - Complete API Documentation

> ML-powered Solana token rug pull detection. 5-model ensemble trained on 175K+ tokens.
> Risk scoring, honeypot detection, temporal analysis, wallet clustering.

---

## Overview

DrainBrain analyzes Solana tokens for rug pull risk using a 5-model ML ensemble:
- XGBoost v1: Liquidity pattern detection (15 features)
- XGBoost v2: Enrichment features with RugCheck signals (17 features)
- GRU Temporal: 2-layer GRU learning behavioral patterns across 4 time windows
- NVIDIA NIM: Content safety and guard models
- Heuristic: Rule-based authority, liquidity, and holder analysis

Returns a score from 0-100 (higher = more risky), risk level (LOW/MEDIUM/HIGH/CRITICAL), rug stage (0-5), honeypot detection, and risk flags.

---

## Authentication

Two methods to access DrainBrain:

### 1. API Key (Bearer Token)
Get a free key at https://rugslayer.com/drainbrain#keys or via the API:

```
POST https://rugslayer.com/api/drainbrain/v1/keys
Content-Type: application/json

{"name": "my-agent", "email": "agent@example.com"}
```

Response:
```json
{"apiKey": "db_live_abc123...", "id": "uuid", "tier": "free"}
```

Use the key in all requests:
```
Authorization: Bearer db_live_abc123...
```

### 2. x402 USDC Micropayments (via Harvey Intel MCP)
Connect to the MCP server at https://agents.rugslayer.com/mcp
No account needed. Pay per call with USDC on Solana.
Prices: scan_token $0.01, trading signals $0.02, market regime $0.02, social trends $0.02, competitor intel $0.02.

### 3. Stripe ACP (Agent Commerce Protocol)
Fully programmatic credit card payment via SharedPaymentTokens. No human interaction needed.
```
1. POST /api/agent/acp/checkouts with {plan: "pro"} -> get checkout_id + amount_cents
2. PUT /api/agent/acp/checkouts/{id} with {shared_payment_granted_token: "spt_..."} -> ready
3. POST /api/agent/acp/checkouts/{id}/complete -> payment + API key provisioned instantly
```
Plans: Pro ($199/mo, 10K calls/min), PAYG ($49/mo + $0.005/call, 1K calls/min).
Requires commerce token (Authorization: Bearer <commerce_token>). Contact j@rugslayer.com for access.

---

## Pricing Tiers

| Tier | Price | Rate Limit | Features |
|------|-------|------------|----------|
| Free | $0 | 100 scans/day | score, riskLevel, isRug |
| Pro | $199/month | 10,000/min | Full breakdown, honeypot, temporal, riskFlags, batch scan |
| PAYG | $49/month + $0.005/call | 1,000/min | Same as Pro, pay for what you use |

Payment methods: Stripe (credit card) or USDC on Solana (same prices).

---

## Endpoints

### POST /api/drainbrain/v1/scan

Scan a single Solana token for rug pull risk.

**Request:**
```json
{
  "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
}
```

**Headers:**
```
Authorization: Bearer db_live_xxx
Content-Type: application/json
```

**Response (200):**
```json
{
  "mint": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
  "score": 12,
  "riskLevel": "LOW",
  "isRug": false,
  "cached": false,
  "timestamp": "2026-03-03T16:00:00Z",
  "rugStage": 0,
  "honeypot": {
    "isHoneypot": false,
    "reason": null
  },
  "riskFlags": ["MINT_AUTHORITY_ENABLED"],
  "temporal": {
    "stage": 0,
    "confidence": 0.92,
    "pullHours": null
  },
  "scoreMethod": "ensemble-nvidia"
}
```

**Parameters:**
- `mint` (required, string): Solana token mint address in base58 format. Must be 32-44 characters. Example: `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v`
- `action` (optional, string): `scan_only` (default) or `quote_if_risky`. Pro/PAYG only.
- `riskThreshold` (optional, number): Score threshold 0-100 to trigger action. Default: 70.

**Response Fields:**
- `score` (number, 0-100): Ensemble risk score. 0 = safest, 100 = certain rug.
- `riskLevel` (string): LOW (0-30), MEDIUM (31-50), HIGH (51-70), CRITICAL (71-100).
- `isRug` (boolean): True if score >= 70.
- `cached` (boolean): True if result came from cache (results cached for 5 minutes).
- `rugStage` (number, 0-5): Rug lifecycle stage. 0=Safe, 1=Setup, 2=Pump, 3=Distribution, 4=Preparation, 5=Execution. Pro/PAYG only.
- `honeypot` (object): Buy/sell simulation via Jupiter. `isHoneypot: true` means selling is blocked. Pro/PAYG only.
- `riskFlags` (array of strings): Specific risk indicators found. Examples: MINT_AUTHORITY_ENABLED, FREEZE_AUTHORITY_ENABLED, LOW_LIQUIDITY, HIGH_HOLDER_CONCENTRATION, LP_UNLOCKED. Pro/PAYG only.
- `temporal` (object): GRU model's behavioral prediction. `pullHours` estimates time until rug if detected. Pro/PAYG only.
- `scoreMethod` (string): Which scoring pipeline was used. `ensemble-nvidia` = full 5-model, `ensemble` = 4-model (no NVIDIA), `heuristic` = rules only.

**Errors:**
- `401 Unauthorized`: Missing or invalid API key. Get one at https://rugslayer.com/drainbrain#keys
- `429 Too Many Requests`: Rate limit or daily quota exceeded. Check `X-RateLimit-Remaining` header. Free tier: wait until midnight UTC reset. Pro/PAYG: reduce request rate.
- `400 Bad Request`: Invalid mint address format. Must be base58, 32-44 characters.
- `500 Internal Server Error`: Transient. Retry with exponential backoff (max 3 retries).

---

### POST /api/drainbrain/v1/scan/batch

Scan up to 10 tokens in parallel. Pro/PAYG tier required.

**Request:**
```json
{
  "mints": [
    "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "So11111111111111111111111111111111111111112"
  ]
}
```

**Response (200):**
```json
{
  "results": [
    {"mint": "EPjFWdd5...", "score": 12, "riskLevel": "LOW", "isRug": false},
    {"mint": "So111...", "score": 5, "riskLevel": "LOW", "isRug": false}
  ],
  "errors": [],
  "totalMs": 245,
  "count": 2
}
```

**Parameters:**
- `mints` (required, array of strings): 1-10 Solana mint addresses. Each must be valid base58.

**Errors:**
- `401`: Not authenticated or free tier (batch requires Pro/PAYG).
- `400`: More than 10 mints, or invalid mint format.

---

### POST /api/drainbrain/v1/keys

Generate a free API key. No authentication required.

**Request:**
```json
{
  "name": "my-trading-bot",
  "email": "bot@example.com"
}
```

**Response (201):**
```json
{
  "apiKey": "db_live_abc123def456...",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "tier": "free",
  "message": "Save this key - it cannot be retrieved later"
}
```

**Parameters:**
- `name` (required, string): Name for this key (your project or bot name). 1-100 characters.
- `email` (required, string): Contact email. Valid email format required.

**Important:** The `apiKey` value is shown only once. Store it securely. If lost, generate a new key.

---

### GET /api/drainbrain/v1/keys

List all API keys for an email. Requires authentication with any key from that email.

**Response (200):**
```json
{
  "keys": [
    {
      "id": "uuid",
      "name": "my-bot",
      "tier": "free",
      "calls_today": 42,
      "calls_total": 1250,
      "created_at": "2026-03-01T00:00:00Z",
      "last_used_at": "2026-03-03T16:00:00Z"
    }
  ]
}
```

---

### DELETE /api/drainbrain/v1/keys/{id}

Revoke an API key. Requires authentication with a key from the same email.

**Parameters:**
- `id` (required, path, string): UUID of the key to revoke.

**Response (200):**
```json
{"message": "Key revoked", "id": "uuid"}
```

---

### POST /api/drainbrain/v1/keys/{id}/rotate

Rotate a key: deactivates the old key and returns a new one. Requires authentication.

**Parameters:**
- `id` (required, path, string): UUID of the key to rotate.

**Response (200):**
```json
{
  "apiKey": "db_live_newkey789...",
  "id": "new-uuid",
  "tier": "free"
}
```

---

### GET /api/drainbrain/v1/health

Check API status. No authentication required.

**Response (200):**
```json
{
  "status": "operational",
  "models": {
    "xgboost_v1": true,
    "xgboost_v2": true,
    "gru_temporal": true,
    "nvidia_nim": true,
    "heuristic": true
  },
  "timestamp": "2026-03-03T16:00:00Z"
}
```

---

## Harvey Intel MCP Server

For agents that prefer MCP (Model Context Protocol), Harvey Intel wraps all DrainBrain tools plus trading signals and social intelligence.

**Connection:**
```
claude mcp add harvey-intel --transport http https://agents.rugslayer.com/mcp
```

**npm:**
```
npx -y @meltingpixels/harvey-intel
```

**8 Tools (3 free + 5 paid):**
| Tool | Price | Description |
|------|-------|-------------|
| list_tools | FREE | List all tools with pricing |
| health | FREE | Server status and payment config |
| scan_token_preview | FREE | Quick risk level (LOW/MEDIUM/HIGH/CRITICAL) |
| scan_token | $0.01 USDC | Full DrainBrain ML analysis |
| get_trading_signals | $0.02 USDC | CORTEX AI trading signals |
| get_market_regime | $0.02 USDC | Market regime detection (HOT/NORMAL/COLD) |
| get_social_trends | $0.02 USDC | Social intelligence from Synthia |
| get_competitor_intel | $0.02 USDC | Competitor tracking from Synthia |

**Payment:** x402 USDC on Solana (automatic, no account) or API key (Bearer db_live_xxx).

---

## Error Format

All error responses follow this structure:
```json
{
  "error": "Human-readable error message"
}
```

HTTP status codes:
- 400: Bad request (invalid input)
- 401: Unauthorized (missing/invalid API key)
- 403: Forbidden (tier insufficient for this endpoint)
- 429: Rate limited (check X-RateLimit-Remaining header)
- 500: Server error (retry with backoff)

---

## Rate Limits

| Tier | Limit | Reset |
|------|-------|-------|
| Free | 100 calls/day | Midnight UTC |
| Pro | 10,000 calls/min | Rolling window |
| PAYG | 1,000 calls/min | Rolling window |

Rate limit headers on every response:
- `X-RateLimit-Limit`: Max calls in current window
- `X-RateLimit-Remaining`: Calls left
- `X-RateLimit-Reset`: UTC timestamp when window resets

---

## SDK Examples

### TypeScript/JavaScript
```typescript
const response = await fetch("https://rugslayer.com/api/drainbrain/v1/scan", {
  method: "POST",
  headers: {
    "Authorization": "Bearer db_live_xxx",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ mint: "TOKEN_MINT_ADDRESS" })
});
const result = await response.json();
console.log(result.score, result.riskLevel, result.isRug);
```

### Python
```python
import requests

response = requests.post(
    "https://rugslayer.com/api/drainbrain/v1/scan",
    headers={"Authorization": "Bearer db_live_xxx"},
    json={"mint": "TOKEN_MINT_ADDRESS"}
)
result = response.json()
print(result["score"], result["riskLevel"], result["isRug"])
```

### cURL
```bash
curl -X POST https://rugslayer.com/api/drainbrain/v1/scan \
  -H "Authorization: Bearer db_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"mint": "TOKEN_MINT_ADDRESS"}'
```

---

## Links

- Website: https://rugslayer.com
- DrainBrain Docs: https://rugslayer.com/drainbrain
- API Keys: https://rugslayer.com/drainbrain#keys
- Pricing: https://rugslayer.com/pricing
- Harvey Intel MCP: https://agents.rugslayer.com/mcp
- npm: https://www.npmjs.com/package/@meltingpixels/harvey-intel
- Privacy: https://rugslayer.com/privacy
- Contact: j@rugslayer.com