FarmDash Agent Sandbox and SDK Guide: Mock Mode, Rate Limits, and Structured Errors

The Problem With Live-Only Development

Agent developers need to test:

• request wiring
• response parsing
• retry behavior
• rate-limit handling
• UI copy
• tool orchestration
• error fallbacks

Doing all of that against live DeFi data is expensive and noisy. It can also burn free-tier quota before the integration is ready.

FarmDash now has a cleaner development path:

1. call the public status endpoint
2. use mock mode for compatible read-only endpoints
3. inspect data_quality
4. handle structured errors
5. move to Scout live preview
6. upgrade or use x402 only when live data is needed

Start With the Status Endpoint

Call:

GET /api/v1/agent/status

or:

GET /api/v1/agent/feature-status

The response tells your agent:

• which surfaces are available
• which tier is required
• which endpoints support mock mode
• what error fields are stable
• how data confidence should be interpreted

This should be part of integration startup, not just a debugging tool.

Enable Mock Mode

Mock mode can be enabled with any of these:

GET /api/v1/agent/protocols?mock=true
GET /api/v1/trail-heat?mock=true
X-FarmDash-Mock: true
Authorization: Bearer fd_sandbox_mock

Mock responses return deterministic fixture data and include:

{
  "mode": "mock",
  "status": "sandbox",
  "data_quality": {
    "confidence": "demo",
    "mode": "mock"
  },
  "developer_sandbox": {
    "live_data": false,
    "not_for_trading": true
  }
}

Agent rule:

If confidence is demo, never present it as live DeFi intelligence and never pass it into an execution flow.

SDK Usage

The Agent Kit client can mark compatible read-only requests with the mock header:

import { FarmDashClient } from "@farmdash/agent-kit";

const client = new FarmDashClient({
  baseUrl: "https://www.farmdash.one/api",
  mockMode: true,
  retry: { retries: 0 }
});

const status = await client.getAgentStatus();
const protocols = await client.getProtocols();

The SDK intentionally does not apply the mock header to POST calls. That prevents write-capable or execution-adjacent paths from looking sandboxed.

Rate-Limit Metadata

FarmDash exposes rate-limit headers:

X-RateLimit-Limit
X-RateLimit-Remaining
X-RateLimit-Reset
X-Request-ID

The SDK surfaces those headers in meta:

const result = await client.getProtocols();

if (result.ok) {
  console.log(result.meta?.requestId);
  console.log(result.meta?.rateLimit?.remaining);
}

Agents should use this to avoid surprise failures. If remaining quota is low, the agent can ask whether to continue, switch to mock mode for non-live development, or prepare the user for an x402 overage.

Structured Error Handling

FarmDash errors are designed for machine parsing:

{
  "ok": false,
  "error": "rate_limit",
  "code": "rate_limit_exceeded",
  "message": "Scout daily limit exceeded.",
  "retryable": true,
  "request_id": "req_..."
}

The SDK preserves structured error bodies in error.details and avoids coercing nested objects into unreadable strings.

Recommended handling:

const response = await client.getProtocols();

if (!response.ok) {
  switch (response.error.code) {
    case "payment_required":
      // Present wait, x402, or upgrade options.
      break;
    case "rate_limit_exceeded":
      // Wait for reset or ask the user.
      break;
    case "feature_not_ready":
      // Do not fabricate. Fall back to lower-scope research.
      break;
    default:
      // Log requestId and give a safe explanation.
      break;
  }
}

Development Flow

Use this progression:

1. getAgentStatus() to learn the contract.
2. getProtocols() in mock mode to wire parsing.
3. /api/v1/trail-heat?mock=true to test ranking UI.
4. Scout live calls to verify real data shape.
5. Paid key or x402 only when live usage justifies it.
6. Execution skills only after user confirmation and local signing.

What Not To Do

Do not:

• use mock fixtures in production recommendations
• hide rate-limit errors from users
• retry non-retryable errors
• treat Trail Heat as a guaranteed outcome
• send private keys, seed phrases, or wallet exports
• hand read-only research directly to execution without user confirmation

Related FarmDash Docs

• Agent Data Confidence
• x402 Payment Fallback for DeFi APIs
• ClawHub Skill Safety Model