# API Integration

Plugging into the Gloria Data Platform is simple. You can fetch both our pre-curated feeds and custom feeds (set up on request) via REST, WebSocket or x402 API.

***

## **REST API**

### Overview

The News API provides access to processed and curated content from various feeds like general crypto, macro, AI agent, and much more. Unlike the WebSocket API which provides real-time updates, this REST endpoint allows you to retrieve historical data within a specific date range.

### Endpoint

```
GET /news
```

#### Query Parameters

<table><thead><tr><th width="201.5390625">Parameter</th><th width="103.2265625">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>token</code></td><td><code>string</code></td><td>Authorization token. You can generate/manage your authorization tokens here: <a href="https://app.itsgloria.ai/api-tokens">https://app.itsgloria.ai/api-tokens</a></td></tr><tr><td><code>feed_categories</code></td><td><code>string</code></td><td>Comma-separated list of feed categories to fetch (e.g. <code>crypto,ai_agents</code>). Must be in your allowed feed categories, specified during token creation.</td></tr><tr><td><code>from_date</code></td><td><code>string</code></td><td>Optional. Start date in ISO format (<code>YYYY-MM-DD</code>). Defaults to <code>2025-05-01</code>.</td></tr><tr><td><code>to_date</code></td><td><code>string</code></td><td>Optional. End date in ISO format (<code>YYYY-MM-DD</code>). Defaults to <code>today</code>.</td></tr><tr><td><code>page</code></td><td><code>number</code></td><td>Optional. Page number for pagination. Defaults to <code>1</code>.</td></tr><tr><td><code>limit</code></td><td><code>number</code></td><td>Optional. Number of items per page. Defaults to <code>20</code>.</td></tr></tbody></table>

### Authentication

All requests to the News API require authentication using an authorization token. You can provide it as a query parameter:

```url
https://ai-hub.cryptobriefing.com/news?token={{token}}&feed_categories=crypto,rwa
```

You can generate/manage your authorization tokens here: [https://app.itsgloria.ai/api-tokens](https://app.itsgloria.ai/api-tokens)

If a token is not provided or is invalid, the request will fail with a `401 Unauthorized` response.

### Feed Permissions

Each authorization token is associated with permissions for specific feed categories.

If at least one feed category you are trying to fetch from is not in the list of allowed (specified during authorization token creation), the request will fail with a `403 Forbidden` response.

### Available Feeds

The following feeds are available for subscription:

* `ai_agents`: Updates related to AI agents and technologies
* `crypto`: General cryptocurrency news and updates
* `aptos`: Aptos blockchain specific updates
* `rwa`: Real World Asset updates
* `ondo`: Ondo Finance related updates
* `macro`: Macro news

### Response Format

The API returns an array of feed items in JSON format. Each item has the following structure:

```json
[
    {
        "id": "185f8557-7fb7-4bae-b75e-1e347436a8f4",
        "signal": "New York Teachers Pension Fund buys $1.5M of CleanSpark as $30T in US pensions await Bitcoin exposure",
        "timestamp": 1752154081.018553,
        "feed_category": "crypto",
        "short_context": "The New York State Teachers' Retirement System (NYSTRS) recently reported holding 175,129 shares of CleanSpark Inc., valued at about $5.34 million as of March 31, 2025. Over the past two years, institutional investors have collectively purchased more than 41 million shares of CleanSpark stock, highlighting significant and growing interest from large financial entities in the company and the Bitcoin mining sector.",
        "long_context": "Facts\n\n- The **New York State Teachers' Retirement System (NYSTRS)** recently disclosed a holding of **175,129 shares of CleanSpark Inc.** valued at approximately **$5.34 million as of March 31, 2025**[5].\n- This is a significant increase compared to earlier reported holdings; for example, one source listed NYSTRS with about **218,900 shares valued at $1,471 thousand**, though that appears to be based on an older or possibly misreported price[4].\n- CleanSpark (NASDAQ: CLSK) is a company heavily involved in the Bitcoin mining sector.\n- Over the past two years, institutional investors have purchased more than **41 million shares** of CleanSpark stock[3].\n- It is estimated that there is roughly **$30 trillion in U.S. pension fund assets**, and financial experts are watching closely for greater pension exposure to Bitcoin and related companies.\n\nWhy it matters\n\nPension funds represent some of the largest pools of investment capital globally. When a major public pension system like NYSTRS adds exposure to a company focused on Bitcoin mining—such as CleanSpark—it signals growing mainstream acceptance and potential adoption of digital asset-related investments among traditionally conservative institutions. If this trend continues across other large pensions managing trillions in assets, it could significantly impact both the cryptocurrency market and broader perceptions around digital assets as viable long-term investments.\n\nZooming out\n\nBroader Pension Trends:\n- As of early 2025, total U.S. pension fund assets are estimated at about $30 trillion—a vast sum relative to global markets.\n  \nInstitutional Crypto Adoption:\n- Institutional investors now hold over 43% ownership in CleanSpark stock—a notable marker given historic skepticism toward crypto-related equities by such entities[3].\n\nHistorical Comparisons:\n- Pension allocations into technology or emerging sectors have historically been slow but can accelerate quickly once risk/return profiles shift or regulatory stances change nationwide.\n",
        "sources": [
            "https://www.trsnyc.org/memberportal/WebContent/publications/financialReports/investmentPortfolios2023",
            "https://stockzoa.com/ticker/clsk/",
            "https://www.marketbeat.com/stocks/NASDAQ/CLSK/institutional-ownership/",
            "https://www.holdingschannel.com/funds/holding-clsk/",
            "https://www.nystrs.org/getmedia/8ebb7fd5-c7fc-4f64-94a3-510877371ddc/equity_domestic.pdf"
        ]
    },
    {
        "id": "80dd4d47-1e7a-4244-9d68-42058e42bf34",
        "signal": "GameSquare completes initial $5M Ethereum purchase for $100M ETH treasury strategy",
        "timestamp": 1752153005.863336,
        "feed_category": "crypto",
        "short_context": "GameSquare Holdings has launched a **$100 million Ethereum-based treasury strategy**, which was approved by its board and will be implemented in phases. To support this plan, the company completed an initial public offering of **8,421,054 shares at $0.95 per share**, raising approximately **$8 million in gross proceeds** to accelerate the rollout of its Ethereum-focused treasury approach.",
        "long_context": "Facts\n\n- GameSquare Holdings has launched a **$100 million Ethereum-based treasury strategy**, approved by its board and to be deployed in phases[1][3][5].\n- The company completed an initial **public offering of 8,421,054 shares at $0.95 per share**, raising **$8 million in gross proceeds**[1][3].\n- This first $5 million purchase of ETH is part of the phased plan toward the full $100 million allocation[1].\n- Lucid Capital Markets acted as the sole book-runner for this offering; it can buy up to 1,263,157 additional shares within 45 days[1].\n- GameSquare is collaborating with crypto investment firm Dialectic and will use its Medici platform for yield generation and risk management[1][3][5].\n- The Medici platform leverages machine learning and automated optimization to target yields between **8% and 14%**, well above standard ETH staking returns of 3–4%[1][3][5].\n- The treasury strategy may also include investments in stablecoins and NFTs for diversification beyond just ETH holdings[1][3].\n\nWhy it matters\n\nGameSquare's move marks a significant shift in corporate treasury management by allocating a substantial portion of its assets into Ethereum rather than traditional instruments. By targeting yields far higher than conventional staking or fiat-based returns—and utilizing sophisticated risk controls—GameSquare aims to boost financial flexibility while tapping into decentralized finance (DeFi) opportunities. This approach could set a precedent for other public companies considering on-chain asset strategies as part of their capital management, potentially increasing mainstream adoption of crypto assets at the institutional level.\n\nZooming out\n\nCorporate Adoption Trends\n- Tesla made headlines in early 2021 by buying $1.5 billion worth of Bitcoin as a treasury asset; more firms have since explored digital assets for diversification.\n  \nEthereum Staking Yields\n- Typical annualized returns from Ethereum staking range from about 3–4%, making GameSquare’s targeted DeFi yields (8–14%) notably aggressive.\n\nDeFi Ecosystem Growth\n- As of mid-2025, DeFi protocols collectively hold over $90 billion in total value locked (TVL), reflecting growing interest from both retail users and institutions seeking yield opportunities on-chain.",
        "sources": [
            "https://thecryptobasic.com/2025/07/09/gamesquare-launches-100m-ethereum-treasury-strategy/",
            "https://coincentral.com/pepeto-races-past-5-million-presale-and-preps-to-take-solaxys-spot/",
            "https://www.tradingview.com/news/cryptonews:09d06fde1094b:0-nasdaq-listed-gamesquare-secures-8m-to-initiate-100m-eth-treasury/",
            "https://www.btcc.com/en-US/square/StellarMiner/603071",
            "https://investors.gamesquare.com/news/news-details/2025/GameSquare-Announces-Pricing-of-Underwritten-Public-Offering-to-Launch-Ethereum-Treasury-Strategy/default.aspx"
        ]
    }
    // More items...
]
```

#### Response Fields

<table><thead><tr><th width="158.6875">Field</th><th width="114.8671875">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>id</code></td><td><code>string</code></td><td>Unique identifier for the news item.</td></tr><tr><td><code>signal</code></td><td><code>string</code></td><td>The main content of the news item.</td></tr><tr><td><code>timestamp</code></td><td><code>number</code></td><td>Unix timestamp (in seconds) of when the item was created.</td></tr><tr><td><code>feed_category</code></td><td><code>string</code></td><td>Feed category the news item belongs to.</td></tr><tr><td><code>short_context</code></td><td><code>string</code></td><td>Short context for the news item.</td></tr><tr><td><code>long_context</code></td><td><code>string</code></td><td>Expanded context for the news item.</td></tr><tr><td><code>sources</code></td><td><code>string[]</code></td><td>List </td></tr></tbody></table>

### Status Codes

<table><thead><tr><th width="158.6875">Status Code</th><th>Description</th></tr></thead><tbody><tr><td><code>200</code></td><td>Success</td></tr><tr><td><code>400</code></td><td>Bad Request (invalid parameters)</td></tr><tr><td><code>401</code></td><td>Unauthorized (missing or invalid authorization token)</td></tr><tr><td><code>403</code></td><td>Forbidden (authorization token does not have permission for the requested feed)</td></tr><tr><td><code>404</code></td><td>Not Found (no data found for the specified parameters)</td></tr></tbody></table>

### Example Requests

#### cUrl

```bash
curl -X GET "https://ai-hub.cryptobriefing.com/news?token={{token}}&feed_categories=crypto,ai_agents&page=1&limit=40&from_date=2025-05-10&to_date=2025-05-15"
```

#### Javascript

```javascript
const fetchNews = async () => {
  const response = await fetch(
    'https://ai-hub.cryptobriefing.com/news?token={{token}}&feed_categories=crypto,ai_agents&page=1&limit=40&from_date=2025-05-10&to_date=2025-05-15'
  );
  
  if (!response.ok) {
    throw new Error(`HTTP error! Status: ${response.status}`);
  }
  
  const data = await response.json();
  return data;
};

// Usage
(async () => {
  try {
    const newsItems = await fetchNews();
    console.log(`Received ${newsItems.length} news items`);
    newsItems.forEach(item => {
      console.log(`${new Date(item.timestamp * 1000).toLocaleString()}: ${item.signal}`);
    });
  } catch (error) {
    console.error('Error fetching news:', error);
  }
})();
```

***

## **WebSocket API**

### Overview

The WebSocket API provides real-time data feeds from various cryptocurrency and AI-related feeds. It allows to subscribe to specific data feeds and receive instant updates as new content becomes available.

### Connection

#### Endpoint

```url
wss://{{domain}}/ws/feed
```

#### Authentication

All WebSocket connections require authentication using an authorization token. You can provide it as a query parameter:

```url
wss://{{domain}}/ws/feed?token={{token}}
```

You can generate/manage your authorization tokens here: [https://app.itsgloria.ai/api-tokens](https://app.itsgloria.ai/api-tokens)

If an authorization token is not provided or is invalid, the connection will be closed immediately with a  `401 Unauthorized` response.

### Message Format

All messages exchanged between the client and server are in JSON format. Each message has a type field that indicates the message type.

#### Message Types

* `subscribe`: Subscribe to a specific feed
* `unsubscribe`: Unsubscribe from a specific feed
* `data`: Data message containing feed item information
* `error`: Error message
* `ping`: Ping message to keep connection alive
* `pong`: Response to a ping message

### Client to Server Messages

#### Subscribe to a Feed

To receive updates from a specific feed, send a subscribe message:

```json
{
    "type": "subscribe",
    "feed_category": "crypto"
}
```

The server will respond with a confirmation message:

```json
{
    "type": "data",
    "action": "subscribed",
    "feed_category": "crypto"
}
```

#### Feed Permissions

Each authorization token is associated with permissions for specific feed categories.

If at least one feed category you are trying to subscribe to is not in the list of allowed (specified during authorization token creation), you will receive an error message.

#### Unsubscribe from a Feed

To stop receiving updates from a feed:

```json
{
    "type": "unsubscribe",
    "feed_category": "crypto"
}
```

### Server to Client Messages

#### Welcome Message

Upon successful connection, the server sends a welcome message:

```json
{
    "type": "data",
    "message": "Connection established. Use subscribe/unsubscribe messages to manage feeds."
}
```

#### Data Message

When new content is available in a subscribed feed, the server sends a data message:

```json
{
    "type": "data",
    "content": {
        "id": "4582d10e-f32c-4701-bfd2-43be2263f177",
        "signal": "Pump Fun acquires Kolscan to enhance wallet tracking and onchain trading features",
        "timestamp": "2025-07-10T20:17:11.858099+00:00",
        "feed_category": "crypto",
        "short_context": "Pump Fun has acquired Kolscan to enhance its wallet tracking and onchain trading features. This move comes just before Pump Fun\u2019s major $PUMP token Initial Coin Offering (ICO), which aims to raise $1.32 billion by offering 33% of the total supply, with 18% allocated to private institutional buyers and 15% to public investors.",
        "long_context": "Facts\n\n- Pump Fun has acquired Kolscan to improve its **wallet tracking** and **onchain trading features**.\n- Pump Fun is a leading memecoin launchpad operating on the Solana network[3].\n- The acquisition comes just ahead of Pump Fun\u2019s major Initial Coin Offering (ICO) for its $PUMP token, scheduled for July 12, 2025[3].\n- The $PUMP ICO aims to raise $1.32 billion, offering 33% of the total supply (1 trillion tokens), with 18% allocated to private institutional buyers and 15% to public investors[3].\n- Recent activity around Pump Fun\u2019s token includes significant trading volumes on platforms like Hyperliquid and Binance, where open interest surged above $43 million on Hyperliquid and over $12 billion in trading volume was reported on Binance for PUMP perpetual contracts[2].\n\nWhy it matters\n\nThe acquisition of Kolscan signals Pump Fun's ambition to strengthen its position in the competitive memecoin ecosystem by providing more advanced analytics tools for traders. Enhanced wallet tracking and improved onchain trading capabilities can help retain users who might otherwise turn to specialized platforms with better data offerings. This move could also make Pump Fun more attractive ahead of its high-profile ICO by promising a richer feature set that supports active traders\u2014potentially boosting investor confidence as large amounts of capital prepare to enter the platform.\n\nZooming out\n\nMarket Trends:\n- Token discovery and analytics tools have become crucial differentiators among decentralized exchanges; competitors like DEX Screener reportedly generated over $100 million in revenue recently due largely to their advanced tracking features[1].\n  \nEcosystem Context:\n- On Solana, most transaction volume stems from memecoin trading or swaps between SOL and stablecoins, reflecting high user demand for sophisticated trade execution platforms[1].\n\nHistorical Comparison:\n- Major acquisitions targeting data or analytics have previously helped similar crypto projects grow their market share by owning more layers of the \"trading stack,\" consolidating user experience within one ecosystem instead of losing traffic to third-party tools[1].",
        "sources": "[\"https://blockworks.co/news/pumpfun-raise-acquisition-companies\", \"https://www.theblock.co/post/361975/pump-token-ico\", \"https://www.ainvest.com/news/pump-fun-announces-1-32-billion-ico-pump-token-july-12-2025-2507/\", \"https://wublock.substack.com/p/analysis-why-is-binance-rapidly-listing\", \"https://crypto.news/pump-fun-launch-pump-token-ico-on-july-12-2025/\"]"
    }
}
```

#### Error Message

If an error occurs, the server sends an error message:

```json
{
    "type": "error",
    "error": "Permission denied",
    "details": "No permission for crypto feed"
}
```

#### Ping/Pong

The server sends ping messages every 30 seconds to keep the connection alive:

```json
{
  "type": "ping",
  "timestamp": 1148216.120805222
}
```

Clients should respond with a pong message:

```json
{
  "type": "pong",
  "timestamp": 1148216.120805222
}
```

### Available Feeds

The following feeds are available for subscription:

* `ai_agents`: Updates related to AI agents and technologies
* `crypto`: General cryptocurrency news and updates
* `aptos`: Aptos blockchain specific updates
* `rwa`: Real World Asset updates
* `ondo`: Ondo Finance related updates
* `macro`: Macro news

### Error Handling

The server may close the connection with the following status codes:

* `1000`: Normal closure (server shutting down or inactive connection)
* `1008`: Policy violation (missing or invalid authorization token)

### Connection Lifecycle

1. Connect to the WebSocket endpoint with a valid authorization token
2. Receive the welcome message
3. Subscribe to desired feeds
4. Receive real-time updates
5. Respond to ping messages to keep the connection alive
6. Unsubscribe when no longer interested in a feed
7. The connection will be automatically closed after 5 minutes of inactivity

### Client Example (JavaScript)

```javascript
// Create WebSocket connection
const socket = new WebSocket('wss://ai-hub.cryptobriefing.com/ws/feed?token={{token}}');

// Connection opened
socket.addEventListener('open', (event) => {
  console.log('Connected to WebSocket server');
  
  // Subscribe to a feed
  socket.send(JSON.stringify({
    type: 'subscribe',
    feed_category: 'crypto'
  }));
});

// Listen for messages
socket.addEventListener('message', (event) => {
  const message = JSON.parse(event.data);
  
  switch(message.type) {
    case 'data':
      if (message.content) {
        // New news item received
        console.log(`WebSocketClient: New update for ${message.content.feed_category}:`, message.content.signal);
        this.emit('news', message.content);
      } else if (message.action === 'subscribed') {
        console.log(`WebSocketClient: Successfully subscribed to ${message.feed_category}`);
        this.emit('subscribed', message.feed_category);
      } else {
        console.log('WebSocketClient: Data message:', message);
      }
      break;
    case 'error':
      console.error('Error:', message.error, message.details);
      break;
    case 'ping':
      // Respond with pong to keep connection alive
      socket.send(JSON.stringify({
        type: 'pong',
        timestamp: message.timestamp
      }));
      break;
  }
});

// Handle connection close
socket.addEventListener('close', (event) => {
  console.log('Connection closed:', event.code, event.reason);
});

// Handle errors
socket.addEventListener('error', (event) => {
  console.error('WebSocket error:', event);
});
```

***
