ƒxyz Network Documentation

Telegram bot integration, Fixie AI chat, real-time notifications, and messaging on fXYZ Network

Communication Infrastructure

fXYZ Network provides multiple communication channels for users to interact with the platform, AI agents, and each other.

Telegram Integration

Bot Overview

The network operates a Telegram bot for mobile-first access:

Feature	Description
Authentication	Login via Telegram
Agent Chat	Talk to Fixie AI agents
Notifications	Receive alerts and updates
Commands	Quick actions via slash commands

Bot Commands

Command	Description
`/start`	Initialize bot conversation
`/help`	Show available commands
`/agents`	List available Fixie agents
`/agent <id>`	Select agent to chat with

Webhook Setup

The bot uses webhook-based message handling:

# Configure webhook
POST /api/telegram/setup
Content-Type: application/json

{
  "action": "set",
  "url": "https://api.fxyz.network/api/telegram/webhook"
}

# Webhook receives updates
POST /api/telegram/webhook
X-Telegram-Bot-Api-Secret-Token: <webhook-secret>

{
  "message": {
    "chat": { "id": 123456789 },
    "text": "/start",
    "from": { "id": 987654321, "username": "user" }
  }
}

Message Flow

User sends message to Telegram bot
Telegram delivers to webhook endpoint
Handler validates secret token
Message routed to selected Fixie agent
Agent response sent back to user

Telegram Login: Users can authenticate with Telegram as their primary login method, receiving embedded wallets automatically.

Fixie AI Chat

Chat Interface

The platform provides real-time chat with AI agents:

Feature	Technology
Streaming	Server-Sent Events (SSE)
UI Framework	Vercel AI SDK
Memory	Letta persistent memory
Tools	Neo4j queries, web search

Chat Endpoint

POST /api/fixie/{agentId}/stream
Authorization: Bearer <privy-jwt>
Content-Type: application/json

{
  "message": "What is the current market sentiment?"
}

Response (SSE stream):

data: {"type":"reasoning","content":"Analyzing market data..."}
data: {"type":"text","content":"Based on recent price movements..."}
data: {"type":"tool_call","name":"neo4j_query","args":{...}}
data: {"type":"tool_result","content":"..."}
data: {"type":"text","content":"The market sentiment appears..."}
data: {"type":"done"}

React Integration

import { useChat } from '@ai-sdk/react';

function FixieChat({ agentId }: { agentId: string }) {
  const { messages, input, handleInputChange, handleSubmit } = useChat({
    api: `/api/fixie/${agentId}/stream`,
  });

  return (
    <div>
      {messages.map((m) => (
        <div key={m.id}>
          <strong>{m.role}:</strong> {m.content}
        </div>
      ))}
      <form onSubmit={handleSubmit}>
        <input value={input} onChange={handleInputChange} />
        <button type="submit">Send</button>
      </form>
    </div>
  );
}

Agent Memory

Fixie agents maintain conversation history and memory:

// Memory operations (via Letta)
engine.onTrade = async (trade) => {
  await agent.addMemory({
    type: 'trade',
    content: `Trade executed: ${trade.quantity} @ ${trade.price}`,
    timestamp: new Date(),
  });
};

// Memory search
const relevant = await agent.searchMemory({
  query: 'price predictions',
  limit: 5,
});

Real-Time Notifications

Notification Types

Type	Channel	Description
Transaction	In-app, Telegram	Token transfers, trades
Membership	In-app, Email	Tier changes, NFT claims
Governance	In-app, Telegram	Proposals, votes
Market	In-app	Price alerts, arbitrage

In-App Notifications

// Notification component
import { Bell } from 'lucide-react';
import { useNotifications } from '@/hooks/use-notifications';

function NotificationBell() {
  const { notifications, unreadCount, markAsRead } = useNotifications();

  return (
    <Popover>
      <PopoverTrigger>
        <Bell />
        {unreadCount > 0 && <Badge>{unreadCount}</Badge>}
      </PopoverTrigger>
      <PopoverContent>
        {notifications.map((n) => (
          <NotificationItem key={n.id} notification={n} />
        ))}
      </PopoverContent>
    </Popover>
  );
}

Push via Telegram

For users with Telegram linked:

// Send notification to Telegram
async function notifyUser(userId: string, message: string) {
  const user = await getUser(userId);
  if (user.telegramChatId) {
    await telegram.sendMessage(user.telegramChatId, message);
  }
}

WebSocket Communication

Real-Time Updates

WebSocket connection for live data:

const ws = new WebSocket('wss://api.fxyz.network/ws');

// Authentication
ws.onopen = () => {
  ws.send(JSON.stringify({
    action: 'auth',
    token: privyToken,
  }));
};

// Subscribe to channels
ws.send(JSON.stringify({
  action: 'subscribe',
  channels: ['orderbook:FLORIN-USDC', 'trades', 'notifications'],
}));

// Handle messages
ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  switch (msg.type) {
    case 'ORDER_BOOK_UPDATE':
      updateOrderBook(msg.data);
      break;
    case 'TRADE':
      addTrade(msg.data);
      break;
    case 'NOTIFICATION':
      showNotification(msg.data);
      break;
  }
};

Event Types

Event	Payload	Description
`ORDER_BOOK_UPDATE`	`{ bids, asks, sequence }`	Order book changes
`TRADE`	`{ price, quantity, side }`	New trade executed
`TICKER`	`{ lastPrice, volume24h }`	Ticker update
`NOTIFICATION`	`{ type, title, message }`	User notification
`BALANCE_UPDATE`	`{ asset, balance }`	Balance change

Email Communication

Transactional Emails

For users with email linked:

Email Type	Trigger
Welcome	Account creation
KYC Status	Verification updates
Transaction	Large transfers (optional)
Security	Login from new device

Email Templates

Located in packages/email/templates/:

// packages/email/templates/contact.tsx
import { Html, Body, Container, Text } from '@react-email/components';

export function ContactEmail({ name, message }: Props) {
  return (
    <Html>
      <Body>
        <Container>
          <Text>New contact from {name}</Text>
          <Text>{message}</Text>
        </Container>
      </Body>
    </Html>
  );
}

API Communication

GraphQL Subscriptions

Real-time updates via GraphQL subscriptions:

subscription OnTradeExecuted($pairId: String!) {
  tradeExecuted(pairId: $pairId) {
    id
    price
    quantity
    side
    timestamp
  }
}

subscription OnOrderUpdate($userId: String!) {
  orderUpdate(userId: $userId) {
    id
    status
    filledQuantity
  }
}

REST Polling (Fallback)

For clients without WebSocket support:

// Poll for updates
async function pollPrices() {
  const response = await fetch('/api/prices');
  const prices = await response.json();
  updateUI(prices);
}

// Poll every 30 seconds
setInterval(pollPrices, 30000);

Security

Message Authentication

All communication channels validate:

Channel	Authentication
Telegram	Webhook secret token
WebSocket	JWT token on connect
GraphQL	Bearer token header
REST	Bearer token header

Rate Limiting

Channel	Limit
Telegram commands	30/minute
Chat messages	60/minute
WebSocket messages	100/minute
API requests	1000/hour

Encryption

TLS 1.3 for all external traffic
Telegram bot API uses HTTPS
WebSocket connection upgraded from HTTPS

Integration Points

Available Integrations

Platform	Status	Features
Telegram	Live	Login, chat, notifications
Discord	Planned	Community, alerts
Slack	Planned	Enterprise notifications
Email	Live	Transactional

Custom Integrations

Build custom communication integrations:

// Webhook integration example
app.post('/api/integrations/custom', async (req, res) => {
  const { event, data } = req.body;

  // Validate webhook signature
  if (!validateSignature(req)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Process event
  switch (event) {
    case 'transaction':
      await processTransaction(data);
      break;
    case 'alert':
      await sendAlert(data);
      break;
  }

  res.json({ received: true });
});

Communication

On this page