Skip to main content

Overview

The 8004 Trustless Agent Registry is a Solana-based registry that makes AI agents discoverable on-chain. Registering Syra on 8004 enables:
  • Agent Discovery — Users can find Syra through on-chain registry queries
  • Service Metadata — Advertise capabilities, endpoints, and payment requirements
  • Collection Management — Group multiple Syra agents under a single collection
  • Reputation System — Optional ATOM reputation engine integration
Registry Documentation: 8004.qnt.sh/skill.md

What is 8004?

8004 is an on-chain agent registry that:
  • Stores agent metadata on IPFS
  • Creates agent NFTs on Solana
  • Enables trustless discovery via on-chain queries
  • Supports agent collections for organizing multiple agents
  • Integrates with ATOM reputation tracking (optional)

Prerequisites

Before registering Syra on 8004:
1

Solana Wallet

Set up a Solana signer in .env:Option 1: JSON Array (recommended)
SOLANA_PRIVATE_KEY="[1,2,3,...,64]"
Option 2: Base58 Encoded
AGENT_PRIVATE_KEY="base58_encoded_key"
# or
ZAUTH_SOLANA_PRIVATE_KEY="base58_encoded_key"
Option 3: Existing Payer
PAYER_KEYPAIR="[1,2,3,...,64]"
2

Pinata API Key

Create a Pinata account and generate a JWT:
PINATA_JWT="your_pinata_jwt_token"
This is used to pin agent metadata to IPFS.
3

Optional: Agent Image

Set a custom image URI (IPFS or HTTPS):
SYRA_AGENT_IMAGE_URI="ipfs://..."
# or
SYRA_AGENT_IMAGE_URI="https://syraa.fun/images/logo.jpg"
Defaults to Syra logo if not set.
4

Optional: Network Selection

Choose Solana cluster (defaults to mainnet-beta):
SOLANA_CLUSTER="devnet"
# or
SOLANA_CLUSTER="mainnet-beta"
5

Optional: ATOM Reputation

Enable ATOM reputation engine (irreversible):
8004_ATOM_ENABLED=true

Registration Methods

1. Register Single Agent

Register a new Syra agent on 8004:
cd api
npm run register-8004
What happens:
  1. Generates agent metadata (name, description, services, skills)
  2. Uploads metadata to IPFS via Pinata
  3. Creates agent NFT on Solana
  4. Prints agent asset address and transaction signature
Output:
✅ Agent registered successfully!
Agent Asset: 8aJwH76QsQe5uEAxbFXha24toSUKjHxsdCk4BRuKERYx
Transaction: 5X7h9...
Token URI: ipfs://bafkreid...
Save the Agent Asset address — you’ll need it for future operations like setAgentUri or giveFeedback.

2. Create Agent Collection

After registering an agent, create a collection to group multiple Syra agents:
cd api
npm run create-8004-collection
Configuration:
# Required: Agent asset from registration
SYRA_AGENT_ASSET="8aJwH76QsQe5uEAxbFXha24toSUKjHxsdCk4BRuKERYx"

# Optional: Collection branding
SYRA_COLLECTION_IMAGE_URI="ipfs://..."
SYRA_COLLECTION_EXTERNAL_URL="https://syraa.fun"
SYRA_COLLECTION_X_URL="https://x.com/syra_agent"
SYRA_COLLECTION_BANNER_URI="ipfs://..."  # Optional
Output:
✅ Collection created and attached!
Collection Pointer: c1:bafkreid3g6kogo55n5iob7pi36xppcycynn7m64pds7wshnankxjo52mfm
Transaction: 4Y8f2...

3. Register Agent + Collection (One Command)

Register a new agent and attach it to a collection in one step:
cd api
npm run register-8004-with-collection
Two modes:
# Attach to existing Syra collection
SYRA_COLLECTION_POINTER="c1:bafkreid3g6kogo55n5iob7pi36xppcycynn7m64pds7wshnankxjo52mfm"
Creates new agent and attaches the existing collection pointer.

4. API Endpoint (Dynamic Registration)

Create agents programmatically via API: Endpoint: POST /8004/register-agent Payment: Requires x402 payment (or use /8004/dev/register-agent in dev mode) Request Body:
{
  "name": "Syra Research Agent",
  "description": "AI-powered trading intelligence for Solana",
  "image": "https://syraa.fun/images/logo.jpg",
  "services": [
    {
      "type": "MCP",
      "value": "https://api.syraa.fun"
    }
  ],
  "skills": ["trading-analysis", "market-research", "token-screening"],
  "domains": ["finance", "defi"],
  "x402Support": true,
  "collectionPointer": "c1:bafkreid3g6kogo55n5iob7pi36xppcycynn7m64pds7wshnankxjo52mfm"
}
Response (201):
{
  "asset": "9bKwH87RtRf6vFBybGXib35upTVLkHyteEl5CSvLFSZy",
  "registerSignature": "6Y9g3...",
  "tokenUri": "ipfs://bafkreibh...",
  "setCollectionSignature": "3X5h1..."  // if collectionPointer was provided
}
First request without payment returns 402 Payment Required with payment details. Complete payment and retry with payment header.

Agent Metadata

Registered agents include the following metadata:

Core Fields

{
  "name": "Syra",
  "description": "AI Trading Intelligence Agent for Solana",
  "image": "ipfs://bafkreih...",
  "external_url": "https://syraa.fun",
  "attributes": [
    {
      "trait_type": "Agent Type",
      "value": "Research & Trading Intelligence"
    },
    {
      "trait_type": "Blockchain",
      "value": "Solana"
    }
  ]
}

Services

{
  "services": [
    {
      "type": "MCP",
      "value": "https://api.syraa.fun"
    },
    {
      "type": "Telegram",
      "value": "https://t.me/syra_trading_bot"
    },
    {
      "type": "Web",
      "value": "https://agent.syraa.fun"
    }
  ]
}

Skills & Domains

{
  "skills": [
    "trading-signals",
    "market-research",
    "sentiment-analysis",
    "token-screening",
    "on-chain-analysis"
  ],
  "domains": [
    "finance",
    "defi",
    "trading"
  ]
}

Collection Management

Why Use Collections?

  • Organization — Group related agents (e.g., “Syra Trading Agents”)
  • Branding — Unified visual identity across agents
  • Discovery — Users can find all agents in a collection
  • Social Links — Attach X/Twitter, website, documentation links

Collection Metadata

{
  "name": "Syra Agents",
  "description": "Official collection of Syra AI trading agents",
  "image": "ipfs://bafkreid...",
  "external_url": "https://syraa.fun",
  "banner_image": "ipfs://bafkreie...",
  "x_url": "https://x.com/syra_agent"
}

Add Agent to Existing Collection

When registering new agents, include the collection pointer:
# Set in .env before running register-8004-with-collection
SYRA_COLLECTION_POINTER="c1:bafkreid3g6kogo55n5iob7pi36xppcycynn7m64pds7wshnankxjo52mfm"
Or via API:
{
  "name": "Syra Memecoin Scanner",
  "description": "Specialized memecoin screening agent",
  "collectionPointer": "c1:bafkreid3g6kogo55n5iob7pi36xppcycynn7m64pds7wshnankxjo52mfm"
}

ATOM Reputation Engine

Optionally enable the ATOM reputation system:
8004_ATOM_ENABLED=true
Irreversible: Once enabled, ATOM reputation cannot be disabled for that agent.
Benefits:
  • Track agent performance on-chain
  • User feedback influences reputation score
  • Reputation affects discoverability and trust
Trade-offs:
  • Permanent on-chain record
  • Negative feedback impacts reputation
  • Additional transaction complexity

Querying Registered Agents

Find Agents by Service Type

import { Connection, PublicKey } from '@solana/web3.js';

const connection = new Connection('https://api.mainnet-beta.solana.com');

// Query agents providing MCP service
const agents = await connection.getProgramAccounts(
  new PublicKey('8004_PROGRAM_ID'),
  {
    filters: [
      {
        memcmp: {
          offset: 0,
          bytes: 'MCP',
        },
      },
    ],
  }
);

Fetch Agent Metadata

// Given an agent asset address
const agentAsset = new PublicKey('8aJwH76QsQe5uEAxbFXha24toSUKjHxsdCk4BRuKERYx');

// Fetch on-chain data
const agentData = await connection.getAccountInfo(agentAsset);

// Parse token URI from account data
const tokenUri = parseTokenUri(agentData);

// Fetch IPFS metadata
const metadata = await fetch(tokenUri.replace('ipfs://', 'https://ipfs.io/ipfs/'));
const agentMetadata = await metadata.json();

console.log(agentMetadata);
// {
//   "name": "Syra",
//   "description": "AI Trading Intelligence Agent",
//   "services": [...],
//   ...
// }

Update Agent Metadata

To update an existing agent:
  1. Update metadata — Modify agent info locally
  2. Upload to IPFS — Pin new metadata via Pinata
  3. Call setAgentUri — Update on-chain URI to new IPFS hash
import { setAgentUri } from '@8004/sdk';

const newUri = 'ipfs://bafkreinew...';
const signature = await setAgentUri(
  connection,
  payer,
  agentAsset,
  newUri
);

Integration with Syra Ecosystem

Registering on 8004 enables:
  • Cross-agent Discovery — Other agents can find and call Syra services
  • Marketplace Listing — Appear in agent marketplaces and directories
  • Reputation Building — Accumulate on-chain feedback and reputation
  • Service Advertising — Advertise MCP, Telegram, API endpoints

Connected Services

Registered Syra agents link to:

Troubleshooting

  • Ensure wallet has enough SOL for:
    • Agent NFT creation (~0.01 SOL)
    • Transaction fees (~0.0001 SOL)
    • IPFS pinning is free via Pinata
  • Verify PINATA_JWT is correct
  • Check Pinata account is active
  • Ensure metadata size is under limits
  • Try generating a new JWT
  • Verify SYRA_AGENT_ASSET is correct
  • Ensure you own the agent NFT
  • Check wallet has authority to modify agent
  • Verify collection pointer format: c1:bafkrei...
  • Allow time for on-chain indexing
  • Verify transaction was confirmed
  • Check agent metadata uploaded to IPFS
  • Ensure services array is properly formatted

Best Practices

Recommendations:
  • Test on devnet first — Set SOLANA_CLUSTER=devnet for initial registration
  • Use collections — Group related agents for better organization
  • Complete metadata — Fill all fields for better discoverability
  • Monitor reputation — Enable ATOM if you want on-chain feedback
  • Update regularly — Keep agent URI current as services evolve

Next Steps

MCP Server

Expose Syra as MCP tools

x402 Agent

Deploy autonomous agents

API Playground

Test agent capabilities

n8n Workflows

Automate agent operations

Build docs developers (and LLMs) love