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

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 gets a limited live preview. Numeric fields may be masked.

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 are moving toward this shape:

{
  "ok": false,
  "error": "rate_limit",
  "code": "rate_limit_exceeded",
  "message": "Pioneer daily limit exceeded.",
  "retryable": true,
  "request_id": "req_...",
  "rate_limit": {
    "tier": "pioneer",
    "used": 501,
    "limit": 500,
    "remaining": 0
  }
}

This lets SDKs and agents handle failures safely:

• retry only when retryable is true
• show request_id for support
• downgrade to mock mode only for development
• avoid fabricating when a feature 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 execution skill and require a fresh user-local signature.

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