Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: FarmDash Agent Strategy API
version: 2.0.0
description: 'WARNING: Running trade executions and cancellations places real perpetual futures trades and alters active market exposure, carrying significant risk of financial loss. Immediate, explicit manual end-user confirmation and consent is strictly required immediately before placing any execution or cancellation request. Do not allow autonomous agents to auto-run trade execution or cancellation without manual user approval. FarmDash is an intelligence and control layer for DeFi agents and serious airdrop farmers. This API covers swap transaction preparation (Signal Architect),
protocol discovery intelligence (Trail Heat), perpetual futures (Futures Strategist), portfolio
research, bounded autonomous sessions, x402 payment flows, and agent-readable opportunity intelligence. FarmDash does not request seed phrases or raw wallet private keys. Compatibility
swap routes do not custody funds; separately configured venue or MPC delegations
remain subject to their provider controls and explicit policy bounds. ## Authentication & Credential Lifecycle
| Tier | Price | Auth | Rate Limit | Key Prefix | Entitlements | Best for |
|------|-------|------|------------|------------|--------------|----------|
| Scout | Free | None | 30 req / 24 h per IP | `fd_scout_free` | Keyless public discovery and quotes | Keyless discovery and quotes |
| Pioneer | $39.99/mo USDC | `Authorization: Bearer ` | 1,500 req / day | `fd_pio_` | Premium research, full Trail Heat, wallet analytics, sybil audits | Serious farmers, full datasets, sybil audits, wallet analytics |
| Syndicate | $199/mo USDC | `Authorization: Bearer ` | 50,000 req / day | `fd_syn_` | All Pioneer features plus advanced control tooling, bounded autopilot, webhooks, unrestricted CORS | Teams, serious agents, high-volume API use, webhooks, unrestricted CORS, advanced control/session tooling |
### Paid Entitlement & Key Issuance Sequence:
1. **Pay**: Transfer USDC ($39.99/mo for Pioneer, $199/mo for Syndicate) on Base, Arbitrum, Optimism, Polygon, Ethereum, or Linea to the FarmDash treasury. 2. **Verify**: Post transaction hash and wallet to `verify-payment` to record on-chain confirmation in `users` and `payment_events`. 3. **Sign Proof**: Sign an EIP-712 `ApiKeyRequest` with the paying wallet (domain: `FarmDash`, intent: `Issue FarmDash API key`, single-use `nonce`). 4. **Receive Credential**: Post the signed payload to `/api/v1/agent/api-key`. The credential tier is server-authoritative, derived exclusively from your active paid subscription (client input cannot downgrade or elevate your tier). The plaintext key is returned exactly once; FarmDash stores only a SHA-256 hash. 5. **Authenticate**: Send `Authorization: Bearer ` on all requests. Daily limits reset every 24 hours (`X-RateLimit-Remaining`). Keys expire with your 30-day subscription; expired keys return HTTP 402 Payment Required. Higher-tier Syndicate capabilities (`advanced_control`) remain blocked for Pioneer subscribers. For SDK development without live data, use the deterministic sandbox on
the two endpoints that explicitly support it (`/v1/agent/protocols` and
`/v1/trail-heat`):
`?mock=true`, `X-FarmDash-Mock: true`, or `Authorization: Bearer fd_sandbox_mock`
Quote mock requests return typed `mock_not_supported` without contacting a live provider. Swap execution requires a fresh successful preflight simulation plus an EIP-191 agent wallet signature. Futures execution requires an EIP-712 Hyperliquid wallet signature. ## Dust Storm Protocol
On upstream failure, FarmDash returns `ok:false` with a typed degraded state
and a `warnings` array containing `{ kind: "dust_storm", message: "..." }`. Cached SDK responses may be returned as stale with explicit stale-data age. ## x402 Payment Wall
When Scout limits are exceeded, FarmDash returns HTTP 402 with
`code: free_quota_exhausted`, `instruction: STOP_RETRYING`, the UTC reset time,
upgrade URL, and x402 payment instructions.'
contact:
name: FarmDash Engineering
url: https://www.farmdash.one/agents
license:
name: MIT
servers:
- url: https://www.farmdash.one/api
description: Production
tags:
- name: Strategy
description: Strategy analysis and position sizing
paths:
/v1/agent/futures/analyze-strategy:
parameters:
- $ref: '#/components/parameters/X-FarmDash-Installation-ID'
- $ref: '#/components/parameters/X-FarmDash-Client'
- $ref: '#/components/parameters/X-FarmDash-Client-Version'
- $ref: '#/components/parameters/X-FarmDash-Skill-Version'
post:
operationId: analyzeStrategy
summary: Full research pipeline with adaptive strategy recommendation
description: 'Runs funding rates + technicals + order book liquidity + Trail Heat cross-ref.
Returns a structured strategy object, confidence score, market regime,
adaptive risk, portfolio context, pre-trade simulation, and explicit
no-trade outcomes when no setup is valid. Scout may claim one bounded research
result per durable free futures lifecycle (five per capital owner per UTC day),
with locally signed commercial identity or validated owner-bound delegated authority.
Paid Pioneer+ and eligible x402 admission remain available. This
registers analysis for a 60-second execution window that binds side, maximum size, entry drift, leverage metadata, and stop-derived risk.'
tags:
- Strategy
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- coin
- agentAddress
properties:
coin:
type: string
description: Asset symbol (ETH, BTC, SOL)
agentAddress:
type: string
pattern: ^0x[a-fA-F0-9]{40}$
riskMultiplier:
type: number
minimum: 0.1
maximum: 1.0
description: Optional flexibility modifier for risk tolerance. 1.0 keeps the full risk budget; lower values are more conservative.
accountAddress:
type: string
pattern: ^0x[a-fA-F0-9]{40}$
idempotencyKey:
type: string
maxLength: 128
executionTrialProof:
$ref: '#/components/schemas/ExecutionTrialProof'
executionMode:
type: string
enum:
- USER_SIGNED
- BOUNDED_AUTONOMOUS
sessionId:
type: string
grantId:
type: string
sessionToken:
type: string
parameters:
- $ref: '#/components/parameters/X-ClawHub-Skill'
responses:
'200':
description: Strategy recommendation
headers:
X-Request-ID:
$ref: '#/components/headers/X-Request-ID'
content:
application/json:
schema:
$ref: '#/components/schemas/AnalyzeStrategyResponse'
'400':
$ref: '#/components/responses/BadRequest'
'402':
$ref: '#/components/responses/PaymentRequired'
/v1/agent/futures/position-sizing:
parameters:
- $ref: '#/components/parameters/X-FarmDash-Installation-ID'
- $ref: '#/components/parameters/X-FarmDash-Client'
- $ref: '#/components/parameters/X-FarmDash-Client-Version'
- $ref: '#/components/parameters/X-FarmDash-Skill-Version'
post:
operationId: calculatePositionSize
summary: Position size calculator with guardrail enforcement
description: 'Given entry price, stop price, equity, and risk, returns exact position
size, leverage, and margin. All guardrails enforced server-side.
Pioneer+ required.'
tags:
- Strategy
security:
- bearerAuth: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PositionSizingRequest'
parameters:
- $ref: '#/components/parameters/X-ClawHub-Skill'
responses:
'200':
description: Position sizing result
headers:
X-Request-ID:
$ref: '#/components/headers/X-Request-ID'
content:
application/json:
schema:
$ref: '#/components/schemas/PositionSizingResponse'
'400':
$ref: '#/components/responses/BadRequest'
'402':
$ref: '#/components/responses/PaymentRequired'
components:
schemas:
FundingAnalysis:
type: object
properties:
coin:
type: string
fundingRate:
type: number
annualizedRate:
type: number
predictedRate:
type: number
crossVenueDelta:
type: number
premium:
type: number
openInterest:
type: number
isArbOpportunity:
type: boolean
arbDirection:
type: string
nullable: true
enum:
- long_spot_short_perp
- short_spot_long_perp
- null
StrategyRecommendation:
type: object
properties:
recommendedStrategy:
type: string
enum:
- funding_arb
- momentum_long
- momentum_short
- trend_pullback_long
- trend_pullback_short
- mean_reversion
- no_trade
confidence:
type: number
asset:
type: string
marketRegime:
$ref: '#/components/schemas/FuturesMarketRegime'
entry:
type: number
stopLoss:
type: number
takeProfit:
type: number
positionSize:
type: number
leverage:
type: number
maximum: 5
riskPercent:
type: number
maximum: 0.02
reasoning:
type: array
items:
type: string
noTradeReason:
type: string
nullable: true
strategyObject:
$ref: '#/components/schemas/FuturesStrategyObject'
adaptiveRisk:
$ref: '#/components/schemas/FuturesAdaptiveRisk'
simulation:
$ref: '#/components/schemas/FuturesTradeSimulation'
portfolioContext:
$ref: '#/components/schemas/FuturesPortfolioContext'
trailHeatCrossRef:
type: object
properties:
protocolId:
type: string
score:
type: number
farmingOpportunity:
type: boolean
referralLink:
type: string
format: uri
fundingAnalysis:
$ref: '#/components/schemas/FundingAnalysis'
indicators:
$ref: '#/components/schemas/TechnicalIndicators'
ExecutionContinuation:
type: object
additionalProperties: false
required:
- schema
- continuation_id
- source
- execution_domain
- network
- protocol_id
- assets
- action_kind
- lifecycle_id
- trail_id
- next_operation
- available_execution_modes
- authority
- prerequisites
- scout_trial
- expires_at
properties:
schema:
type: string
const: farmdash.execution-continuation.v1
continuation_id:
type: string
format: uuid
source:
type: object
additionalProperties: false
required:
- type
- ref
properties:
type:
type: string
enum:
- market_estimate
- solana_preview
- futures_analysis
ref:
type: string
maxLength: 128
execution_domain:
type: string
enum:
- spot
- solana
- futures
network:
type: string
protocol_id:
type:
- string
- 'null'
assets:
type: array
items:
type: object
additionalProperties: false
required:
- namespace
- network
- identifier
- kind
properties:
namespace:
type: string
enum:
- eip155
- solana
- hyperliquid
network:
type: string
identifier:
type: string
symbol:
type: string
kind:
type: string
enum:
- native
- wrapped_native
- token
- market
decimals:
type: integer
minimum: 0
maximum: 36
action_kind:
type: string
enum:
- swap
- prepare_order
lifecycle_id:
type: string
format: uuid
trail_id:
type:
- string
- 'null'
next_operation:
$ref: '#/components/schemas/ExecutionContinuationNextOperation'
available_execution_modes:
type: array
items:
type: string
enum:
- USER_SIGNED
- BOUNDED_AUTONOMOUS
authority:
type: string
const: NOT_GRANTED
prerequisites:
type: array
items:
type: string
scout_trial:
type: object
additionalProperties: false
required:
- exists
- domain
- daily_limit
- remaining
- status
- after_exhaustion
properties:
exists:
type: boolean
const: true
domain:
type: string
enum:
- spot
- futures
daily_limit:
type: integer
minimum: 0
maximum: 1000000
remaining:
type: 'null'
status:
type: string
enum:
- unknown
- evaluation_required
after_exhaustion:
type: string
const: authoritative_admission
expires_at:
type: string
format: date-time
FuturesAdaptiveRisk:
type: object
properties:
baseRiskPercent:
type: number
appliedRiskPercent:
type: number
confidenceMultiplier:
type: number
volatilityMultiplier:
type: number
drawdownMultiplier:
type: number
portfolioMultiplier:
type: number
finalRiskMultiplier:
type: number
PositionSizingResponse:
type: object
properties:
ok:
type: boolean
sizing:
$ref: '#/components/schemas/PositionSizing'
guardrails:
type: object
properties:
maxLeverage:
type: integer
maxRiskPerTrade:
type: string
maxPositionValue:
type: string
note:
type: string
timestamp:
type: integer
PositionSizing:
type: object
properties:
positionSize:
type: number
positionValueUsd:
type: number
leverage:
type: number
marginRequired:
type: number
riskAmount:
type: number
riskPercent:
type: number
stopDistance:
type: number
rewardRiskRatio:
type: number
DustStormWarning:
type: object
required:
- kind
- message
properties:
kind:
type: string
const: dust_storm
message:
type: string
FuturesTradeSimulation:
type: object
properties:
methodology:
type: string
enum:
- heuristic_preflight
holdingWindowHours:
type: number
entryValueUsd:
type: number
marginRequiredUsd:
type: number
marginImpactPct:
type: number
liquidationPriceEstimate:
type: number
nullable: true
stopScenarioPnlUsd:
type: number
targetScenarioPnlUsd:
type: number
oneAtrMovePnlUsd:
type: number
estimatedFundingPnl24hUsd:
type: number
estimatedFundingPnl72hUsd:
type: number
ErrorResponse:
type: object
required:
- error
properties:
ok:
type: boolean
example: false
error:
type: string
code:
type: string
message:
type: string
retryable:
type: boolean
request_id:
type: string
details:
type: object
additionalProperties: true
FuturesPortfolioContext:
type: object
properties:
openPositionCount:
type: integer
sameAssetExposureUsd:
type: number
sameAssetExposurePct:
type: number
directionalExposurePct:
type: number
netDirectionalBias:
type: string
enum:
- net_long
- net_short
- balanced
concentrationWarning:
type: string
nullable: true
PaymentRequiredError:
type: object
properties:
ok:
type: boolean
example: false
error:
type: string
example: payment_required
code:
type: string
description: '`free_quota_exhausted` when the shared Scout allowance is spent; otherwise `payment_required`.'
example: free_quota_exhausted
message:
type: string
instruction:
type: string
enum:
- STOP_RETRYING
description: Present when an exhausted free caller must not repeat the same unpaid request.
retry_same_request:
type: boolean
example: false
next_action:
type: string
example: Wait for your quota reset, upgrade your plan, or use x402 paid access.
quota:
type: object
properties:
tier:
type: string
example: scout
remaining:
type: integer
example: 0
reset_at:
type: string
format: date-time
abuse_notice:
type: string
example: Repeated automated requests while quota is exhausted may result in temporary or permanent API blocking.
retryable:
type: boolean
upgrade_url:
type: string
format: uri
direct_upgrade_url:
type: string
format: uri
rate_limit:
type: object
additionalProperties: true
developer_sandbox:
type: object
additionalProperties: true
payment_required:
type: object
properties:
amount:
type: string
example: 0.01 USDC
chain:
type: string
example: Base
destination:
type: string
example: '0xb0Ed0d7bca24BBaD635B977C2efbE06742e33377'
token:
type: string
chainId:
type: integer
example: 8453
ExecutionTrialProof:
type: object
required:
- issuedAt
- signature
description: Locally signed server-issued commercial identity challenge. Creates no transaction authority or delegation. Valid for five minutes. Never send private keys.
properties:
issuedAt:
type: integer
minimum: 1
signature:
type: string
ExecutionContinuationNextOperation:
type: object
additionalProperties: false
required:
- method
- endpoint
- parameters
- required_fields
properties:
method:
type: string
const: POST
endpoint:
type: string
enum:
- /api/v1/agent/quote-intent
- /api/agents/solana-swap
- /api/agents/futures/prepare-order
- /api/v1/agent/futures/prepare-order
parameters:
type: object
additionalProperties:
oneOf:
- type: string
- type: number
- type: boolean
required_fields:
type: array
items:
type: string
FuturesStrategyObject:
type: object
properties:
id:
type: string
type:
type: string
enum:
- futures
market:
type: string
direction:
$ref: '#/components/schemas/FuturesTradeDirection'
regime:
$ref: '#/components/schemas/FuturesMarketRegime'
triggerConditions:
type: array
items:
type: string
entryLogic:
type: string
exitLogic:
type: string
riskModel:
type: object
properties:
baseRiskPercent:
type: number
appliedRiskPercent:
type: number
riskMultiplier:
type: number
leverageCap:
type: number
stopModel:
type: string
leverageModel:
type: object
properties:
mode:
type: string
enum:
- adaptive
suggested:
type: number
cap:
type: number
drivers:
type: array
items:
type: string
fallbackLogic:
type: array
items:
type: string
telemetryTracking:
type: array
items:
type: string
FuturesMarketRegime:
type: string
enum:
- trending
- ranging
- high_volatility
- low_liquidity
AnalyzeStrategyResponse:
type: object
properties:
continuation:
$ref: '#/components/schemas/ExecutionContinuation'
next_operation:
$ref: '#/components/schemas/ExecutionContinuationNextOperation'
ok:
type: boolean
recommendation:
$ref: '#/components/schemas/StrategyRecommendation'
account:
type: object
properties:
equity:
type: string
availableMargin:
type: string
openPositions:
type: integer
guardrails:
$ref: '#/components/schemas/Guardrails'
timestamp:
type: integer
warnings:
type: array
items:
$ref: '#/components/schemas/DustStormWarning'
FuturesTradeDirection:
type: string
enum:
- long
- short
- neutral
Guardrails:
type: object
properties:
maxLeverage:
type: integer
example: 5
maxRiskPerTrade:
type: string
example: 2%
maxPositions:
type: integer
dailyLossLimit:
type: string
example: -3%
weeklyLossLimit:
type: string
example: -7%
maxDrawdown:
type: string
example: -15%
PositionSizingRequest:
type: object
required:
- equity
- entryPrice
- stopPrice
properties:
equity:
type: number
description: Account equity in USD
entryPrice:
type: number
stopPrice:
type: number
riskPercent:
type: number
maximum: 0.02
description: Capped at 2%
targetPrice:
type: number
description: For R:R calculation
riskMultiplier:
type: number
minimum: 0.1
maximum: 1.0
description: Optional flexibility modifier for risk tolerance. 1.0 keeps the full risk budget; lower values are more conservative.
TechnicalIndicators:
type: object
properties:
ema8:
type: number
ema34:
type: number
emaCross:
type: string
enum:
- bullish
- bearish
- neutral
rsi:
type: number
macd:
type: number
macdSignal:
type: number
macdHistogram:
type: number
macdCross:
type: string
enum:
- bullish_cross
- bearish_cross
- neutral
adx:
type: number
atr:
type: number
bbUpper:
type: number
bbMiddle:
type: number
bbLower:
type: number
bbWidth:
type: number
volumeRatio:
type: number
zScore:
type: number
parameters:
X-FarmDash-Client-Version:
name: X-FarmDash-Client-Version
in: header
required: false
description: Optional analytics client version; never security evidence.
schema:
type: string
maxLength: 64
pattern: ^[A-Za-z0-9._+-]{1,64}$
X-FarmDash-Skill-Version:
name: X-FarmDash-Skill-Version
in: header
required: false
description: Optional event-touch analytics skill version, alongside X-ClawHub-Skill; never security evidence.
schema:
type: string
maxLength: 64
pattern: ^[A-Za-z0-9._+-]{1,64}$
X-FarmDash-Installation-ID:
name: X-FarmDash-Installation-ID
in: header
required: false
description: Optional analytics-only locally generated UUIDv4 installation hint. Stored only as a domain-separated salted hash. Not authentication, principal proof, quota, payment, wallet ownership, delegation or transaction authority. Omission changes no functionality.
schema:
type: string
format: uuid
pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$
X-FarmDash-Client:
name: X-FarmDash-Client
in: header
required: false
description: Optional untrusted analytics client hint; never security evidence.
schema:
type: string
enum:
- mcp
- ts_agent_kit
- python_agent_kit
- public_client
- webapp
X-ClawHub-Skill:
name: X-ClawHub-Skill
in: header
required: false
schema:
type: string
pattern: ^[a-zA-Z0-9-]{1,128}$
example: farmdash-signal-architect
description: 'ClawHub skill attribution. An installed FarmDash skill sends its canonical skill slug (e.g. farmdash-signal-architect) on every FarmDash API request so anonymous Scout usage can be attributed to the skill that drove it. Optional and analytics-only: absence never blocks a request, and malformed values are ignored. This is a skill identity, never a wallet address, API key, or user ID.'
responses:
BadRequest:
description: Invalid parameters
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
PaymentRequired:
description: Free-tier limit exceeded — x402 payment required
headers:
X-Payment-Required:
schema:
type: string
X-Payment-Address:
schema:
type: string
description: Treasury wallet (USDC on Base)
X-Payment-Token:
schema:
type: string
description: USDC contract on Base
X-Payment-Amount:
schema:
type: string
description: Amount in token decimals (990000 = 0.99 USDC)
X-Payment-Chain-Id:
schema:
type: string
description: 8453 (Base)
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentRequiredError'
headers:
X-Request-ID:
description: Unique request trace ID for debugging and support
schema:
type: string
format: uuid
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: Pioneer or Syndicate API key
x-agent-use-cases:
- id: bounded-autopilot
name: Bounded Autopilot
tier: Syndicate
cadence: Every 5 minutes
purpose: Run an always-on loop inside explicit budgets, allowlists, cooldowns, quote freshness, and local-signing requirements.
primaryTools:
- agent_onboard
- create_session
- configure_autopilot
- autopilot_cycle
- session_heartbeat
stopConditions:
- Budget, allowlist, cooldown, quote freshness, or risk bound is violated.
- Required local EIP-191 or EIP-712 signature is missing.
- Realized performance degrades enough to require analysis_only mode.
- id: airdrop-rotation
name: Airdrop Rotation Desk
tier: Pioneer
cadence: Daily or event-driven
purpose: Watch Trail Heat, snapshots, multiplier changes, wallet health, and costs before entering, waiting, rotating, or exiting.
primaryTools:
- get_trail_heat
- get_historical_trailheat
- get_agent_events
- simulate_points
- get_swap_quote
- simulate_swap_execution
stopConditions:
- Expected point edge is unclear or negative after fees and gas.
- Sybil risk exceeds the configured threshold.
- User constraints do not allow the target chain or protocol.
- id: cross-chain-roi
name: Cross-Chain ROI Gate
tier: Pioneer
cadence: Before any bridge
purpose: Bridge only when net expected edge remains positive after bridge fee, gas, slippage, and execution risk buffer.
primaryTools:
- get_chain_breakdown
- get_wallet_balances
- get_token_prices
- get_swap_quote
- simulate_swap_execution
- optimize_portfolio
stopConditions:
- netEdgeUsd is not positive.
- Quote age exceeds the configured freshness limit.
- Target chain is not allowlisted.
- id: perps-hedge
name: Perps Hedge Co-Pilot
tier: Syndicate
cadence: Before exposure changes
purpose: Evaluate whether a farming position needs a Hyperliquid hedge, with no_trade as a valid outcome.
primaryTools:
- scan_funding_rates
- scan_market_conditions
- get_futures_account
- analyze_futures_strategy
- calculate_position_size
stopConditions:
- Research gate expires.
- Strategy confidence, liquidity, jurisdiction, or guardrails do not support execution.
# --- truncated at 32 KB (32 KB total) ---
# Full source: https://artifacts.apis.io/farmdash/openapi/farmdash-strategy-api-openapi.yml