Skip to main content

​
Overview

The Agent Marketplace enables users to discover, favorite, and track their interactions with various AI trading agents. Each user has personalized preferences, usage statistics, and a curated collection of favorite agents.

​
Marketplace Features

​
User Preferences

Each user’s marketplace experience is personalized with:
  • Favorites: Quick access to preferred agents
  • Recent Agents: Recently used agents with context
  • Call Counts: Usage statistics per agent
  • Anonymous Tracking: Privacy-preserving user identification

​
Agent Discovery

Discover agents through:
  • Browse all available agents
  • Filter by category or capability
  • Sort by popularity or recent usage
  • Search by name or description

​
API Endpoints

​
Get User Preferences

Retrieve marketplace preferences for a user: 
const response = await fetch(
  `https://api.syraa.fun/v1/agent/marketplace/${anonymousId}`,
  {
    headers: { 'Authorization': `Bearer ${apiKey}` }
  }
);

const { favorites, recent, callCounts } = await response.json();
Response Structure: 
{
  "success": true,
  "favorites": ["agent-id-1", "agent-id-2"],
  "recent": [
    {
      "id": "agent-id-3",
      "title": "Market Analysis Agent",
      "prompt": "Analyze current market trends"
    }
  ],
  "callCounts": {
    "agent-id-1": 45,
    "agent-id-2": 23,
    "agent-id-3": 12
  }
}

​
Update Preferences

Update user marketplace preferences: 
const response = await fetch(
  `https://api.syraa.fun/v1/agent/marketplace/${anonymousId}`,
  {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      favorites: ['agent-id-1', 'agent-id-4'],
      recent: [
        {
          id: 'agent-id-5',
          title: 'Trading Signal Agent',
          prompt: 'Get latest SOL signal'
        }
      ],
      callCounts: {
        'agent-id-5': 1
      }
    })
  }
);

const { success, favorites, recent, callCounts } = await response.json();

​
User Preferences

​
Favorites Management

Manage your favorite agents: 
class MarketplacePreferences {
  constructor(anonymousId, apiKey) {
    this.anonymousId = anonymousId;
    this.apiKey = apiKey;
  }

  async addFavorite(agentId) {
    const prefs = await this.getPreferences();
    
    if (!prefs.favorites.includes(agentId)) {
      prefs.favorites.push(agentId);
      await this.updatePreferences({ favorites: prefs.favorites });
    }
  }

  async removeFavorite(agentId) {
    const prefs = await this.getPreferences();
    
    prefs.favorites = prefs.favorites.filter(id => id !== agentId);
    await this.updatePreferences({ favorites: prefs.favorites });
  }

  async getPreferences() {
    const response = await fetch(
      `https://api.syraa.fun/v1/agent/marketplace/${this.anonymousId}`,
      { headers: { 'Authorization': `Bearer ${this.apiKey}` } }
    );
    return await response.json();
  }

  async updatePreferences(updates) {
    const response = await fetch(
      `https://api.syraa.fun/v1/agent/marketplace/${this.anonymousId}`,
      {
        method: 'PUT',
        headers: {
          'Authorization': `Bearer ${this.apiKey}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify(updates)
      }
    );
    return await response.json();
  }
}

​
Recent Agents Tracking

The marketplace automatically tracks recently used agents: Recent Agent Structure: 
interface RecentAgent {
  id: string;           // Agent identifier
  title: string;        // Display name
  prompt: string;       // Last prompt used
}
Max Recent Agents: 10 (oldest entries are automatically removed)

​
Usage Statistics

Track how often you use each agent: 
async function getAgentUsageStats(anonymousId, apiKey) {
  const response = await fetch(
    `https://api.syraa.fun/v1/agent/marketplace/${anonymousId}`,
    { headers: { 'Authorization': `Bearer ${apiKey}` } }
  );
  
  const { callCounts } = await response.json();
  
  // Sort by usage
  const sorted = Object.entries(callCounts)
    .sort(([, a], [, b]) => b - a)
    .map(([id, count]) => ({ id, count }));
  
  return sorted;
}

​
Anonymous User Identification

​
Anonymous ID

Users are identified by an anonymous ID:
  • Privacy: No personal information required
  • Persistence: Stored locally on user device
  • Portability: Can be exported/imported across devices

​
Creating Anonymous ID

function generateAnonymousId() {
  // Use existing ID from local storage
  let anonymousId = localStorage.getItem('syra_anonymous_id');
  
  if (!anonymousId) {
    // Generate new UUID
    anonymousId = crypto.randomUUID();
    localStorage.setItem('syra_anonymous_id', anonymousId);
  }
  
  return anonymousId;
}

​
Data Management

​
Partial Updates

Update specific fields without affecting others: 
// Only update favorites, leave recent and callCounts unchanged
await fetch(
  `https://api.syraa.fun/v1/agent/marketplace/${anonymousId}`,
  {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      favorites: ['new-agent-1', 'new-agent-2']
      // recent and callCounts remain unchanged
    })
  }
);

​
Data Validation

The API validates all updates:
  • Favorites: Array of strings (agent IDs)
  • Recent: Array of objects with id, title, prompt
  • Call Counts: Object with agent IDs as keys, numbers as values
  • Max Recent: Limited to 10 entries
Invalid data is normalized during save. Empty or invalid fields are converted to appropriate defaults.

​
Use Cases

​
Personalized Dashboard

Build a dashboard with favorite agents: 
async function buildDashboard(anonymousId, apiKey) {
  const { favorites, recent, callCounts } = 
    await getMarketplacePreferences(anonymousId, apiKey);
  
  return {
    favoriteAgents: await loadAgentDetails(favorites),
    recentlyUsed: recent,
    topAgents: Object.entries(callCounts)
      .sort(([, a], [, b]) => b - a)
      .slice(0, 5)
  };
}

​
Usage Analytics

Track your agent usage patterns: 
async function analyzeUsage(anonymousId, apiKey) {
  const { callCounts } = await getMarketplacePreferences(anonymousId, apiKey);
  
  const totalCalls = Object.values(callCounts)
    .reduce((sum, count) => sum + count, 0);
  
  const uniqueAgents = Object.keys(callCounts).length;
  
  const avgCallsPerAgent = totalCalls / uniqueAgents;
  
  return {
    totalCalls,
    uniqueAgents,
    avgCallsPerAgent,
    mostUsedAgent: Object.entries(callCounts)
      .sort(([, a], [, b]) => b - a)[0]
  };
}

​
Quick Access

Implement quick access to favorite agents: 
class QuickAccess {
  constructor(anonymousId, apiKey) {
    this.prefs = new MarketplacePreferences(anonymousId, apiKey);
  }

  async getFavorites() {
    const { favorites } = await this.prefs.getPreferences();
    return favorites;
  }

  async toggleFavorite(agentId) {
    const { favorites } = await this.prefs.getPreferences();
    
    if (favorites.includes(agentId)) {
      await this.prefs.removeFavorite(agentId);
      return false; // Removed
    } else {
      await this.prefs.addFavorite(agentId);
      return true; // Added
    }
  }
}

​
Integration Example

import { v4 as uuidv4 } from 'uuid';

class MarketplaceManager {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.anonymousId = this.getOrCreateAnonymousId();
    this.baseUrl = 'https://api.syraa.fun/v1/agent/marketplace';
  }

  getOrCreateAnonymousId() {
    let id = localStorage.getItem('syra_anonymous_id');
    if (!id) {
      id = uuidv4();
      localStorage.setItem('syra_anonymous_id', id);
    }
    return id;
  }

  async getPreferences() {
    const response = await fetch(
      `${this.baseUrl}/${this.anonymousId}`,
      { headers: { 'Authorization': `Bearer ${this.apiKey}` } }
    );
    return await response.json();
  }

  async recordAgentCall(agentId, title, prompt) {
    const prefs = await this.getPreferences();
    
    // Update call count
    const callCounts = { ...prefs.callCounts };
    callCounts[agentId] = (callCounts[agentId] || 0) + 1;
    
    // Update recent (keep max 10)
    const recent = [
      { id: agentId, title, prompt },
      ...prefs.recent.filter(r => r.id !== agentId)
    ].slice(0, 10);
    
    // Save updates
    await fetch(
      `${this.baseUrl}/${this.anonymousId}`,
      {
        method: 'PUT',
        headers: {
          'Authorization': `Bearer ${this.apiKey}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({ recent, callCounts })
      }
    );
  }

  async toggleFavorite(agentId) {
    const prefs = await this.getPreferences();
    let favorites = [...prefs.favorites];
    
    const index = favorites.indexOf(agentId);
    if (index > -1) {
      favorites.splice(index, 1);
    } else {
      favorites.push(agentId);
    }
    
    await fetch(
      `${this.baseUrl}/${this.anonymousId}`,
      {
        method: 'PUT',
        headers: {
          'Authorization': `Bearer ${this.apiKey}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({ favorites })
      }
    );
    
    return favorites.includes(agentId);
  }
}

// Usage
const marketplace = new MarketplaceManager(process.env.SYRA_API_KEY);

// Record agent usage
await marketplace.recordAgentCall(
  'signal-agent',
  'Trading Signal Agent',
  'Get SOL signal'
);

// Toggle favorite
const isFavorite = await marketplace.toggleFavorite('signal-agent');
console.log(`Agent is ${isFavorite ? 'now' : 'no longer'} a favorite`);

​
Best Practices

Sync preferences across devices by exporting/importing the anonymous ID.
  1. Privacy First: Never expose anonymous IDs publicly
  2. Local Storage: Persist anonymous ID locally
  3. Incremental Updates: Update only changed fields
  4. Usage Tracking: Record all agent interactions
  5. Favorites Limit: Consider limiting favorites to 20-30 for UX

​
Error Handling

async function safeUpdatePreferences(anonymousId, apiKey, updates) {
  try {
    const response = await fetch(
      `https://api.syraa.fun/v1/agent/marketplace/${anonymousId}`,
      {
        method: 'PUT',
        headers: {
          'Authorization': `Bearer ${apiKey}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify(updates)
      }
    );
    
    if (!response.ok) {
      throw new Error(`HTTP ${response.status}`);
    }
    
    return await response.json();
  } catch (error) {
    console.error('Failed to update preferences:', error);
    // Fallback to local storage
    localStorage.setItem(
      'syra_preferences_pending',
      JSON.stringify(updates)
    );
    return null;
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us