# WebSocket API Reference

> **Note:** The `api.noderr.xyz` public REST/GraphQL/WebSocket API is not yet live. This page documents the planned interface. For the currently live API, see the [Agent Protocol API Reference](../for-ai-agents/api-reference.md) at `https://agent.noderr.xyz`.

The Noderr Protocol WebSocket API provides real-time streaming data for vault metrics, strategy updates, and protocol events.

## Connection

```javascript
const ws = new WebSocket('wss://ws.noderr.xyz/v1');
```

For testnet:
```javascript
const ws = new WebSocket('wss://ws-testnet.noderr.xyz/v1');
```

## Message Format

All messages use JSON format:

```json
{
  "type": "subscribe",
  "channel": "vault.updates",
  "params": {
    "address": "0xd62f6c4Fe1444Dafbe3dBd0163C4B77A3C41Af84"
  }
}
```

## Channels

### Vault Updates

Subscribe to real-time vault metrics:

```json
{
  "type": "subscribe",
  "channel": "vault.updates",
  "params": {
    "address": "0xd62f6c4Fe1444Dafbe3dBd0163C4B77A3C41Af84"
  }
}
```

**Events:**
```json
{
  "channel": "vault.updates",
  "event": "tvl_change",
  "data": {
    "address": "0xd62f6c4Fe1444Dafbe3dBd0163C4B77A3C41Af84",
    "tvl": "1250000000000000000000",
    "pricePerShare": "1041666666666666666",
    "timestamp": 1703721600
  }
}
```

### Vault Transactions

Subscribe to deposit/withdraw events:

```json
{
  "type": "subscribe",
  "channel": "vault.transactions",
  "params": {
    "address": "0xd62f6c4Fe1444Dafbe3dBd0163C4B77A3C41Af84"
  }
}
```

**Events:**
- `deposit_requested` - New deposit request (ERC-7540)
- `deposit_fulfilled` - Deposit fulfilled by validator
- `deposit_claimed` - User claimed shares
- `redeem_requested` - New redeem request
- `redeem_fulfilled` - Redeem fulfilled
- `redeem_claimed` - User claimed assets

### Strategy Updates

Subscribe to strategy performance updates:

```json
{
  "type": "subscribe",
  "channel": "strategy.updates"
}
```

### Node Network

Subscribe to node status updates:

```json
{
  "type": "subscribe",
  "channel": "nodes.status"
}
```

### Protocol Metrics

Subscribe to aggregate protocol metrics:

```json
{
  "type": "subscribe",
  "channel": "protocol.metrics"
}
```

## Heartbeat

The server sends heartbeat messages every 30 seconds:

```json
{
  "type": "heartbeat",
  "timestamp": 1703721600
}
```

Respond with:
```json
{
  "type": "pong"
}
```

## Unsubscribe

```json
{
  "type": "unsubscribe",
  "channel": "vault.updates",
  "params": {
    "address": "0xd62f6c4Fe1444Dafbe3dBd0163C4B77A3C41Af84"
  }
}
```

## Error Handling

```json
{
  "type": "error",
  "code": "INVALID_CHANNEL",
  "message": "Channel not found"
}
```

## Example: JavaScript Client

```javascript
const ws = new WebSocket('wss://ws.noderr.xyz/v1');

ws.onopen = () => {
  // Subscribe to vault updates
  ws.send(JSON.stringify({
    type: 'subscribe',
    channel: 'vault.updates',
    params: {
      address: '0xd62f6c4Fe1444Dafbe3dBd0163C4B77A3C41Af84'
    }
  }));
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  
  if (data.type === 'heartbeat') {
    ws.send(JSON.stringify({ type: 'pong' }));
    return;
  }
  
  console.log('Received:', data);
};

ws.onerror = (error) => {
  console.error('WebSocket error:', error);
};
```

---

*Last Updated: December 2025*