AI Intelligence API: Access SURCHI Market Signals

The SURCHI Intelligence API is the primary interface for consuming AI-generated market signals produced by Alpha Sentinel. Every signal carries a confidence score, directional bias, on-chain trigger attribution, and a human-readable summary — giving your application the same intelligence layer that powers the SURCHI protocol. Signals are available via polling REST endpoint or a persistent WebSocket stream for applications that need sub-second latency.

GET /v1/intelligence/signals

Fetch the current set of active AI-generated signals. Signals represent Alpha Sentinel’s real-time assessment of market conditions across Solana assets and are refreshed continuously as new on-chain data is ingested.

Query Parameters

asset

string

Filter signals by token symbol or mint address. Examples: SOL, BONK, JTO, or a full Solana mint address. Omit to return signals across all tracked assets.

signal_type

string

Filter by signal classification. Accepted values:

opportunity — bullish or bearish trade setups identified by Alpha Sentinel
warning — risk alerts such as liquidity withdrawal or unusual selling pressure
whale_alert — large wallet movements above protocol-defined thresholds
sentiment — aggregated social and on-chain sentiment shifts

min_confidence

number

Minimum confidence score threshold, expressed as a decimal between 0 and 1. Only signals with a confidence score at or above this value will be returned. Recommended minimum for actionable signals: 0.75.

limit

integer

Maximum number of signals to return. Defaults to 20. Maximum value is 100.

Example Request

curl 'https://api.surchi.io/v1/intelligence/signals?asset=SOL&min_confidence=0.75' \
  -H 'Authorization: Bearer {token}'

Example Response

{
  "signals": [
    {
      "signal_id": "sig_a8f2b3",
      "signal_type": "opportunity",
      "asset": "SOL",
      "confidence": 0.89,
      "direction": "bullish",
      "timeframe": "4h",
      "triggers": ["whale_accumulation", "volume_breakout"],
      "summary": "Strong accumulation detected from 3 whale wallets over the last 2 hours",
      "timestamp": "2024-01-15T14:23:00Z"
    }
  ],
  "total": 1,
  "generated_at": "2024-01-15T14:25:00Z"
}

Response Fields

Field	Type	Description
`signal_id`	string	Unique identifier for this signal instance
`signal_type`	string	Classification: `opportunity`, `warning`, `whale_alert`, or `sentiment`
`asset`	string	Token symbol the signal applies to
`confidence`	number	Alpha Sentinel confidence score between 0 and 1
`direction`	string	`bullish`, `bearish`, or `neutral`
`timeframe`	string	Expected signal relevance window (e.g. `1h`, `4h`, `1d`)
`triggers`	array	On-chain events that contributed to this signal
`summary`	string	Human-readable explanation of the signal
`timestamp`	string	ISO 8601 UTC timestamp when the signal was generated

WebSocket: Live Signal Stream

For applications that require real-time signal delivery, subscribe to the persistent WebSocket stream at wss://api.surchi.io/v1/stream/signals. Signals are pushed to your connection as soon as Alpha Sentinel generates them — typically within milliseconds of the triggering on-chain event.

Connecting and Subscribing

wss-client.js

const ws = new WebSocket('wss://api.surchi.io/v1/stream/signals', {
  headers: { Authorization: 'Bearer {token}' }
});

ws.on('open', () => {
  // Send a subscription message with optional filters
  ws.send(JSON.stringify({
    subscribe: 'signals',
    filters: {
      assets: ['SOL', 'JTO'],
      min_confidence: 0.8
    }
  }));
});

ws.on('message', (data) => {
  const signal = JSON.parse(data);
  console.log('New signal:', signal);
});

ws.on('close', (code, reason) => {
  console.warn(`WebSocket closed: ${code} — ${reason}`);
  // Implement exponential backoff reconnect logic here
});

ws.on('error', (err) => {
  console.error('WebSocket error:', err);
});

Subscription Message Schema

{
  "subscribe": "signals",
  "filters": {
    "assets": ["SOL", "BONK", "JTO"],
    "signal_types": ["opportunity", "whale_alert"],
    "min_confidence": 0.75
  }
}

All filter fields are optional. Omitting filters entirely subscribes to the full unfiltered signal stream.

Incoming Signal Message

Pushed messages follow the same schema as the REST response signal objects:

{
  "event": "signal",
  "data": {
    "signal_id": "sig_c9d4e1",
    "signal_type": "whale_alert",
    "asset": "JTO",
    "confidence": 0.93,
    "direction": "bullish",
    "timeframe": "1h",
    "triggers": ["large_wallet_inflow"],
    "summary": "Whale wallet accumulated 840,000 JTO in a single transaction",
    "timestamp": "2024-01-15T14:27:45Z"
  }
}

WebSocket connections are rate-limited to 1 active connection per API key. Opening a second connection will terminate the first. Implement reconnection logic with exponential backoff — start with a 1-second delay and double on each failure up to a maximum of 60 seconds. See the Rate Limits page for tier-specific WebSocket connection allowances.

POST /v1/execution/strategy

Submit a natural language or structured execution strategy to Execution Sentinel. Execution Sentinel parses your command, identifies the required on-chain steps, and returns a strategy plan for review before any action is taken on-chain. Execution only proceeds after the plan is confirmed and your wallet has granted the necessary execution permissions — see Wallet Integration for the permissions model.

Request Body

command

string

required

A natural language description of the strategy you want Execution Sentinel to carry out. Examples: "Swap 10 SOL to USDC if SOL drops below $90" or "Add $500 of liquidity to the SOL/USDC pool on Raydium". Execution Sentinel will parse the intent and translate it into discrete on-chain steps.

wallet_address

string

required

The Solana wallet address on behalf of which the strategy should be executed. The wallet must have granted the relevant execution permissions via the permissions flow.

risk_params

object

Optional risk constraints that cap and govern execution behavior. All fields are optional — omitting risk_params falls back to the defaults set during the wallet’s permission grant.

max_amount_usd (number) — maximum total value in USD that Execution Sentinel is permitted to move in a single strategy execution
slippage_bps (number) — maximum acceptable slippage in basis points (e.g. 50 = 0.5%). Executions that would exceed this slippage are aborted.

Example Request

curl -X POST https://api.surchi.io/v1/execution/strategy \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "command": "Swap 5 SOL to USDC if the SOL price drops below $90 within the next hour",
    "wallet_address": "7xKXtg2CW87d97TXJSDpbD5jBkheTqA83TZRuJosgAsU",
    "risk_params": {
      "max_amount_usd": 500,
      "slippage_bps": 50
    }
  }'

Example Response

{
  "strategy_id": "strat_7f3a2c9d",
  "status": "pending_review",
  "parsed_intent": {
    "action": "swap",
    "from_asset": "SOL",
    "to_asset": "USDC",
    "amount": 5,
    "condition": {
      "trigger": "price_below",
      "asset": "SOL",
      "threshold_usd": 90,
      "expiry": "1h"
    }
  },
  "estimated_steps": [
    {
      "step": 1,
      "description": "Monitor SOL/USD price via Alpha Sentinel",
      "type": "condition_watch"
    },
    {
      "step": 2,
      "description": "Execute SOL → USDC swap on best available DEX route",
      "type": "swap",
      "estimated_gas_sol": 0.000005
    }
  ]
}

Response Fields

Field	Type	Description
`strategy_id`	string	Unique identifier for this strategy submission
`status`	string	Always `pending_review` on initial submission — the plan is not yet executing
`parsed_intent`	object	Execution Sentinel’s structured interpretation of your natural language command
`estimated_steps`	array	Ordered list of on-chain actions the strategy will perform once conditions are met

Submitting a strategy does not immediately execute any on-chain transaction. The returned plan is in pending_review status — review the parsed_intent and estimated_steps carefully to confirm Execution Sentinel has interpreted your command correctly before proceeding. Your wallet must have the appropriate execution permissions granted before a strategy can be activated. Never grant permissions or activate strategies from untrusted third-party applications.

​GET /v1/intelligence/signals

​Query Parameters

​Example Request

​Example Response

​Response Fields

​WebSocket: Live Signal Stream

​Connecting and Subscribing

​Subscription Message Schema

​Incoming Signal Message

​POST /v1/execution/strategy

​Request Body

​Example Request

​Example Response

​Response Fields

GET /v1/intelligence/signals

Query Parameters

Example Request

Example Response

Response Fields

WebSocket: Live Signal Stream

Connecting and Subscribing

Subscription Message Schema

Incoming Signal Message

POST /v1/execution/strategy

Request Body

Example Request

Example Response

Response Fields