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

How to build against the FarmDash Agent API with deterministic mock mode, rate-limit metadata, public status contracts, and safer SDK error handling.

TLDR: Build your FarmDash integration against the public status endpoint and deterministic mock mode first. Mock mode is for explicitly supported read-only development endpoints, not execution. Treat retries as part of the safety model: read/idempotent operations may be retried according to the contract, while financial mutations must never be blindly replayed after an ambiguous failure.

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:

call the public status endpoint
use mock mode for compatible read-only endpoints
inspect data_quality
handle structured errors
move to Scout live preview
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.

Public read-only client versus source Agent Kit

Read-only public distribution observed October 5, 2026: @farmdash/client@1.0.0, dependency-free, Node.js 20+, source/license included, and tarball checksum matching the published .sha256 file.

npm install https://www.farmdash.one/downloads/farmdash-client-1.0.0.tgz
npx farmdash-report

This report client is not the signing Agent Kit or an MCP server. Archive retrieval does not mean installation or a funded transaction was tested. @farmdash/agent-kit@0.1.0 is a canonical source package; public npm and its documented historical source clone target returned 404 to unauthenticated reads. Whether private, moved, or deleted is not established. The source SDK example below requires an authorized checkout; public users can integrate through REST/OpenAPI. No key or seed phrase should be sent to FarmDash.

SDK Usage

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

// @farmdash/agent-kit is not published on npm.
import { FarmDashClient } from "./path/to/source-built/agent-kit/dist/index.js";

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 public package is not currently published on npm, so do not advertise an npm install @farmdash/agent-kit quickstart. Where the source SDK is available to your development environment, mock mode remains limited to routes that explicitly declare sandbox support. A POST method is not automatically unsafe and a GET method is not automatically live truth; use the route contract.

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 eligible non-live development, use an existing paid entitlement, or prepare the user for a route-specific x402 option. Once a 402 response says STOP_RETRYING, the unpaid request must not be looped automatically.

Structured Error Handling

FarmDash errors are designed for machine parsing:

{
  "ok": false,
  "error": "rate_limit",
  "code": "rate_limit_exceeded",
  "message": "Scout daily limit exceeded.",
  "instruction": "STOP_RETRYING",
  "retry_same_request": false,
  "retryable": false,
  "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:

getAgentStatus() to learn the contract.
getProtocols() in mock mode to wire parsing.
/api/v1/trail-heat?mock=true to test ranking UI.
Scout live calls to verify real data shape.
Paid key or x402 only when live usage justifies it.
Exercise execution-adjacent routes only after reading their live capability state.
For a financial mutation, test idempotency and ambiguous-failure recovery before allowing automatic retries.
Use the route-specific authorization model; do not assume every future execution mode requires a fresh signature or that an API key grants wallet authority.

What Not To Do

Do not:

use mock fixtures in production recommendations
hide rate-limit errors from users
retry non-retryable errors or replay a financial mutation after an ambiguous timeout without checking authoritative state
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