Overview The Arcana Agent Marketplace consists of 7 specialized agents , each providing domain-specific crypto intelligence through paid x402 endpoints. Every agent is independently priced and optimized for its specific use case.
x402 Architecture All agents use HTTP 402 payment protocol on Base Sepolia
Agent Catalog Oracle Agent
Price Oracle Price: $0.01 per callAgent ID: oracleEndpoints:
GET /api/x402/oracle/price?symbol=BTCPOST /api/x402/oracle/prices (batch) What It Does Provides real-time cryptocurrency price data from CoinGecko, supporting 500+ tokens.
Features
Example
Supported Tokens
Token Prices : Current USD price for any supported tokenMarket Data : 24h price change, market cap, volumeBatch Queries : Fetch multiple prices in one callSymbol Mapping : Supports common symbols (BTC, ETH, SOL, etc.)Cache : 30-second cache to reduce API costs Request: GET /api/x402/oracle/price?symbol=BTC
Response: { "success" : true , "data" : { "symbol" : "BTC" , "name" : "Bitcoin" , "price" : 97234.50 , "currency" : "USD" , "change24h" : 2.34 , "marketCap" : 1920000000000 , "volume24h" : 45000000000 , "lastUpdated" : "2026-03-03T10:15:00Z" }, "payment" : { "amount" : "$0.01" , "network" : "eip155:84532" , "payTo" : "0xbaFF2E0939f89b53d4caE023078746C2eeA6E2F7" } }
Top 50 by Market Cap:
Bitcoin (BTC), Ethereum (ETH), Tether (USDT), XRP, BNB
Solana (SOL), Cardano (ADA), Dogecoin (DOGE), Avalanche (AVAX)
Polkadot (DOT), Polygon (MATIC/POL), Chainlink (LINK)
Uniswap (UNI), Litecoin (LTC), Cosmos (ATOM), Arbitrum (ARB)
DeFi:
Aave (AAVE), Curve (CRV), Compound (COMP), Synthetix (SNX)
MakerDAO (MKR), Yearn (YFI), GMX, Pendle
Layer 2:
Optimism (OP), zkSync (ZK), Starknet (STRK), Mantle (MNT)
And 450+ more… See backend/src/services/price-oracle.ts for full list. Data Source: CoinGecko API (free tier, no API key required)
Scout Agent
Chain Scout Price: $0.01 per callAgent ID: scoutEndpoints:
GET /api/x402/scout/analyze?address=0x...GET /api/x402/scout/gasGET /api/x402/scout/gas-estimate?operation=eth_transferGET /api/x402/scout/dex?chain=ethereumGET /api/x402/scout/protocol?protocol=uniswapGET /api/x402/scout/bridgesGET /api/x402/scout/hacks What It Does Provides on-chain analytics, gas prices, wallet analysis, and DeFi protocol intelligence.
Wallet Analytics
Gas & Fees
DeFi Intelligence
Security
Endpoint: /scout/analyze?address=0x...Analyzes Ethereum wallets using Alchemy:
Token balances and portfolio value
NFT holdings
Transaction history
ENS domain resolution
Example Response: { "address" : "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" , "ensName" : "vitalik.eth" , "tokens" : [ { "symbol" : "ETH" , "balance" : "123.45" , "value" : 234567.89 }, { "symbol" : "USDC" , "balance" : "50000" , "value" : 50000 } ], "nfts" : [ { "collection" : "Bored Ape Yacht Club" , "count" : 1 } ], "totalValue" : 284567.89 }
Current Gas Prices: /scout/gas{ "slow" : { "gwei" : 20 , "usd" : 0.84 }, "standard" : { "gwei" : 25 , "usd" : 1.05 }, "fast" : { "gwei" : 30 , "usd" : 1.26 }, "instant" : { "gwei" : 35 , "usd" : 1.47 } }
Gas Estimates: /scout/gas-estimate?operation=swap{ "operation" : "uniswap_swap" , "estimatedGas" : 180000 , "costs" : { "slow" : { "eth" : 0.0036 , "usd" : 8.64 }, "fast" : { "eth" : 0.0054 , "usd" : 12.96 } } }
Protocol Stats: /scout/protocol?protocol=aave{ "protocol" : "Aave" , "tvl" : 12500000000 , "tvlChange24h" : 2.3 , "chains" : [ "ethereum" , "polygon" , "arbitrum" , "optimism" ], "fees24h" : 450000 , "revenue24h" : 135000 }
DEX Volume: /scout/dex?chain=ethereum{ "chain" : "ethereum" , "totalVolume24h" : 3200000000 , "topDexs" : [ { "name" : "Uniswap" , "volume24h" : 1800000000 }, { "name" : "Curve" , "volume24h" : 890000000 } ] }
Bridge Activity: /scout/bridges{ "topBridges" : [ { "name" : "Stargate" , "volume24h" : 45000000 , "chains" : 7 }, { "name" : "Across" , "volume24h" : 32000000 , "chains" : 5 } ] }
Recent Hacks: /scout/hacks{ "recentHacks" : [ { "date" : "2026-03-01" , "protocol" : "Example Protocol" , "amount" : 5000000 , "type" : "Smart Contract Exploit" } ] }
Data Sources: Alchemy API (wallet analytics), Etherscan (gas), DeFiLlama (protocols, TVL)
News Agent
News Scout Price: $0.01 per callAgent ID: newsEndpoints:
GET /api/x402/news/latest?limit=10GET /api/x402/news/search?query=bitcoin&limit=10GET /api/x402/news/breakingGET /api/x402/news/trending What It Does Aggregates real-time crypto news from multiple sources with sentiment analysis and trending topics.
Latest News
Search & Filter
Breaking News
Trending Topics
Endpoint: /news/latest?limit=10Returns the most recent crypto news articles: { "articles" : [ { "title" : "Bitcoin Surges Past $97K on ETF Inflows" , "link" : "https://..." , "description" : "Bitcoin reached new highs today..." , "pubDate" : "2026-03-03T10:30:00Z" , "source" : "CoinDesk" , "category" : "Market" , "timeAgo" : "5m ago" } ], "totalCount" : 247 , "sources" : [ "CoinDesk" , "Decrypt" , "The Block" ], "fetchedAt" : "2026-03-03T10:35:00Z" }
Endpoint: /news/search?query=ethereum&limit=5Search news by keyword: { "articles" : [ { "title" : "Ethereum Gas Fees Drop to 6-Month Low" , "description" : "Layer 2 adoption driving efficiency..." , "source" : "CoinTelegraph" , "timeAgo" : "2h ago" } ] }
Common Queries:
defi - DeFi protocol newsregulation - Regulatory updateshack - Security incidentsToken symbols (BTC, ETH, SOL)
Endpoint: /news/breakingReturns high-priority news from the last 15 minutes: { "articles" : [ { "title" : "🚨 Major Exchange Announces USDC Support" , "pubDate" : "2026-03-03T10:20:00Z" , "timeAgo" : "15m ago" } ] }
Endpoint: /news/trendingSentiment analysis on trending topics: { "trending" : [ { "topic" : "Bitcoin ETF" , "count" : 45 , "sentiment" : "bullish" , "recentHeadlines" : [ "Bitcoin ETF Sees Record Inflows" ] }, { "topic" : "Ethereum Upgrade" , "count" : 32 , "sentiment" : "neutral" } ], "timeWindow" : "24h" , "articlesAnalyzed" : 892 }
Data Source: cryptocurrency.cv API (free, no API key required)
Yield Agent
Yield Optimizer Price: $0.01 per callAgent ID: yieldEndpoints:
GET /api/x402/yield/top?chain=ethereum&limit=20GET /api/x402/yield/asset?token=ETH What It Does Aggregates DeFi yield opportunities from 7 major protocols across all chains with risk scoring.
Top Yields
Filters
Risk Scoring
Protocols
Endpoint: /yield/top?minApy=5&limit=20Returns best yield opportunities with risk assessment: { "opportunities" : [ { "protocol" : "Lido" , "name" : "stETH Staking" , "asset" : "ETH → stETH" , "apy" : 3.2 , "tvl" : 30000000000 , "chain" : "ethereum" , "risk" : "LOW" , "type" : "staking" , "url" : "https://stake.lido.fi" }, { "protocol" : "Aave" , "name" : "USDC Supply" , "asset" : "USDC" , "apy" : 4.8 , "chain" : "ethereum" , "risk" : "LOW" , "type" : "lending" , "url" : "https://app.aave.com/reserve-overview/?underlyingAsset=0xa0b86991..." } ], "totalCount" : 347 , "fetchedAt" : "2026-03-03T10:40:00Z" }
Query Parameters:
chain: ethereum, polygon, arbitrum, optimism, baseminApy: Minimum APY percentage (e.g., 5)maxApy: Maximum APY percentagetype: staking, lending, vault, lp, fixedprotocol: lido, aave, yearn, curve, beefy, pendlelimit: Number of results (default 20) Example: GET /yield/top?chain=arbitrum & type = lending & minApy = 3 & limit = 10
Risk Levels:
Tier 1 protocols (Lido, Aave, Pendle)
$1B+ TVL
Multiple audits
Staking or lending yields
APY < 15%
Examples: Lido stETH (3.2%), Aave USDC (4.8%)
Tier 2 protocols (Yearn, Curve)
100 M − 100M- 100 M − Some audit history
APY 15-30%
Examples: Curve 3pool (7.5%), Yearn vaults (12%)
New or unaudited protocols
Less than $100M TVL
LP pools with impermanent loss risk
APY greater than 30% (likely unsustainable)
Examples: New farms, meme token LPsIntegrated Sources:
Lido - Ethereum staking (~$30B TVL)Aave - Multi-chain lending (~$12B TVL)Yearn - Automated vaults (~$500M TVL)Curve - Stablecoin LPs (~$2B TVL)Beefy - Multi-chain vaultsPendle - Fixed yield marketsTurtle - Yield aggregator See backend/src/services/yield-optimizer.ts for implementation. Data Sources: Direct protocol APIs + DeFiLlama yield aggregation
Tokenomics Agent
Tokenomics Analyzer Price: $0.02 per callAgent ID: tokenomicsEndpoints:
GET /api/x402/tokenomics/analyze?symbol=ARB What It Does Analyzes token supply, vesting schedules, unlock events, and allocation breakdowns for 200+ tokens.
Supply Analysis
Unlock Events
Allocations
Supported Tokens
Endpoint: /tokenomics/analyze?symbol=ARB{ "symbol" : "ARB" , "name" : "Arbitrum" , "supply" : { "circulating" : 2500000000 , "total" : 10000000000 , "max" : 10000000000 , "circulatingFormatted" : "2.50B" , "totalFormatted" : "10.00B" , "maxFormatted" : "10.00B" , "percentUnlocked" : 25.0 }, "inflation" : { "annualRate" : "~21.4%" , "fullyDilutedBy" : "~2029" } }
Next Unlock: { "nextUnlock" : { "date" : "2026-03-15" , "amount" : 92500000 , "amountFormatted" : "92.50M" , "percentOfCirculating" : 3.7 , "recipient" : "Team & Advisors" , "riskLevel" : "🟠 MEDIUM - Noticeable selling pressure likely" } }
Upcoming Schedule: { "upcomingUnlocks" : [ { "date" : "2026-03-15" , "amountFormatted" : "92.50M" , "percentOfCirculating" : 3.7 , "riskLevel" : "🟠 MEDIUM" }, { "date" : "2026-06-15" , "amountFormatted" : "185.00M" , "percentOfCirculating" : 7.4 , "riskLevel" : "🔴 HIGH - Major unlock" } ] }
Token Distribution: { "allocations" : [ { "category" : "DAO Treasury" , "percentage" : 42.78 }, { "category" : "Team & Advisors" , "percentage" : 26.94 }, { "category" : "Investors" , "percentage" : 17.53 }, { "category" : "Community (Airdrop)" , "percentage" : 11.62 } ] }
Hardcoded for Major Tokens:
Arbitrum (ARB)
Optimism (OP)
Polygon (MATIC/POL)
Sui (SUI)
Aptos (APT)
Celestia (TIA)
Monad (MON)
200+ Tokens Including: Layer 1/Layer 2:
Ethereum (ETH), Solana (SOL), Avalanche (AVAX)
Arbitrum (ARB), Optimism (OP), Polygon (MATIC)
zkSync (ZK), Starknet (STRK), Scroll (SCR)
DeFi:
Uniswap (UNI), Aave (AAVE), Curve (CRV)
Lido (LDO), MakerDAO (MKR), Compound (COMP)
New Projects:
Monad (MON), Berachain (BERA), Movement (MOVE)
Hyperliquid (HYPE), Sonic, Blur
See backend/src/services/tokenomics-service.ts for full list. Premium Agent: Charges $0.02 per call due to multiple API requests and complex data aggregation.
Data Sources: CoinGecko (supply data), Mobula (vesting schedules), hardcoded allocations for major tokens
NFT Agent
NFT Scout Price: $0.02 per callAgent ID: nftEndpoints:
GET /api/x402/scout/nft/:slugGET /api/x402/scout/search?q=pudgy+penguins What It Does Provides NFT collection analytics, floor prices, sales trends, and recent activity from OpenSea.
Collection Analytics
Recent Sales
Search Collections
Popular Collections
Endpoint: /scout/nft/boredapeyachtclub{ "slug" : "boredapeyachtclub" , "name" : "Bored Ape Yacht Club" , "description" : "The Bored Ape Yacht Club is a collection of 10,000 unique Bored Ape NFTs..." , "floor_price" : 32.5 , "floor_price_symbol" : "ETH" , "volume_total" : 1250000 , "num_owners" : 5834 , "market_cap" : 325000 , "image_url" : "https://..." , "opensea_url" : "https://opensea.io/collection/boredapeyachtclub" , "sales_trend" : "up" }
Included in Analytics Response: { "recent_sales" : [ { "nft_name" : "Bored Ape #1234" , "price" : 35.2 , "symbol" : "ETH" , "date" : "2026-03-03T09:45:00Z" , "tx_hash" : "0x..." }, { "nft_name" : "Bored Ape #5678" , "price" : 33.8 , "symbol" : "ETH" , "date" : "2026-03-03T08:30:00Z" , "tx_hash" : "0x..." } ] }
Sales Trend Algorithm:
Compare average of 3 most recent sales vs 7 older sales
up if recent avg > 5% higherdown if recent avg > 5% lowerneutral otherwise Endpoint: /scout/search?q=pudgyReturns matching collections: { "collections" : [ { "collection" : "pudgypenguins" , "name" : "Pudgy Penguins" , "slug" : "pudgypenguins" , "image_url" : "https://..." }, { "collection" : "lilpudgys" , "name" : "Lil Pudgys" , "slug" : "lilpudgys" , "image_url" : "https://..." } ] }
Smart Slug Fallback:
If OpenSea search fails, tries common slug patterns:
pudgypenguins (no spaces)pudgy-penguins (hyphenated)pudgy (partial match) Example Slugs:
boredapeyachtclub - Bored Ape Yacht Clubmutant-ape-yacht-club - MAYCazuki - Azukiclonex - CloneXcryptopunks - CryptoPunkspudgypenguins - Pudgy Penguinsdoodles-official - Doodlesproof-moonbirds - Moonbirds Use /scout/search?q=... if you’re unsure of the exact slug.
OpenSea API Key Required: This agent requires an OpenSea API key (set OPENSEA_API_KEY in backend .env).
Data Source: OpenSea API v2
Perp Agent
Perp Stats Price: $0.02 per callAgent ID: perpEndpoints:
GET /api/x402/perp/marketsGET /api/x402/perp/global What It Does Aggregates perpetual futures market data from 6 major decentralized exchanges.
Market Data
Global Stats
Supported Exchanges
Data Fields
Endpoint: /perp/marketsReturns all available perp markets: { "success" : true , "data" : [ { "exchange" : "Hyperliquid" , "symbol" : "BTC-USD" , "markPrice" : 97234.50 , "indexPrice" : 97230.25 , "fundingRate" : 0.0001 , "openInterestUsd" : 1250000000 , "volume24h" : 3200000000 , "priceChange24h" : 2.34 , "maxLeverage" : 50 , "url" : "https://app.hyperliquid.xyz/trade/BTC" }, { "exchange" : "dYdX" , "symbol" : "ETH-USD" , "markPrice" : 3456.78 , "fundingRate" : 0.00008 , "openInterestUsd" : 890000000 , "volume24h" : 1800000000 } ], "meta" : { "count" : 247 , "sources" : [ "Hyperliquid" , "dYdX" , "Paradex" , "Lighter" , "Pacifica" , "EdgeX" ] } }
Endpoint: /perp/globalAggregated market statistics: { "success" : true , "data" : { "totalVolume24h" : 8900000000 , "totalOpenInterestUsd" : 4200000000 , "activeExchanges" : [ "Hyperliquid" , "dYdX" , "Paradex" , "Lighter" , "Pacifica" , "EdgeX" ], "marketCount" : 247 } }
Integrated DEXs:
Largest on-chain perp DEX
100+ markets
Up to 50x leverage
Native L1 blockchain
Cosmos-based L1
50+ markets
Professional trading UI
Deep liquidity
StarkEx-based
40+ markets
Low fees
Minimalist design
Gas-efficient
Emerging protocol
Unique market structure
Partial support
Metadata only
Market Object: interface PerpMarket { exchange : string ; // "Hyperliquid" symbol : string ; // "BTC-USD" markPrice ?: number ; // Current mark price indexPrice ?: number ; // Index price (spot reference) fundingRate ?: number ; // 8-hour funding rate openInterestUsd ?: number ; // Total open interest in USD volume24h ?: number ; // 24h trading volume in USD priceChange24h ?: number ; // 24h price change % maxLeverage ?: number ; // Maximum leverage available url ?: string ; // Direct trading link }
Not all fields available from all exchanges. Missing fields return undefined.
Premium Agent: Charges $0.02 per call due to multiple exchange API requests and data normalization.
Data Sources: Direct APIs from Hyperliquid, dYdX, Paradex, Lighter, Pacifica, EdgeX
Agent Discovery How Gemini Selects Agents When a user asks a question, Gemini analyzes the intent and selects appropriate agents:
Intent Analysis
Gemini identifies keywords and intent:
Price/market → Oracle
Gas/wallet/on-chain → Scout
News/headlines → News
Yield/APY/staking → Yield
Supply/vesting/unlocks → Tokenomics
NFT/collection → NFT
Perp/futures/leverage → Perp
Multi-Agent Queries
Some queries need multiple agents:
“What’s ETH price and yield?” → Oracle + Yield
“BTC price and recent news” → Oracle + News
“ARB tokenomics and unlock schedule” → Tokenomics
Fallback Handling
If agent call fails:
Try alternative provider if available
Return partial response
Inform user which agents failed
Agent Health Monitoring The backend tracks agent performance:
Success Rate Percentage of successful calls (200-299 status)
Latency Average response time in milliseconds
Circuit Breaker Auto-disable after 3 consecutive failures
Dashboard View: { "agent" : "oracle" , "status" : "healthy" , "stats" : { "calls" : 1247 , "successes" : 1235 , "failures" : 12 , "successRate" : 99.04 , "avgLatencyMs" : 245 , "circuitOpen" : false }, "lastSeen" : "2026-03-03T10:45:00Z" }
Policy Controls Admins can control agent behavior via policy endpoints:
Freeze Agent
Spend Limits
Allowlists
View Policy
Temporarily disable an agent: POST /admin/policy/oracle/freeze x-admin-key: your-admin-key { "frozen" : true }
Frozen agents:
Reject all new calls with 403
Show “FROZEN” badge in dashboard
Can be reactivated by setting frozen: false
Set per-call and daily limits: PATCH /admin/policy/oracle x-admin-key: your-admin-key { "dailyLimitUsd" : "1.00", "perCallLimitUsd" : "0.05" }
Limits enforced before each agent call. Restrict endpoints and recipients: PATCH /admin/policy/oracle x-admin-key: your-admin-key { "endpointAllowlist" : [ "/api/x402/oracle/price" , "/api/x402/oracle/prices" ], "payToAllowlist" : [ "0xbaFF2E0939f89b53d4caE023078746C2eeA6E2F7" ] }
Calls to non-allowlisted endpoints are blocked. Get current policy: GET /admin/policy/oracle x-admin-key: your-admin-key { "agentId" : "oracle", "frozen" : false , "dailyLimitUsd" : "1.00", "perCallLimitUsd" : "0.05", "endpointAllowlist" : [...], "payToAllowlist" : [...], "updatedAt" : "2026-03-03T10:50:00Z" }
Cost Comparison Example Query Breakdown User Query: “What’s the price of Bitcoin, recent BTC news, and best yield for BTC?”Payment From To Amount Purpose 1️⃣ User Payment User Backend $0.03 Query processing 2️⃣ Oracle Call Backend Oracle Agent $0.01 BTC price 3️⃣ News Call Backend News Agent $0.01 BTC news 4️⃣ Yield Call Backend Yield Agent $0.01 BTC yield Total $0.06 End-to-end cost
Backend keeps 0.03 − 0.03 - 0.03 − $0.00 margin (covers Gemini API and infrastructure). Pricing Philosophy Why These Prices?
0.01 − 0.01- 0.01 − Transparent : Users see exactly which agents were calledSustainable : Agents cover their API costsIncentive-Aligned : Quality agents get more callsTestnet : Real pricing on testnet validates the model Future Agents Potential new agents for the marketplace:
Social Agent Track influencer sentiment, Twitter trends, Farcaster activity
Whale Tracker Monitor large wallet movements and exchange flows
MEV Agent MEV opportunities and sandwich attack alerts
DAO Agent DAO proposal tracking and governance analytics
Airdrop Scout Upcoming airdrops and eligibility checker
Bridge Agent Cross-chain bridge comparison and routing
Next Steps
x402 Protocol Learn how agents implement x402 payment endpoints
Payment Flow See how payments flow from users to agents
Architecture Understand the complete system architecture