API Overview

The Raphael Sentinel API is a Web3-native interface that exposes the full capabilities of the platform’s intelligence engine to external applications, automated trading systems, analytics dashboards, and the Sentinel web client itself. It is built to be fast, secure, scalable, and developer-friendly, allowing seamless integration with on-chain workflows on Solana.

The API is composed of two access layers:

1. REST API — for triggering analyses, retrieving results, managing account state

2. WebSocket API — for real-time intelligence streams, progress updates, and live alerts

Together, these layers make Sentinel programmable, automatable, and accessible for both individual users and institutional clients.

---

1. Design Principles

The API follows several core principles:

Web3-Native Identity

Authentication is based on wallet signatures or API keys — no emails, passwords, or centralized credentials.

Deterministic Responses

All API results are stable, reproducible, and based on the same analysis engine used by the Sentinel UI.

Tier-Aware Access

API usage is automatically shaped by the user’s subscription tier (Free, Pro, VIP).

High Reliability

Every request is routed through redundant infrastructure with automatic retry and fallback nodes.

Developer-Centric

Endpoints return clean, predictable JSON structures designed for automation and bots.

---

2. Authentication Model

Sentinel supports two auth methods:

A. Wallet-Based Authentication (default)

1. Client requests a nonce: POST /auth/nonce

2. User signs the nonce with a Solana wallet.

3. Client submits signature: POST /auth/verify

4. Server issues a short-lived JWT token.

This JWT is included in all API calls:

Authorization: Bearer <jwt>

B. API Keys (partners, bots, institutions)

Permanent or semi-permanent keys issued to trusted clients:

X-API-Key: <key>

---

3. Core REST Endpoints

1. Trigger a Token Analysis

POST /v1/analyze-token

Body:

{ "address": "So11111111111111111111111111111111111111112" }

Response:

{
  "task_id": "task_92d83fa",
  "status": "queued",
  "token_address": "So111111...",
  "queued_at": "2025-12-10T13:15:22Z"
}

---

2. Check Analysis Status

GET /v1/analyze-status/{task_id}

Statuses include:

• queued

• processing

• completed

• failed

A completed result returns the full analysis object:

{
  "status": "completed",
  "task_id": "task_92d83fa",
  "result": {
    "token_type": "BONDING_CURVE",
    "risk_score": 81,
    "risk_level": "high",
    "confidence": "medium",
    "clusters": { ... },
    "wallets": { ... },
    "metrics": { ... }
  }
}

---

3. Fetch Latest Cached Analysis

GET /v1/token/{address}

Returns the freshest stored analysis result, if available.

---

4. Analysis History

GET /v1/history

Allows users to retrieve:

• past analyses

• timestamps

• risk evolution over time

• filtering by score, token, or type

---

5. Subscription Management

• GET /v1/user/subscription

• POST /v1/user/upgrade

• POST /v1/user/verify-payment (SOL or native token)

---

4. WebSocket API (Real-Time Intelligence)

Endpoint

wss://api.raphaelsentinel.com/v1/ws/analysis

Subscription Message

{
  "type": "subscribe",
  "task_id": "task_92d83fa"
}

Streamed Events

{ "event": "started", "task_id": "task_92d83fa" }
{ "event": "progress", "task_id": "task_92d83fa", "progress": 37 }
{ "event": "stage", "stage": "cluster_detection" }
{ "event": "completed", "result": { ... } }

VIP-Only Streams

• real-time risk updates

• dev cluster exit alerts

• behavioral anomaly alerts

• pump-curve momentum warnings

These streams enable advanced automation (bots, algo trading, scanners).

---

5. Rate Limits & Quotas

Rate limits are automatically enforced based on tier:

Tier	Daily Analyses	WebSocket Access	Priority
Anonymous	5	No	Low
Free	10	Yes (basic)	Normal
Pro	500+	Yes (full)	High
VIP	1500+	Yes (priority)	Highest

Clients receive standard headers:

X-RateLimit-Limit
X-RateLimit-Remaining
X-RateLimit-Reset

---

6. Error Format

All errors follow a unified structure:

{
  "error": {
    "code": "INVALID_ADDRESS",
    "message": "The provided mint address is not valid.",
    "request_id": "req_abc123",
    "timestamp": "2025-12-10T13:19:55Z"
  }
}

Common error codes:

• INVALID_ADDRESS

• NOT_FOUND

• RATE_LIMIT_EXCEEDED

• UNAUTHORIZED

• FORBIDDEN_TIER

• ANALYSIS_FAILED

• EXTERNAL_DEPENDENCY_ERROR

---

7. API Versioning

All endpoints are namespaced:

/v1/analyze-token
/v1/token/{address}
/v1/history

Breaking changes → /v2.

Backward-compatible features are rolled out silently.

---

8. Expected Integrations

The API is designed for:

• trading bots

• sentinel-like scanners

• dashboard overlays

• Telegram/Discord alert bots

• institutional dashboards

• retail analysis tools

Because the output is structured intelligence, it can be plugged directly into trading workflows.