Agent Data Confidence: How FarmDash Labels Trail Heat, Mock Data, and API Limits

TLDR: Agent APIs should not pretend every answer has the same certainty. FarmDash now exposes data_quality, scoring_methodology, structured errors, and a public status endpoint so agents can tell the difference between live data, catalog-derived data, masked Scout previews, and deterministic mock fixtures.

Observed capability status (October 5, 2026): Spot and futures USER_SIGNED are server-labeled operational, not independently verified funded-transaction proofs. Both spot and futures BOUNDED_AUTONOMOUS are preparation_only. A valid owner policy, generic session, venue delegation, or paid tier cannot override that gate. USER_SIGNED requires fresh user authorization; bounded architecture requires a distinct explicit owner policy and customer-agent-local signature per action, plus all binding, scope, validity, risk/budget, and replay checks. FarmDash never receives the customer key.

Why Agents Need Confidence Labels

Human users can often spot uncertainty in a dashboard. Agents cannot. They need the API to say plainly:

• this field is live
• this field is catalog-derived
• this field is masked by tier
• this field is a mock fixture
• this method is heuristic, not statistically validated
• this endpoint is unavailable or missing dependencies

Without that contract, agents may overstate confidence, fabricate missing fields, or pass weak research into an execution tool.

FarmDash solves this by putting confidence metadata directly into agent-facing responses.

The Core Fields

data_quality

data_quality describes where the data came from and how much trust the agent should place in it.

Common confidence levels:

Example:

{
  "data_quality": {
    "confidence": "medium",
    "mode": "catalog",
    "sources": ["FarmDash curated protocol catalog"],
    "caveats": [
      "This record is catalog-derived.",
      "Trail Heat is a heuristic ranking signal and should be paired with risk, liquidity, and user-fit checks."
    ]
  }
}

scoring_methodology

scoring_methodology tells the agent how a score was generated.

Trail Heat responses identify whether they are:

• static-catalog-v1
• live-defillama-v1
• masked for Scout tier
• heuristic and not statistically validated

That last point matters. Trail Heat is a ranking signal, not a guaranteed yield model or allocation instruction.

developer_sandbox

developer_sandbox tells agent builders when a non-live mock mode exists.

FarmDash mock mode can be enabled with:

?mock=true
?mode=mock
X-FarmDash-Mock: true
Authorization: Bearer fd_sandbox_mock

The important constraint: mock mode is for compatible read-only development endpoints. It is not a trading simulator and must not be used for production recommendations.

How Trail Heat Responses Differ by Tier

Scout

Scout access is route-specific. The October 5, 2026 /api/v1/agent/protocols response was a truncated catalog preview: tier=scout, status=limited, count=3, masked_for_tier=true, and data_quality identifying catalog_preview, with encrypted numerical fields. It is not the full unmasked dataset or live quantitative Trail Heat. Eligible free routes still use the published quota; qualifying paid access follows each route policy.

Agent behavior:

• tell the user it is a preview
• do not invent masked values
• offer upgrade, x402 unlock, or a lower-scope answer

Pioneer and Syndicate

Paid tiers receive the full unencrypted dataset where the endpoint allows it.

Agent behavior:

• preserve asOf or timestamp context when available
• quote confidence labels in summaries
• keep Trail Heat separate from final execution decisions

Mock mode

Mock mode returns deterministic fixtures with confidence: "demo".

Agent behavior:

• use for SDK tests, onboarding, and integration flows
• never use for live DeFi recommendations
• never hand mock output to execution tools

The Public Status Endpoint

FarmDash exposes a public feature contract at:

/api/v1/agent/status
/api/v1/agent/feature-status

This endpoint gives agents:

• feature readiness
• tier gates
• structured error expectations
• data confidence rules
• scoring methodology versions
• mock-mode instructions

Agents should call this during setup, not after a failure.

Structured Errors Beat Guesswork

FarmDash agent errors use machine-readable fields so the caller can distinguish retryable transport/provider failures from policy, capability, quota, and payment states:

{
  "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_...",
  "rate_limit": {
    "tier": "scout",
    "used": 30,
    "limit": 30,
    "remaining": 0
  }
}

This lets SDKs and agents handle failures safely:

• retry only when retryable is true and the operation itself is safe to replay
• obey STOP_RETRYING and retry_same_request: false on exhausted unpaid access
• show request_id for support and correlation
• downgrade to mock mode only for development on routes that explicitly support it
• preserve stale/cached age instead of silently calling old data live
• avoid fabricating when a feature, provider, verifier, or authority prerequisite is not ready

Recommended Agent Rules

Use these rules in every FarmDash integration:

1. If confidence is demo, do not recommend or execute.
2. If confidence is low, ask for confirmation or gather more evidence.
3. If a field is masked, say it is masked.
4. If scoring is heuristic, do not describe it as a forecast.
5. If a 402 response appears, present wait, x402, and upgrade choices.
6. If the next step changes wallet state, hand off to the correct capability and require the authorization model published by live status: a fresh signature for supervised routes or an already-approved bounded session/delegation where that route explicitly supports it.
7. Never infer execution from tool discovery, preparation state, a submitted hash, or payment success.
8. Preserve request IDs, timestamps, provider identity, and evidence provenance when handing work between agents.

Why This Improves the Product

Data confidence is not just a compliance layer. It makes FarmDash more useful.

For users, it creates honest recommendations. For agents, it prevents brittle tool chains. For developers, it gives testable contracts. For FarmDash, it makes every API and MCP surface easier to monetize without overclaiming what the data can prove.

Related FarmDash Docs

• Trail Heat Methodology
• x402 Payment Fallback for DeFi APIs
• FarmDash Agent Hub Complete Manual