Farmdash Signal Architect

name: FarmDashSignalArchitect description: "Non-custodial agent-to-agent swap router API. Execute single-chain and cross-chain token swaps with zero custody via FarmDash." version: "1.1.0" author: "FarmDash Pioneers" tools: [curl, python, node] icon: 🚜

Instructions for Agent Use

You are equipped with the FarmDash Signal Architect skill. This allows you to request swap quotes and execute non-custodial token swaps on behalf of the user.

Authentication & Keys

1. Free Tier: You do not need an API key to request quotes via GET /api/agents/quote.
2. Paid Tiers (Optional): If the user provides FARMDASH_PIONEER_KEY or FARMDASH_SYNDICATE_KEY in the environment variables, use it in the Authorization: Bearer <key> header for higher rate limits on data endpoints.
3. Execution Auth: To actually execute a swap (POST /api/agents/swap), you must use EIP-191 signatures. You never send the user's private key. You sign a payload locally and send the signature.

Endpoints

Base URL: https://farmdash.one/api

1. Get a Swap Quote (Free)

Use this to preview a swap before committing.

curl -X GET "https://farmdash.one/api/agents/quote?fromChainId=8453&toChainId=8453&fromToken=0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913&toToken=0x4ed4e862860bef6f5bc2b489d12a64703a110a12&fromAmount=1000000"

2. Execute a Swap (Authenticated)

To execute, you must construct and sign a payload locally. Payload Format: FARMDASH_SWAP:{fromChainId}:{toChainId}:{fromToken}:{toToken}:{fromAmount}:{agentAddress}:{toAddress}:{nonce} Note: All addresses must be lowercase. Nonce is the current timestamp in milliseconds.

Sign this string using the agent's own EVM private key (personal_sign / EIP-191), then send:

curl -X POST "https://farmdash.one/api/agents/swap" \
     -H "Content-Type: application/json" \
     -d '{
       "fromChainId": 8453,
       "toChainId": 8453,
       "fromToken": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
       "toToken": "0x4ed4e862860bef6f5bc2b489d12a64703a110a12",
       "fromAmount": "1000000",
       "agentAddress": "0xYourWallet...",
       "toAddress": "0xDestinationWallet...",
       "nonce": "1709000000000",
       "signature": "0xTheSignatureYouGenerated...",
       "volumeHintUSD": 50000
     }'

Optional fields:

• slippage (number): Slippage tolerance in percent (0.01-50, default 0.5)
• volumeHintUSD (number): Agent-supplied USD estimate of the trade. Unlocks volume fee discounts: $10k+ = 35bps, $100k+ = 25bps (standard: 75bps)
• protocol (string): Force a specific protocol (lifi, zerox, x402). Omit for automatic optimal routing.

3. View Fee History

curl -X GET "https://www.farmdash.one/api/agents/history?agentAddress=0xYourWallet&limit=50&offset=0"

4. View Revenue Metrics (Aggregate)

curl -X GET "https://www.farmdash.one/api/agents/history?metrics=true"

Returns totalFeeUSD, totalVolumeUSD, totalSwaps, and activeAgents.

5. Get Trail Heat Protocol Data

curl -X GET "https://farmdash.one/api/v1/agent/protocols"

Returns ranked protocol dataset with Trail Heat scores. Free tier: top 3 with masked numbers. Paid tiers: full dataset.

6. Get Chain Breakdown (Paid Tiers)

curl -X GET "https://farmdash.one/api/v1/agent/chain-breakdown" \
     -H "Authorization: Bearer $FARMDASH_PIONEER_KEY"

Returns protocol distribution across chains: protocol_count, pct_of_total, confirmed_airdrops, points_programs, and categories per chain. Free (Scout) tier receives the top 3 chains with numeric fields masked. Paid tiers receive the full dataset.

Data Sources & Accuracy

FarmDash integrates with multiple data providers to ensure accurate, real-time information:

• DeFiLlama API: Canonical source for TVL, fees, and protocol metrics
• Alchemy API: Multi-chain token balances and prices
• 0x Protocol: DEX aggregation and routing
• Li.Fi: Cross-chain bridge routing
• Helius: Solana ecosystem data

All data is cached hourly and validated against multiple sources to prevent "dust storms" (data inconsistencies).

Handling Errors & Rate Limits

• If you receive a 429 Too Many Requests, check the Retry-After header and wait.
• If you receive a 402 Payment Required, the free tier limit is exhausted. Inform the user they need to upgrade to Pioneer/Syndicate or pay the micro-fee via the x402 protocol.
• If you receive a 401 Unauthorized, your signature payload is malformed or the nonce is expired (60s window).

Best Practices

• Never expose private keys in the API request.
• Always use the quote endpoint first to verify liquidity and slippage before asking the user for permission to execute.
• All amounts are in Wei format (e.g., 1 USDC = 1000000).
• All token and wallet addresses must be valid 0x + 40 hex character format.
• Slippage must be between 0.01 and 50 (percent). Default is 0.5%.
• For high-value trades, include volumeHintUSD to unlock lower fees (35bps at $10k+, 25bps at $100k+).
• Data Freshness: TVL and protocol metrics update hourly via DeFiLlama API for maximum accuracy.

Error Handling

All error responses are JSON objects with an error string field. Common scenarios and the HTTP status they return:

Always surface the error field value to users — the messages are designed to be actionable.