> ## Documentation Index
> Fetch the complete documentation index at: https://ducs.surchi.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# AI Intelligence API: Access SURCHI Market Signals

> Use the SURCHI AI Intelligence API to fetch real-time market signals from Alpha Sentinel and subscribe to live intelligence streams via WebSocket.

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

<ParamField query="asset" type="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.
</ParamField>

<ParamField query="signal_type" 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
</ParamField>

<ParamField query="min_confidence" type="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`.
</ParamField>

<ParamField query="limit" type="integer">
  Maximum number of signals to return. Defaults to `20`. Maximum value is `100`.
</ParamField>

### Example Request

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

### Example Response

```json theme={null}
{
  "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

```javascript wss-client.js theme={null}
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

```json theme={null}
{
  "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:

```json theme={null}
{
  "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"
  }
}
```

<Info>
  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](/developers/rate-limits) page for tier-specific WebSocket connection allowances.
</Info>

## 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](/developers/wallet-integration) for the permissions model.

### Request Body

<ParamField body="command" type="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.
</ParamField>

<ParamField body="wallet_address" type="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](/developers/wallet-integration#execution-permissions).
</ParamField>

<ParamField body="risk_params" type="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.
</ParamField>

### Example Request

```bash theme={null}
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

```json theme={null}
{
  "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 |

<Warning>
  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.
</Warning>