# News API

News API access is available with data API keys, or separately from $129/mo. 

Please see the [subscription](https://velo.xyz/subscription) page in the webapp to get a key.

News objects contain the following fields:

```json
{
    id: 55, // unique identifier
    time: 1704085200000, // timestamp the news was published
    effectiveTime: 1704085200000, // timestamp the news happened
    headline: "Hello world",
    source: "Velo",
    priority: 2, // 1 = top priority only, 2 = everything else
    coins: ['BTC'], // list of relevant coins
    summary: "# Hello world", // may include markdown
    link: "https://velo.xyz" // source link
}
```

The WebSocket may also send edit events which will have all fields above plus `edit: true` , or delete events which will have only the following `{id: id, deleted: true}`.

***

### Python

<details>

<summary>Quick Start </summary>

```python
import asyncio
from velodata import lib as velo

# new velo client
client = velo.client('api_key')

# get past stories
print(client.news.get_news())

# stream new stories
async def stream():
    async for message in client.news.stream_news():
        if(message in ('connected', 'heartbeat', 'closed')):
            print(message)
        else:
            print(json.loads(message))
        
asyncio.run(stream())
```

</details>

<details>

<summary>Get news</summary>

`news.get_news(begin)`

* begin (optional, defaults to 0): millisecond timestamp to only fetch news after

Returns list of news objects (dicts)

</details>

<details>

<summary>Stream news</summary>

`news.stream_news()`

Returns generator, generator returns 'connected', 'heartbeat', 'closed', or news object (dict)

</details>

<details>

<summary>Close stream</summary>

`news.close_stream()`

Closes open websocket and exits generator

</details>

***

### NodeJS

<details>

<summary>Quick Start</summary>

```javascript
const velo = require('velo-node')

async function doWork() {

  // get past stories
  const stories = await client.news.stories()
  console.log(stories)

  // stream new stories
  const socket = client.news.stream()
  
  socket.on('open', () => console.log('connected'))
  socket.on('close', () => console.log('closed'))
  socket.on('error', (err) => { 
    console.log('error', err) 
    socket.close()
  })

  socket.on('message', (data) => {
    const json = JSON.parse(data.toString())
    if (json.heartbeat) {
      console.log('heartbeat')
      return
    }
    console.log(json)
  })
}

const client = new velo.Client('api_key')

doWork()
```

</details>

<details>

<summary>Get news</summary>

`news.stories({begin})`

* begin (optional, defaults to 0): millisecond timestamp to only fetch news after

Returns list of news Objects

</details>

<details>

<summary>Stream news</summary>

`news.stream()`

Returns [WebSocket](https://github.com/websockets/ws/blob/HEAD/doc/ws.md#class-websocket), WebSocket sends 'connected', 'heartbeat', 'closed', or news Object

</details>

***

### HTTP

<details>

<summary>Quick Start</summary>

`$ curl -v --user "api:api_key" "https://api.velo.xyz/api/n/news?begin=0"`

</details>

<details>

<summary>Get news</summary>

`/news`

* begin (optional, defaults to 0): millisecond timestamp to only fetch news after

Returns JSON

</details>