Signal Architect Complete Reference — Every Agent System in FarmDash Explained

TLDR: FarmDash Signal Architect is a zero-custody agent-to-agent swap routing layer. Autonomous agents authenticate with EIP-191 wallet signatures, get quotes from aggregated liquidity (Li.Fi, Relay; 0x operator-paused), and receive ready-to-sign calldata without handing over custody. x402 is the HTTP payment and access layer, never a swap router. The FarmDash agent-kit source package provides a typed TypeScript client with built-in retry, LRU caching, and Dust Storm resilience. This guide is the single reference for every agentic subsystem.

What is the Signal Architect?

The Signal Architect is FarmDash's non-custodial routing layer for autonomous agents. It sits between an agent (Eliza, LangChain, OpenClaw, or any HTTP client) and the underlying swap protocols. FarmDash never holds funds or keys. It returns EVM calldata that the agent signs and broadcasts on its own.

Layer	Role	Who Controls It
Agent (Eliza, LangChain, etc.)	Decides what to trade and when	The agent operator
Signal Architect API	Selects the best protocol, attaches the fee, returns calldata	FarmDash
Swap Protocol (Li.Fi, Relay; 0x operator-paused)	Executes the on-chain swap	The protocol's smart contracts
Blockchain	Settles the trade	The EVM network

The core design principle: FarmDash is the Matchmaker, not the Bank. The protocol executes the swap. FarmDash collects a fee haircut routed directly to the treasury wallet. No escrow, no custody.

How Does the Architecture Work?

Agent Wallet
    |
    |  EIP-191 signed POST /api/agents/swap
    v
Signal Architect API
    |
    +---> Agent Auth (verify EIP-191 signature + nonce)
    +---> Rate Limiter (20 req/60s per agent address)
    +---> Toll Booth (Scout / Pioneer / Syndicate tier check)
    +---> Route Selector (best net output within a 25bps band)
    +---> Fee Engine (attach 25-45bps based on volume)
    |
    v
Swap Protocol (Li.Fi / Relay; 0x paused)
    |
    v
txData returned to agent (never FarmDash custody)

What Are the API Endpoints?

FarmDash exposes core swap endpoints plus advanced intelligence and automation endpoints. All live under https://www.farmdash.one/api.

POST /api/agents/swap

The main swap execution endpoint. Requires EIP-191 authentication.

Request Body:

Field	Type	Required	Description
fromChainId	number	Yes	Source chain (e.g., 8453 for Base)
toChainId	number	Yes	Destination chain
fromToken	string	Yes	Source token address (0x...)
toToken	string	Yes	Destination token address
fromAmount	string	Yes	Amount in wei
agentAddress	string	Yes	Initiating agent wallet
toAddress	string	Yes	Receiving wallet
signature	string	Yes	EIP-191 signature of the payload
nonce	string	Yes	Timestamp nonce (ms)
slippage	number	No	Slippage tolerance 0.01-5 (default 0.5%)
protocol	string	No	Force a specific provider (lifi, zerox, relay; deterministic, never silent fallback; forcing paused 0x returns provider_paused)

Response: A SwapQuote object containing txData (calldata ready for the agent to sign and broadcast), estimatedOutput, feeBps, feeAmountUSD, gasEstimate, and expiresAt (30 second TTL).

GET /api/v1/agent/market-estimate

Provider-neutral discovery estimate for browsing, previews, and walletless exploration. Makes zero 0x/LI.FI/Relay trading calls. Never executable, never attributed.

Query Parameters: fromChainId, toChainId, fromToken, toToken, fromAmount.

POST /api/v1/agent/quote-intent

Explicit execution intent. Requires exact chain pair, token pair, amount, real walletAddress, destination, slippage, and an idempotencyKey. Contacts exactly one primary provider (sequential alternate only on genuine failure); identical intents reuse the stored firm quote. The firm quote flows through simulate, approval, and prepare without further provider quote requests.

GET /api/agents/quote

Discovery default: serves the provider-neutral market estimate — a supplied wallet alone never triggers provider quoting. With an intentId plus identical parameters, serves the stored firm quote with zero new provider calls.

Preview a swap quote without authentication. Useful for agents to compare pricing before committing to a signed request.

Query Parameters: fromChainId, toChainId, fromToken, toToken, fromAmount, and optionally protocol or intentId.

GET /api/agents/history

Query fee event history and aggregate metrics. Supports pagination.

Query Parameters: agentAddress (optional filter), limit (default 50, max 200), offset. Add ?metrics=true for aggregate revenue dashboard.

GET /api/v1/agent/protocols

Returns the ranked protocol dataset with Trail Heat scores. Response depends on the caller's tier (Scout gets top 3 with masked numbers, paid tiers get the full dataset).

Advanced intelligence endpoints

• GET /api/v1/agent/chain-breakdown
• GET /api/v1/agent/sybil-audit
• POST /api/v1/agent/simulate-points
• POST /api/v1/agent/optimize-portfolio
• GET /api/v1/agent/historical-trailheat
• GET /api/v1/agent/events
• GET|POST|DELETE /api/v1/agent/webhooks
• GET|POST /api/v1/agent/intent

Premium endpoints return a structured 503 feature_not_ready response if their backing infrastructure has not been provisioned in the current deployment yet.

How Does EIP-191 Authentication Work?

Unlike traditional APIs that require hardcoded API keys, the Signal Architect uses cryptographic wallet signatures. This is critical for autonomous agents because it means no secrets need to be stored in environment variables or passed through untrusted networks.

Step 1: The agent constructs a deterministic payload string:

v1:FARMDASH_SWAP:{fromChainId}:{toChainId}:{fromToken}:{toToken}:{fromAmount}:{agentAddress}:{toAddress}:{nonce}

All addresses must be lowercase. The nonce is the current timestamp in milliseconds.

Step 2: The agent signs this string using personal_sign (EIP-191) with its own private key.

Step 3: FarmDash reconstructs the same payload, recovers the signer address from the signature, and verifies it matches the claimed agentAddress.

Step 4: The nonce is validated against a 60-second window to prevent replay attacks. If the nonce is stale or from the future, the request is rejected.

This approach means agents never need to share private keys with FarmDash, and every request is cryptographically bound to the wallet that initiated it.

⚡ Solana On-Chain Verification

Unlike EVM transaction checking, which queries simple binary status codes, FarmDash's Signal Architect queries Solana transaction metadata directly using the @solana/web3.js Connection.

1. DDoS & RPC Protection: Transaction receipt queries are routed through a highly optimized LRU cache (capped at 500 records with a 10-minute TTL) to safeguard endpoints from rate-limiting during agent retries.
2. Graceful Network Failures: RPC lookups enforce a strict 10-second AbortSignal timeout to prevent serverless processes from hanging, reporting clean timeout exceptions back to the agent.
3. Strict Status Inspection: The verify logic explicitly checks the meta.err object in the Solana transaction receipt to accurately flag and reject reverted transactions, ensuring absolute fee accuracy.

How Does Protocol Routing Work?

The Route Selector picks the optimal swap protocol based on chain topology:

Condition	Protocol Selected	Why
Both chains are Base (8453)	Li.Fi (or Relay)	Deep EVM liquidity on active routes
Different source and destination chains	Li.Fi or Relay	Native bridging; the router picks the best net output

Same-chain trades on any supported EVM chain use the same active-route selection. 0x is configured but operator-paused and is never auto-selected.

Agents can override this by passing protocol in the request body, but the automatic selection covers the optimal path for the vast majority of trades. x402 is never a routing choice: it is the HTTP payment and access layer (HTTP 402 overage proofs), not a liquidity venue.

Built-in fallback: If the primary provider fails (e.g., Li.Fi is degraded), the router retries with the remaining active provider (Li.Fi or Relay) when compatible; 0x is configured but operator-paused and is never auto-selected.

How Does the Fee Engine Work?

FarmDash attaches a percentage-based fee to each swap. The fee is routed directly to the FarmDash treasury wallet by the underlying protocol, never held in escrow. The canonical fee and commercial disclosure page is farmdash.one/fees.

Volume-Based Fee Discounts

The fee engine supports volume-based tiering. FarmDash derives the trade value from the selected quote and calculates the applicable tier server-side:

Trade Volume (USD)	Fee Rate	Savings vs Standard
Under $10,000	50 bps (0.50%)	Standard rate
$10,000 - $99,999	45 bps (0.45%)	10% discount
$100,000 - $999,999	40 bps (0.40%)	20% discount
$1,000,000+	30 bps (0.30%)	40% discount

Combined routing target (FarmDash + configured provider platform component; LI.FI's 25 bps is deducted, not stacked). Gas, slippage, price impact, bridge/liquidity costs, and token mechanics are separate.

The quote response discloses the applied feeBps and feeAmountUSD. Clients cannot unlock a discount by self-reporting volume.

The default fee rate can also be overridden globally via the FARMDASH_TARGET_ROUTING_FEE_BPS environment variable.

What is the Toll Booth Tier System?

All API endpoints pass through a toll booth that determines the caller's access level. FarmDash uses three tiers:

Scout (Free Tier)

• Rate limit: 30 requests per 24 hours (IP-based via Upstash Redis)
• Data access: Top 3 protocols only, numerical values masked
• Authentication: None required
• CORS: Open (*)
• After limit exceeded: Returns HTTP 402 with x402 payment headers

Pioneer (Paid Tier)

• Rate limit: 1,500 requests per 24 hours (API key via Authorization: Bearer)
• Data access: Full unmasked dataset
• Authentication: FARMDASH_PIONEER_KEY env var
• CORS: Restricted to farmdash.one origins only
• After limit exceeded: Returns HTTP 429

Syndicate (Operator Tier)

• Rate limit: 50,000 requests per 24 hours (API key)
• Data access: Full dataset, webhooks, unrestricted CORS, advanced session/control tooling
• Authentication: FARMDASH_SYNDICATE_KEY env var
• CORS: Open (*) for full programmatic access
• After limit exceeded: Returns HTTP 429

The x402 Payment Wall

When Scout tier is exhausted, the API returns HTTP 402 with payment headers that conform to the emerging x402 protocol standard:

Header	Value	Purpose
X-Payment-Required	true	Signals payment is needed
X-Payment-Address	Treasury wallet	Where to send payment
X-Payment-Token	USDC on Base	Payment denomination
X-Payment-Amount	Amount in wei	Cost per request
X-Payment-Chain-Id	8453	Base chain

This enables agents with x402 support to automatically pay for continued access without human intervention.

What is the agent-kit SDK?

The FarmDash agent-kit source package is a typed TypeScript SDK that wraps read endpoints with built-in retry logic, caching, and graceful failure handling. It is designed for agents that need a reliable client without rebuilding request logic from scratch.

Public Client Integration

FarmDash does not currently advertise a public agent-kit package or public source checkout. Generate a client from the canonical OpenAPI contract, and use the public Agent Hub for current endpoint, signing, and payment guidance.

API Capabilities

Method	Endpoint	Description
getProtocols()	GET /v1/agent/protocols	Ranked protocol dataset with Trail Heat scores
getQuote(params)	GET /agents/quote	Preview swap pricing without authentication
getSwapHistory(params)	GET /agents/history	Fee event history with pagination
getRevenueMetrics()	GET /agents/history?metrics=true	Aggregate fee/volume/swap/agent counts
getChainBreakdown()	GET /v1/agent/chain-breakdown	Protocol distribution across chains
auditSybilRisk()	GET /v1/agent/sybil-audit	Wallet cluster risk scoring
simulatePoints()	POST /v1/agent/simulate-points	FarmScore what-if projection
optimizePortfolio()	POST /v1/agent/optimize-portfolio	Ranked reallocation suggestions
getHistoricalTrailHeat()	GET /v1/agent/historical-trailheat	Trend snapshots
getAgentEvents()	GET /v1/agent/events	Event polling
subscribeWebhook() / listWebhooks()	`POST	GET /v1/agent/webhooks`

All methods return an ApiEnvelope<T> with ok: true/false, typed data, optional warnings, and meta (including cache status and ETag).

How Does Dust Storm Resilience Work?

When the network fails (timeout, DNS error, etc.), the SDK does not throw. Instead it returns a successful envelope with an empty data shape and a dust_storm warning:

{
  ok: true,
  data: { tier: 'scout', count: 0, data: [] },
  warnings: [{ kind: 'dust_storm', message: 'network_error' }],
  meta: { cached: false }
}

This prevents autonomous agents from crashing on transient network failures. The agent can check for warnings and decide whether to retry, use stale cache, or skip the operation.

How Does Caching Work?

The SDK supports three cache modes:

Mode	Storage	Best For
memory	In-process Map with LRU eviction (max 256 entries)	Server-side agents, short-lived processes
idb	Browser IndexedDB via idb-keyval	Browser-based agents, persistent cache
none	No caching	Testing, real-time requirements

The memory cache uses LRU (Least Recently Used) eviction to prevent unbounded growth. When the cache exceeds 256 entries, the oldest unused entries are dropped first. Cache entries are also validated using ETag headers: when the server returns HTTP 304 (Not Modified), the cached data is returned and its freshness timestamp is refreshed automatically.

How Does Retry Logic Work?

All HTTP requests go through an exponential-backoff retry layer with jitter:

Setting	Default	Description
retries	3	Maximum retry attempts
baseDelayMs	250	Initial delay before first retry
maxDelayMs	2500	Maximum delay cap
jitter	0.2	Random variance to prevent thundering herd
retryOnStatuses	408, 429, 500, 502, 503, 504	HTTP codes that trigger retry

These defaults can be overridden via the retry option in the client constructor.

SDK Type Exports

The SDK exports all relevant types for consumers building typed integrations:

import type {
  ApiEnvelope,
  ApiOkEnvelope,
  ApiErrorEnvelope,
  ChainBreakdownItem,
  ChainBreakdownItemFull,
  ChainBreakdownItemScout,
  ChainBreakdownResponse,
  ChainBreakdownSummary,
  ChainBreakdownSummaryFull,
  ChainBreakdownSummaryScout,
  DustStormWarning,
  FeeEvent,
  HistoryParams,
  HistoryResponse,
  ProtocolItem,
  ProtocolsResponse,
  QuoteParams,
  QuoteResponse,
  RevenueMetrics,
  SupportedProtocol,
  SwapTxData,
  Tier,
  CacheMode,
  CachedValue,
  RetryOptions,
  FarmDashClientOptions,
} from '@farmdash/agent-kit';

What is Trail Heat?

Trail Heat is FarmDash's 0-100 scoring system that ranks protocols by opportunity. The API endpoint (GET /api/v1/agent/protocols) returns Trail Heat scores for all tracked protocols. Live scoring uses four 100% quantitative factors when upstream data is available, with human editorial notes isolated in metadata:

Factor	Calculation	Max Contribution
TVL Scale	Calibrated DeFiLlama TVL curve: $1M ~= 10/40, $1B+ ~= 40/40	40 points
Momentum	Seven-day TVL movement relative to neutral baseline	25 points
Chain Diversification	DeFiLlama chain distribution; single-chain live protocols receive a neutral baseline	15 points
Category Outperformance	Protocol TVL compared with category baselines across sectors	10 points
Editorial Notes	Descriptive catalog notes and flags (isolated from score)	0 points (Metadata)

The raw quantitative sum (90 pts max) is rescaled to a 0–100 headline score. Static tracker pages use a lighter calibrated catalog fallback: TVL, status, category prior, hot momentum, and recency. Treat static scores as deploy-time SEO context and live API scores as the fresher operational signal.

Each protocol in the API response includes: protocol_name, trail_heat_score, sybil_risk catalog label, tvl, category, status, chains, and recommended_agent_deploy_link. A value such as Not assessed means no wallet-level Sybil audit has been run for that protocol row.

How Does Rate Limiting Work?

The swap endpoint (POST /api/agents/swap) has its own per-agent rate limiter separate from the toll booth:

• Limit: 20 requests per 60-second sliding window per agent address
• Scope: Per serverless instance (in-memory). For distributed limiting, upgrade to Redis.
• Response on limit: HTTP 429 with Retry-After header and retryAfterMs in the body

This is per-agent, not per-IP. It uses the agentAddress from the request body as the key, normalized to lowercase.

How Does Input Validation Work?

All endpoints validate inputs using a shared validation module. The following checks are enforced on the swap endpoint:

Field	Rule	Error
agentAddress, toAddress, fromToken, toToken	Must be 0x + 40 hex characters	"Invalid {field}"
fromAmount	Must be a non-zero, non-leading-zero digit string (wei)	"Invalid fromAmount (must be non-zero wei string)"
fromChainId, toChainId	Must be numbers	"Invalid chainId (must be number)"
signature	Must be 0x + hex string	"Invalid signature"
nonce	Must be a non-empty string	"Missing nonce"
slippage	Must be 0.01 to 5 (if provided)	"Invalid slippage (must be 0.01-5)"

The quote endpoint runs the same address and amount validations but does not require signature, nonce, or slippage.

How Does the Fee Event Logger Work?

Every executed swap logs a fee event to a Supabase fee_events table using a fire-and-forget pattern. The logger never blocks the swap response. If the write fails, it logs to console.error and moves on.

Logged fields: protocol, from_token, to_token, volume_usd, fee_bps, fee_usd, agent_address, tx_hash.

The revenue metrics endpoint aggregates these events server-side using a Supabase RPC function for efficient aggregation without transferring raw data to the edge.

Frequently Asked Questions?

What frameworks does the Signal Architect support?

Any framework that can make HTTP requests works. The API is a standard REST API. The FarmDash agent-kit source package provides a typed TypeScript client, and the Eliza framework has a dedicated Action implementation. OpenClaw agents can use the published raw FarmDash skill files at /openclaw-skills/.../SKILL.md.

Does FarmDash ever hold custody of agent funds?

FarmDash does not receive or store customer private keys. After wallet-bound simulation and signature verification, FarmDash returns EVM calldata for the customer's client to review and broadcast. Service authentication and evaluator credentials are separate operational secrets.

How do volume-based fee discounts work?

FarmDash derives the value from the selected quote. The configured fee is 50 bps below $10,000, 45 bps from $10,000, 40 bps from $100,000, and 30 bps from $1,000,000. The quote discloses the applied rate before authorization.

What happens when a swap protocol is down?

The fee engine has built-in fallback logic. If the primary provider fails, it retries with the remaining active provider (Li.Fi or Relay) when one is compatible with the trade; otherwise the failure propagates as a machine-readable error. 0x is configured but operator-paused, so automatic routing never selects it.

How does the SDK handle network failures?

The SDK uses the Dust Storm pattern: instead of throwing exceptions, it returns ok: true with empty data and a dust_storm warning. This prevents agent crashes during transient outages and gives the agent the option to retry or degrade gracefully.

What is the nonce window for replay protection?

The nonce must be a timestamp within 60 seconds of the server's current time. Nonces from the future or older than 60 seconds are rejected. This prevents intercepted requests from being replayed.

Can agents force a specific swap protocol?

Yes. Pass protocol: 'lifi', protocol: 'zerox', or protocol: 'relay' in the swap request body (deterministic — a forced provider is attempted alone, never silently replaced; forcing paused 0x returns a provider_paused error). If omitted, automatic multi-provider routing quotes all healthy compatible providers in bounded parallel — same-chain LI.FI + Relay, cross-chain LI.FI + Relay — and returns the best executable route with machine-readable attempts[] evidence.

How do I access Trail Heat data programmatically?

Use client.getProtocols() from the FarmDash agent-kit source package or call GET /api/v1/agent/protocols directly. Free tier returns the top 3 protocols with masked numbers. Paid tiers return the full ranked dataset.

Related Guides

• How to Build an Eliza Trading Agent with FarmDash
• Trail Heat Methodology
• Publishing AEO-Optimized Content on FarmDash