# Shingou API reference

> Full reference for the Shingou crypto news-sentiment REST API. Base URL: https://api.shingou.io/v1. Get a free key at https://shingou.io/dashboard.

## GET /v1/sentiment

Latest market-impact signal for one or more symbols. Requires an API key.

### Parameters

- `symbols` (string (comma-separated, ≤ 50), required): One or more symbols, comma-separated. Uppercased server-side.

### Example

```
curl "https://api.shingou.io/v1/sentiment?symbols=BTC-USD%2CETH-USD" \
  -H "Authorization: Bearer sk_live_..."
```

### Response

```json
{
  "data": [
    {
      "symbol": "BTC-USD",
      "timestamp": "2026-07-04T04:00:00+00:00",
      "direction": "bullish",
      "score": 0.65,
      "confidence": 0.64,
      "news_volume": 18,
      "novelty_score": 0.74,
      "dominant_events": ["listing", "macro"],
      "summary": "Bullish sentiment driven by renewed ETF buying...",
      "top_sources": [
        {
          "title": "Bitcoin, Ether extend relief rallies as ETF buying returns",
          "source": "cointelegraph.com",
          "url": "https://cointelegraph.com/markets/...",
          "published_at": "2026-07-04T03:54:18.000Z",
          "relevance": 0.95,
          "sentiment": 0.65
        }
      ]
    }
  ]
}
```

### Fields

- `symbol` (string): The requested asset, e.g. BTC-USD.
- `timestamp` (ISO 8601): As-of time of the signal.
- `direction` (enum): bullish / bearish / neutral (±0.15 threshold on score).
- `score` (number [-1,1]): Normalized market-impact. Plot it like any indicator.
- `confidence` (number [0,1]): Blends news volume, cross-source agreement and relevance.
- `news_volume` (integer): Distinct stories behind the signal.
- `novelty_score` (number [0,1]): How fresh the underlying coverage is (dedup-aware).
- `dominant_events` (enum[]): Up to 3 event types driving the signal.
- `summary` (string): Plain-language reason for the score.
- `top_sources` (object[]): Teaser + link references (see below).
- `top_sources[].title` (string): Headline of the source article (teaser only).
- `top_sources[].source` (string): Publisher / domain.
- `top_sources[].url` (string): Link to the original article. Never full text.
- `top_sources[].published_at` (ISO 8601): When the source was published.
- `top_sources[].relevance` (number [0,1]): How relevant the source is to this symbol.
- `top_sources[].sentiment` (number [-1,1]): Per-source sentiment contribution.

## GET /v1/history/sentiment

Point-in-time series for backtesting. As-of timestamps, no lookahead. Requires an API key.

### Parameters

- `symbol` (string, required): A single symbol. Uppercased server-side.
- `from` (string (ISO 8601), required): Start of the range. Clamped to your plan's history window and to at most 90 days before "to"; the applied value is echoed back.
- `to` (string (ISO 8601), required): End of the range. On delayed plans, capped at the freshness delay for non-live symbols.
- `interval` (enum, optional, default 1h): Bucket size.

### Example

```
curl "https://api.shingou.io/v1/history/sentiment?symbol=BTC-USD&from=2026-06-27T00%3A00%3A00Z&to=2026-07-04T00%3A00%3A00Z&interval=1h" \
  -H "Authorization: Bearer sk_live_..."
```

### Response

```json
{
  "symbol": "BTC-USD",
  "interval": "1h",
  "from": "2026-06-27T00:00:00.000Z",
  "to": "2026-07-04T00:00:00.000Z",
  "points": [
    {
      "bucket": "2026-07-04T09:00:00.000Z",
      "score": 0.41,
      "confidence": 0.6,
      "direction": "bullish",
      "news_volume": 3,
      "novelty_score": 0.5,
      "reconstructed": false
    }
  ]
}
```

### Fields

- `symbol` (string): The requested asset.
- `interval` (enum): Applied bucket size.
- `from / to` (ISO 8601): The actual range served after clamping.
- `points[].bucket` (ISO 8601): Bucket start = as-of time. No lookahead.
- `points[].score` (number [-1,1]): Signal for the bucket.
- `points[].confidence` (number [0,1]): Confidence for the bucket.
- `points[].direction` (enum): bullish / bearish / neutral.
- `points[].news_volume` (integer): Stories in the bucket.
- `points[].novelty_score` (number [0,1]): Freshness of coverage in the bucket.
- `points[].reconstructed` (boolean): true = rebuilt by the archival backfill; false = live-collected.

## GET /v1/events

Recent classified market events for a symbol. Requires an API key.

### Parameters

- `symbol` (string, required): A single symbol. Uppercased server-side.
- `limit` (integer (1–100), optional, default 20): Maximum number of events to return.

### Example

```
curl "https://api.shingou.io/v1/events?symbol=BTC-USD&limit=20" \
  -H "Authorization: Bearer sk_live_..."
```

### Response

```json
{
  "symbol": "BTC-USD",
  "events": [
    {
      "id": "evt_01H...",
      "symbol": "BTC-USD",
      "event_type": "macro",
      "headline": "Spot BTC ETFs post record daily inflow",
      "summary": "Renewed institutional demand as ETF net inflows hit a new high.",
      "impact": "bullish",
      "confidence": 0.78,
      "occurred_at": "2026-07-04T03:54:18.000Z",
      "sources": [
        {
          "title": "Bitcoin ETFs see record inflows",
          "source": "cointelegraph.com",
          "url": "https://cointelegraph.com/markets/...",
          "published_at": "2026-07-04T03:40:00.000Z",
          "relevance": 0.93,
          "sentiment": 0.71
        }
      ]
    }
  ]
}
```

### Fields

- `events[].id` (string): Stable event identifier.
- `events[].symbol` (string): The asset the event concerns.
- `events[].event_type` (enum): Classified event type (see Event types).
- `events[].headline` (string): Short event headline.
- `events[].summary` (string): One-line description of the event.
- `events[].impact` (enum): bullish / bearish / neutral impact for the asset.
- `events[].confidence` (number [0,1]): Confidence in the classification.
- `events[].occurred_at` (ISO 8601): When the event occurred.
- `events[].sources` (object[]): Teaser + link references (title, source, url, …).

## GET /health

Liveness check. No authentication required. No authentication required.

### Parameters

No parameters.

### Example

```
curl "https://api.shingou.io/health"
```

### Response

```json
{ "status": "ok" }
```

### Fields

- `status` (string): Always "ok" when the API is up.

## Errors

Every error shares one envelope: {"error": {"code": "...", "message": "..."}}

- 400 `invalid_request`: Missing or invalid query parameters.
- 401 `unauthorized`: Missing, unknown, or revoked API key.
- 404 `not_found`: Unknown route.
- 429 `rate_limited`: Per-minute burst limit exceeded. Slow down.
- 429 `plan_limit`: Daily request cap for your plan reached.
- 500 `internal`: Unexpected server error (no internals leaked).

## For AI agents

- Agent skill + Claude Code plugin: https://github.com/auriontech/shingou-skills (install: /plugin marketplace add auriontech/shingou-skills). Teaches correct API use: auth via SHINGOU_API_KEY, User-Agent "shingou-claude-skill/<version>" on raw HTTP calls, quota etiquette (cache per hour bucket, batch symbols), and disclosure of free-tier 24h delays and reconstructed history buckets.
- MCP endpoint (Streamable HTTP, stateless): POST https://api.shingou.io/mcp with your key in an x-api-key header. Tools: get_sentiment, get_sentiment_history, get_events, get_symbols. Connect: claude mcp add --transport http shingou https://api.shingou.io/mcp --header "x-api-key: <api key>"
- Setup page: https://shingou.io/docs/agents